Getting started with the Home Assistant app for macOS
In this guide, we will install and configure the Home Assistant companion app for macOS.
ESPHome is a tool that allows creating custom firmware for ESP8266 and ESP32 boards. This post shows how to install the ESPHome add-on in Home Assistant. To flash a custom firmware to a Sonoff basic switch. Also, how to configure some of the available components in ESPHome. So, you can integrate them and easily control them via Home Assistant.
To install the ESPHome add-on in Home Assistant, you first need to add the ESPHome repository. So, open Home Assistant, go to Hass.io, Add-on Store and then under Add new repository, add the following URL:https://github.com/esphome/hassio.
After that, locate the ESPHome add-on, click on it and Install it. If you have remote access set up in Home Assistant, using DuckDNS, you’d need to enable SSL. So, under Config, change the
On version 1.13.0, ESPHome started supporting the Home Assistant’s Ingress feature. So there is no need to set up a port forwarding rule on your router. You can now access ESPHome securely from Home Assistant anywhere you are.
Save the changes and start the ESPHome add-on. Give it a few seconds for it to load and then click on Open Web UI. A login window comes up where you’d need to sign in using your Home Assistant credentials to access the ESPHome Dashboard.
To create a new config file for the Sonoff basic switch, you would need to add a node in the ESPHome Dashboard. So, click on the Plus “+” icon on the right and enter a unique name for the device. The name must be in lowercase and with no spaces (allowed characters
_ ). Under Device Type, you can select the device that you are going to be flashing from the drop-down. The Sonoff Basic has an ESP8266 chip, so select Generic ESP8266. Then enter the WiFi credentials, and lastly, click on Submit.
OK, so you created the configuration file for the Sonoff switch. However, it only has some basic settings. If you were to flash the firmware to the Sonoff switch now, it would just connect to your WiFi and nothing else. So, you would need to edit the config file and add a few more components. For example, the switch settings to control the relay to turn the Sonoff basic on and off.
Let’s go over some of the available settings that you can add. Click on Edit to open the config file and enter the following at the bottom:
binary_sensor: - platform: gpio pin: number: GPIO0 mode: INPUT_PULLUP inverted: True name: "Desk light button" on_press: - switch.toggle: relay switch: - platform: gpio name: "Desk light relay" pin: GPIO12 id: relay status_led: pin: number: GPIO13 inverted: yes sensor: - platform: wifi_signal name: "Desk light WiFi signal" update_interval: 60s - platform: uptime name: "Desk light uptime" text_sensor: - platform: version name: "Desk light ESPHome version"
binary_sensor: Checks for anytime the button on the Sonoff switch is pressed
switch: Would trigger the relay on and off
status_led: Useful to show the status of a device. Letting you know of any warning or errors
wifi_signal sensor: Monitors the received signal strength
uptime sensor: Tracks the time (in seconds) the device has been online
version text_sensor: Provides information of the current version of the ESPHome firmware installed on the device
When finished editing the config file, click on Save and then Validate to check that the configuration is correct. Once it’s validated, click on the More Options icon on the right, and then Compile. When the process finishes, click on Download Binary.
To flash the firmware to the Sonoff Basic switch, you can use the ESPHome Flasher, which makes it simple to flash the firmware from a Windows or Mac computer. You would also need a USB to TTL Converter (Transistor-Transistor Logic) and 4 male to female pin wires.
Open the case of the Sonoff switch, and use the USB to TTL Converter and the 4 male to female jumper wires to connect it to the computer.
Starting from the USB to TTL converter, connect the female ends of the wires to GND, TX, RX, and 3.3V. Then connect the male ends of the wires to the Sonoff switch but connect the TX wire to the RX PIN hole and the RX wire to the TX PIN hole.
NOTEMake sure that you don’t have the Sonoff switch connected to an electrical outlet. The only way the Sonoff switch should be getting power is from the 3.3v coming from the USB converter.
After connecting the wires, press and hold the onboard button on the Sonoff switch, and connect the USB to TTL converter to the computer. Hold the button for 3 to 5 seconds, so the switch goes into programming mode.
Lunch the ESPHome Flasher tool, and under Serial Port, you should now have the Sonoff switch coming up. For the Firmware, search and select the binary file that you downloaded from ESPHome. Lastly, click on Flash and give it a couple of minutes for the process to complete.
When the process finishes, restart the Sonoff switch by unplugging and replugging the USB connection to the computer. If the switch connected to the WiFi successfully, it would then show up online in the ESPHome dashboard.
To use the Sonoff switch with Home Assistant, you would need to integrate it. So, in Home Assistant, go to Configuration and then, Integrations. At the top, you should have the new ESPHome device discovered. Click on Configure, and then Submit.
If the device was not discovered automatically, you could manually add it. Look for the ESPHome integration and click on Configure. Enter the
name_of_the_node and then
.local at the end. Alternatively, if you set up a static IP address for the Sonoff switch, you can also enter the assigned IP address for that device. Lastly, click on Submit, and you should now have the Sonoff switch integrated. Click on it, and the options configured under the ESPHome config file would now show up as available entities to use with Home Assistant.
To make updates to the firmware, you can edit the config file in the ESPHome Dashboard and then do an OTA update without having to connect the Sonoff switch to the computer. For example, let’s make a change to the current firmware, Let’s say we want the green LED on the Sonoff switch to either be on or off depending on the state of the relay. So, turning the switch on would also turn on the LED and then off when turning the switch off. Go to the ESPHome Dashboard and open the Sonoff switch config file and replace the current
status_led with the following:
switch: - platform: gpio pin: GPIO12 id: relay - platform: template name: "Main desk light relay" optimistic: true id: relayandled turn_on_action: - switch.turn_on: relay - light.turn_on: led turn_off_action: - switch.turn_off: relay - light.turn_off: led output: - platform: esp8266_pwm id: sonoff_green_led pin: number: GPIO13 inverted: True light: - platform: monochromatic name: "Main sonoff Green LED" output: sonoff_green_led id: led
We set up an
output that uses the GPIO13, which is the PIN that the Sonoff switch uses for the LED. Then, we added a
light component linked to the output that controls GPIO13. Lastly, we set up 2 switches. A GPIO
switch that uses GPIO12 which controls the relay. The other switch is a template that would turn on and off both the relay and the led at the same time.
on_press, change the
id name for the
relayandled, which is the ID name that we set up for the template switch on this example.
Click on Save then Close and to check that the configuration is ok, click on Validate. Lastly, click on Upload to compile the firmware and upload it automatically to the Sonoff switch. When the OTA update finishes, you could then turn the switch on and off, and the LED would also turn on and off depending on the state of the relay.
To add a layer of security when sending updates to a device Over The Air, you want to add a password to the OTA component. In addition to that, you also want to enable Safe mode. So, if the device for some reason doesn’t start correctly due to the wrong configuration, Safe Mode would kick in and only enable the Serial Logging, WiFi, and OTA components. To access a device in Safe Mode, add the
captive_portal component and a fallback hotpot configuration to the WiFi component. So, on the device Config file, enter the following:
wifi: ssid: "WiFi_Name" password: "WiFi_Password" ap: ssid: "Fallback Hotspot Name" password: "Hotspot_Password" captive_portal: ota: safe_mode: True password: "OTA_Password"
Save the changes, Validate the configuration, and then Upload it to the device.
If a device doesn’t start correctly, check the available WiFis for the fallback hotspot, If the fallback hotspot is available, the device is in Safe Mode. To access the Captive portal, connect to the fallback hotspot, open the browser, and go to http://192.168.4.1. On the Captive portal, you can change the WiFi credentials, and also upload a new config file. After updating the configuration, you might need to reboot the device manually.
Just like in the Home Assistant configuration files, it’s possible to use
!secret in ESPHome. So, instead of having sensitive information spread across different config files, you can store them all in one location.
The ESPHome dashboard has a Secrets Editor available, which is accessible via the menu icon on the top right.
When adding something for the first time via the editor, ESPHome automatically creates the secrets.yaml file inside the ESPHome folder, in the Home Assistant Config folder.
After storing data in the secrets.yaml file. For example, the password for the WiFi, you can then go to your ESPHome devices, and in the config file, replace the password with the following:
wifi: ssid: "WiFi_Name" password: !secret WiFi_Password
After editing the config file, upload it to the device, and it would replace the
!secret name with the actual data that is on the secrets.yaml file.
With ESPHome, version 1.13.0, you can easily set up to open the ESPHome dashboard directly from the Home Assistant sidebar. To enable it, go back to Hassio, ESPHome, and then toggle the switch under Show on the sidebar. The page would automatically refresh, and the option would then be available on the sidebar.
One-time DonationBuy Me a Coffee
SubscriptionBecome a Patreon