diff --git a/Creating-Your-First-Device-in-Home-Assistant-‐-ESPHome.md b/Creating-Your-First-Device-in-Home-Assistant-‐-ESPHome.md new file mode 100644 index 0000000..96a0077 --- /dev/null +++ b/Creating-Your-First-Device-in-Home-Assistant-‐-ESPHome.md @@ -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. + +![Example of New Device](https://github.com/DitroniX/Home-Assistant-Dev/blob/main/Datasheets%20and%20Information/Example%20of%20Device%20in%20Dash%20and%20Online.png) + +#### 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 + +![ESPHome Secrets](https://github.com/DitroniX/Home-Assistant-Dev/blob/main/Datasheets%20and%20Information/Home%20Assistant%20-%20ESPHome%20-%20Secrets.png) + +![ESPHome Secrets Editor](https://github.com/DitroniX/Home-Assistant-Dev/blob/main/Datasheets%20and%20Information/Home%20Assistant%20-%20ESPHome%20-%20Secrets%20Editor.png) + +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]. + +![](https://github.com/DitroniX/Home-Assistant-Dev/blob/main/Datasheets%20and%20Information/Example%20of%20New%20Device.png) + +![](https://github.com/DitroniX/Home-Assistant-Dev/blob/main/Datasheets%20and%20Information/Example%20of%20New%20Device%20Setup.png) + +![](https://github.com/DitroniX/Home-Assistant-Dev/blob/main/Datasheets%20and%20Information/Example%20of%20Naming.png) + +![](https://github.com/DitroniX/Home-Assistant-Dev/blob/main/Datasheets%20and%20Information/Example%20of%20MCU%20Selection.png) + +Finally click [INSTALL]. The Auto Generated Encryption Key will be automatically added to the YAML file. + +![](https://github.com/DitroniX/Home-Assistant-Dev/blob/main/Datasheets%20and%20Information/Example%20of%20New%20Device%20Configured.png) + +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. + +![](https://github.com/DitroniX/Home-Assistant-Dev/blob/main/Datasheets%20and%20Information/Example%20of%20Plug%20into%20this%20computer%20option.png) + +![](https://github.com/DitroniX/Home-Assistant-Dev/blob/main/Datasheets%20and%20Information/Example%20of%20Install%20ESPHome%20via%20the%20browser.png) + +#### Flashing + +You will be using the Web Browser to flash the device. + +![](https://github.com/DitroniX/Home-Assistant-Dev/blob/main/Datasheets%20and%20Information/Example%20of%20Open%20ESPHome%20Web.png) + +If you clicked the Install,, you may see this instead +![](https://github.com/DitroniX/Home-Assistant-Dev/blob/main/Datasheets%20and%20Information/Example%20of%20Install.png) + +Chose the downloaded and saved file. + +![](https://github.com/DitroniX/Home-Assistant-Dev/blob/main/Datasheets%20and%20Information/Example%20of%20Choose%20File.png) + +![](https://github.com/DitroniX/Home-Assistant-Dev/blob/main/Datasheets%20and%20Information/Example%20of%20Installing.png) + +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) + +![](https://github.com/DitroniX/Home-Assistant-Dev/blob/main/Datasheets%20and%20Information/Example%20of%20Device%20in%20Dash%20and%20Online.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. + +![](https://github.com/DitroniX/Home-Assistant-Dev/blob/main/Datasheets%20and%20Information/Example%20of%20Basic%20YAMl%20Code%20in%20Editor.png) + +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. + +![](https://github.com/DitroniX/Home-Assistant-Dev/blob/main/Datasheets%20and%20Information/Example%20of%20added%20Device%20Info.png) +