Programming for Home Assistant
For the new modules Home Assistant is especially easy to use!
Currently this website does not have a guide on how to setup Home Assistant, enough of those out there. To get the new QuinLED modules to work with Home Assistant you need a working install together with MQTT installed and configured for auto discovery. If you have this, continue below, if not for now try and find some guides online!
In my Multi-Room Temperature & Humidity video I made a video tutorial how to get started with ESPhome by using USB to flash the first time and then using OTA after that, although the code that you want to input might be different, this can help you get started with everyone, check out the following video:
esphomelib & esphomeyaml
In short, esphomelib is a framework created by Otto Winters which runs on the ESP8266 and ESP32 and has a lot of preconfigured software modules to be able to read out sensors, control LEDs, etc. but also provide a secure communication and update framework. Esphomeyaml was created after that, proving an easy to use configuration file programming method which will do a lot of steps for you such as compiling the firmware (esphomelib arduino image) and providing an easy way to upload or update it on your modules.
For information more see the esphomelib and esphomeyaml webpages
This guide has been slightly outdated, although the below still works I advise installing ESPhome as a plugin with hass.io to start!
Setting up esphomeyaml
To deploy the software on the QuinLED or QuinLED-Dig we are going to use a software package called esphomeyaml. This python script will do most of the work for you and allow you to specify a configuration file (sample provided below) and then automatically compile an Arduino firmware which will connect with MQTT to your Home Assistant installation and automatically add all the buttons and sensors on the board! This is not a guide about “esphomelib” or “esphomeyaml”, only how to use it so that you can configure a board to work together with Home Assistant.
Although esphomeyaml can be installed inside of HASS.IO I don’t advise doing so, at least not for the first software deployment. So for now I advise you install esphomeyaml on your workstation where you also have access to a USB port.
This guide should be roughly the same on Linux or Windows, it’s written from the Windows perspective though.
Step 1. Install Python 2.7 & esphomeyaml
Download and install Python 2.7, you can find it here. If you don’t know what to download and you are on Windows, download the “Windows x86-64 MSI installer“.
After that download the following file and put it into the “c:\Python27” directory. Once that is done, open a command prompt and perform the following commands:
cd\Python27\Scripts pip install esphomeyaml
This will download and install a esphomeyaml on your system including all the add-on packages your Python installation might need.
Configuration file
To configure the QuinLED module you will need to tell esphomeyaml how the board is configured, your WiFi network, where it can find your Home Assistant and MQTT and passwords for it.
To do this let’s take QuinLED-Quad as an example. A sample of such a configuration file is here:
Sample configurations can be found per Board on the main page!
esphomeyaml:
name: 'q1_quinled-quad'
platform: ESP32
board: mhetesp32devkit
wifi:
ssid: 'XXXXXXXXXX'
password: 'XXXXXXXXXX'
mqtt:
broker: 'XXXXXXXXXX'
username: 'XXXXXXXXXX'
password: 'XXXXXXXXXX'
# Enable logging
logger:
level: DEBUG
ota:
password: 'XXXXXXXXXX'
dallas:
- pin: GPIO18
switch:
- platform: gpio
name: "Q1_Onboard light"
pin: 2
output:
- platform: ledc
pin: 16
frequency: 40000Hz
bit_depth: 10
id: LED_gpio_16
- platform: ledc
pin: 17
frequency: 40000Hz
bit_depth: 10
id: LED_gpio_17
- platform: ledc
pin: 5
frequency: 40000Hz
bit_depth: 10
id: LED_gpio_5
- platform: ledc
pin: 19
frequency: 40000Hz
bit_depth: 10
id: LED_gpio_19
light:
- platform: monochromatic
name: "Q1_LED light ouput1"
default_transition_length: 5s
output: LED_gpio_16
- platform: monochromatic
name: "Q1_LED light ouput2"
default_transition_length: 5s
output: LED_gpio_17
- platform: monochromatic
name: "Q1_LED light ouput3"
default_transition_length: 5s
output: LED_gpio_5
- platform: monochromatic
name: "Q1_LED light ouput4"
default_transition_length: 5s
output: LED_gpio_19
sensor:
- platform: dallas
index: 0
name: "Q1_tempsensor"
In the above example you see green values between all the text, these are the values which need to be changed to fit your installation. I’ve made the mandatory values say XXXXXXXXXX. The the names of the sensors and modules don’t need to be changed but I still advise to do so. Be mindful that not all fields will take capital letters!
Let’s save this file as “Q1_QuinLED-Quad.yaml” for now. For demonstration purposes I’m going to save it in “c:\temp”. If the text looks all weird in notepad, thi
Uploading code to module for the first time
Once the above configuration file is correct you need to upload it to the QuinLED ESP32 module. To do this we can use the esphomeyaml script we just installed!
Connect the ESP32 module (either loose or while still on the QuinLED module) to your computers USB port using a standard micro-USB cable.
DO NOT connect external power and USB at the same time!!!
Open up a command prompt and type the following:
cd\Python27\Scripts esphomeyaml c:\temp\Q1_QuinLED-Quad.yaml run
If this fails, probably notepad added a .txt after the file extension, try it again using:
esphomeyaml c:\temp\Q1_QuinLED-Quad.yaml.txt run
If successful it will start giving lots of output about downloading and configuring all the components it needs. This is only done the first time, running the command again is much faster once everything has been installed so just leave it be for a little bit.
Once installing and configuring finishes it should automatically start to compile the Arduino binaries for the ESP32 module. And after a while, it gets to the step where it can upload the finished firmware to the module. Since this is the first time we’re flashing the ESP32 with this firmware this needs to be done using the USB connection we made earlier. You should see something like this:
Linking .pioenvs\quinled_quad\firmware.elf Calculating size .pioenvs\quinled_quad\firmware.elf Building .pioenvs\quinled_quad\firmware.bin text data bss dec hex filename 629116 197436 31568 858120 d1808 .pioenvs\quinled_quad\firmware.elf ============================================ [SUCCESS] Took 14.82 seconds ============================================ [32mINFO [esphomeyaml.__main__] Successfully compiled program.[0m Found multiple serial port options, please choose one: [0] COM13 (Silicon Labs CP210x USB to UART Bridge (COM13)) [1] Over The Air (quinled_quad.local)
In my case the COM13 CP210x USB to UART Bridge is the one we need. Hit the 0 key and it should automatically start sending the firmware to the module!
Reset mode
Sometimes a module won’t enter flash start correctly even after trying multiple reboots (You can see this with the blue LED flashing and not staying on). The best way to help it is after pressing the 0 key to start the upload is to hold down the “EN” button that is on the module. This should make it boot to flash mode and you should see the logging on the screen display something like the following:
Serial port COM13 Connecting........__ Chip is ESP32D0WDQ6 (revision 1) Features: WiFi, BT, Dual Core MAC: 30:ae:a4:1a:de:30 Uploading stub... Running stub... Stub running... Changing baud rate to 921600 Changed. Configuring flash size... Auto-detected Flash size: 4MB Compressed 15088 bytes to 9755... Wrote 15088 bytes (9755 compressed) at 0x00001000 in 0.2 seconds (effective 642.0 kbit/s)... Hash of data verified. Compressed 3072 bytes to 144... Wrote 3072 bytes (144 compressed) at 0x00008000 in 0.1 seconds (effective 384.0 kbit/s)... Hash of data verified. Compressed 8192 bytes to 47... Wrote 8192 bytes (47 compressed) at 0x0000e000 in 0.1 seconds (effective 1040.3 kbit/s)... Hash of data verified. Compressed 826688 bytes to 459906... Wrote 826688 bytes (459906 compressed) at 0x00010000 in 9.5 seconds (effective 697.6 kbit/s)... Hash of data verified. Leaving... Hard resetting via RTS pin...
All done!
And that’s it! You don’t need to log into the module or even know it’s IP really. It should automatically join your WiFi network and connect to Home Assistant through the MQTT broker you specified. If you have Home Assistant configured to automatically add MQTT devices the buttons and sensor should automatically appear and presto!
Additional topics
OTA Update
The OTA update features can be used after programming the module once. But to use this feature esphomeyaml needs to be able to find the module again on your home network. To do this is uses DNS. They have guides on how to configure this so it works automatically but for myself I just look up the IP in my router, make it static and then assign it a static DNS name also.
Configuration example files
Example configurations can be found on the main page under each board section.