Congratulations
You now have a board which you are excited to add to Home Assistant. So let's get started.
Note: This is not a step by step guide, so please follow the prompts where needed and you should be able to flow through the process.
Top Level
- Use Home Assistant 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', 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
DitroniX Component Development
During DitroniX Home Assistant Code Development, the required device 'Component', is simply connected to the DitroniX git (GitHub), 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).
Adding a Device
You will be using ESPHome 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. Within YAML , this is <<: !include ../secrets.yaml
To configure the secrets file, you need to:
Edit the Wi-Fi settings and click [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's oddities and quirky gotchas.
- 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].
You would normally click the [New Device Setup].
Give your device a meaningful name
Select the ESP device, normally ESP32-C6.
For ESP32-C5, also see this page for reference.
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 the dash as online.
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 individual product repositors, or in the YAML folder. 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.
Finally
Once your device is up and running, you can always 'tweak', or edit, the YAML code, then quickly reflash, at any time, either by OTA or USB.
You can even duplicate the code for another device.
Remember though, each device has it's own unique 'api key', 'ota password' and 'ap fallback password'. The rest of the code can be duplicated across your devices, where needed.
Further Information
Additional information, and other technical details on this project, maybe found in the related repository pages.
Repository Folders
- Components (Code examples for Home Assistant - ESPHome)
- Datasheets and Information (Component Datasheets, Schematics, Board Layouts, Photos, Technical Documentation)
Repository Tabs
- Wiki (Related Repository Wiki pages and Technical User Information)
- Discussions (Related Repository User Discussion Forum)
- Issues (Related Repository Technical Issues and Fixes)
We value our Customers, Users of our designs and STEM Communities, all over the World . Should you have any other questions, or feedback to share to others, please feel free to:
- Visit the related Project plus the related Discussions and Wiki Pages. See tab in each separate repository.
- Project Community Information can be found at https://www.hackster.io/DitroniX
- DitroniX.net Website - Contact Us
- Twitter: https://twitter.com/DitroniX
- Supporting the STEM Projects - BuyMeACoffee
- LinkedIN: https://www.linkedin.com/in/g8puo/
Dave Williams, Maidstone, UK.
Electronics Engineer | Software Developer | R&D Support | RF Engineering | Product Certification and Testing | STEM Ambassador
STEM
Supporting STEM Learning
Life is one long exciting learning curve, help others by setting the seed to knowledge.
