Created Creating Your First Device in Home Assistant - ESPHome (markdown)
Dave Williams | DitroniX | G8PUO
@@ -0,0 +1,181 @@
|
|||||||
|
## Congratulations
|
||||||
|
|
||||||
|
You now have a board which you are excited to add to Home Assistant. So let's get started.
|
||||||
|
|
||||||
|
Note: This is a step by step guide, so please follow the prompts where needed.
|
||||||
|
|
||||||
|
### Top Level
|
||||||
|
|
||||||
|
- Use Home Assitant **ESPHome** to Create and Maintain Devices
|
||||||
|
- Use existing **External Component**(s). (Think of these as libraries.)
|
||||||
|
- **Create Device**
|
||||||
|
- Paste or Edit **YAML code**
|
||||||
|
- **Add new Device to Dash**
|
||||||
|
|
||||||
|
### Preliminary Information on the Basics!
|
||||||
|
|
||||||
|
#### How Does It Work?
|
||||||
|
|
||||||
|
Using Home Assistant, with integrated ESPHome, you are easily able to create a new 'Device', then flash the board so it will then appear in your Dashboard > Devices.
|
||||||
|
|
||||||
|
Home Assistant (ESPHome), devices use .yaml code, which is initially flashed to the board via USB cable.
|
||||||
|
|
||||||
|
Once flashed (so the board is 'talking' to Home Assistant'), you can then subsequently easily reflash to the board using OTA, Over-The-Air, via Wi-Fi. USB re-flashing remains an option if needed.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
#### Home Assistant (ESPHome) Devices
|
||||||
|
|
||||||
|
Home Assistant (ESPHome), uses '[Components](https://developers.home-assistant.io/docs/creating_component_code_review/)', which configures and tells Home Assistant about the device which you are trying to add.
|
||||||
|
|
||||||
|
Two 'flavours' of components are available (as far as I am aware):
|
||||||
|
* Internal Components (embedded into HA)
|
||||||
|
* External Components (This is a custom component, not currently embedded into HA)
|
||||||
|
|
||||||
|
DitroniX External Components are located in
|
||||||
|
[https://github.com/DitroniX/Home-Assistant-Dev/tree/main/components](https://github.com/DitroniX/Home-Assistant-Dev/tree/main/components)
|
||||||
|
|
||||||
|
#### DitroniX Component Development
|
||||||
|
|
||||||
|
During DitroniX Home Assistant Code Development, the required device 'Component', is simply connected to the DitroniX git repository, as an external component.
|
||||||
|
|
||||||
|
|
||||||
|
You could of course, always 'clone' this component and make your own.
|
||||||
|
|
||||||
|
The below is an example of the source pointing to the git repository.
|
||||||
|
|
||||||
|
- source:
|
||||||
|
type: git
|
||||||
|
url: [https://github.com/DitroniX/Home-Assistant-Dev]
|
||||||
|
(https://github.com/DitroniX/Home-Assistant-Dev)
|
||||||
|
|
||||||
|
### Get Programming!
|
||||||
|
|
||||||
|
#### Initial Basics
|
||||||
|
|
||||||
|
This basic tutorial assumes you already the following installed and configured (links provided is not).
|
||||||
|
|
||||||
|
- [Home Assistant](https://www.home-assistant.io/installation/) [x86-64](https://www.home-assistant.io/installation/generic-x86-64/)
|
||||||
|
- [ESPHome](https://esphome.io/guides/getting_started_hassio/)
|
||||||
|
|
||||||
|
### Adding a Device
|
||||||
|
|
||||||
|
You will be using [ESPHome](https://esphome.io/guides/getting_started_hassio/) to add a device and integrate is to Home Assistant.
|
||||||
|
|
||||||
|
ESPHome allows you to create device 'configurations' which in turn adds common microcontrollers into smart home devices.
|
||||||
|
|
||||||
|
#### Open ESPHome Builder
|
||||||
|
|
||||||
|
Assuming you have added ESPHome device builder to your left menu bar within Home Assistant, simply click 'ESPHome Builder'
|
||||||
|
|
||||||
|
#### Secrets
|
||||||
|
|
||||||
|
ESPHome configuration for a device lives in a .yaml file. Within this yaml file, you can add a whole range of device configuration information, the most common between devices is your Wi-Fi setup information.
|
||||||
|
|
||||||
|
If not already configured, I would recommend you setup your 'secrets' file. Withn yaml, this is `<<: !include ../secrets.yaml`
|
||||||
|
|
||||||
|
To configure the secrets file, you need to
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
Edit the Wi-Fi settings and lick 'Save'. That is it, all done!
|
||||||
|
|
||||||
|
#### YAML
|
||||||
|
|
||||||
|
YAML is designed to be human-readable and easy to edit. However, like all programming languages, it has it oddities and quirky
|
||||||
|
|
||||||
|
- You can **only use spaces** for indentation
|
||||||
|
- Using the `**[Tab] key is strictly forbidden** and can cause parser errors or unexpected block merges
|
||||||
|
- If you want an **empty string, you have to add quotes**. E.g. MyString = ""
|
||||||
|
- You do not need add a semicolon at the end of each function or command. YAML treats semicolons as a regular string character, rathe than syntax delimiter.
|
||||||
|
|
||||||
|
#### New Device
|
||||||
|
|
||||||
|
Within ESPHome, to create a device, simply click the NEW Device on the bottom right of the screen, the click [CONTINUE].
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
Finally click [INSTALL]. The Auto Generated Encryption Key will be automatically added to the YAML file.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
Excellent! Your new device should not be added to the ESPHome Device Builder dash.
|
||||||
|
|
||||||
|
#### Setting up your New Device
|
||||||
|
|
||||||
|
Now you have a 'blank device' you could run through flashing it with blank code, to ensure it then appears in the dash as online.
|
||||||
|
|
||||||
|
If you right click the three dots on your device, you will be requested to install the YAML to the device itself.
|
||||||
|
As this is a new device and does not know about Wi-Fi etc, simply use the [Plug into this computer] option.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
#### Flashing
|
||||||
|
|
||||||
|
You will be using the Web Browser to flash the device.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
If you clicked the Install,, you may see this instead
|
||||||
|
|
||||||
|
|
||||||
|
Chose the downloaded and saved file.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
Finally - Success! Your board is flashed with a blank code. It should then show in teh dash as online.
|
||||||
|
[](https://github.com/DitroniX/Home-Assistant-Dev/blob/main/Datasheets%20and%20Information/Example%20of%20Installed.png)
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
#### Adding the DitroniX configuration
|
||||||
|
You are now at a stage where you can edit the device YAML and add the test code.
|
||||||
|
|
||||||
|
YAML Test code is provided in the indivudal product repositors, or in the YAML folder.
|
||||||
|
[https://github.com/DitroniX/Home-Assistant-Dev/tree/main/YAML%20Examples](https://github.com/DitroniX/Home-Assistant-Dev/tree/main/YAML%20Examples)
|
||||||
|
|
||||||
|
Click the [EDIT] button on the device dash and this should open the YAML Editor.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
At this stage, you will be copying the test YAML code and pasting it into the editor.
|
||||||
|
|
||||||
|
Remember, that you must NOT over-write the elements below the # Enable Home Assistant API, or your unique device will not be known by your system.
|
||||||
|
|
||||||
|
You may alternatively, simply update the xxxx with your details.
|
||||||
|
|
||||||
|
# Enable Home Assistant API
|
||||||
|
api:
|
||||||
|
encryption:
|
||||||
|
key: "xxxxx"
|
||||||
|
|
||||||
|
ota:
|
||||||
|
- platform: esphome
|
||||||
|
password: "xxxxx"
|
||||||
|
|
||||||
|
wifi:
|
||||||
|
ssid: !secret wifi_ssid
|
||||||
|
password: !secret wifi_password
|
||||||
|
|
||||||
|
# Enable fallback hotspot (captive portal) in case wifi connection fails
|
||||||
|
ap:
|
||||||
|
ssid: "EPEM E36 House Fallback Hotspot"
|
||||||
|
password: "xxxxx"
|
||||||
|
|
||||||
|
#### Add Device to your dash
|
||||||
|
You may now add the device to your normal Home Assistant dash and select required values to be displayed.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
Reference in New Issue
Block a user