How to get started with ESPHome and Sonoff

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.

Install the ESPHome Add-on

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 ssl from false to true.

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.

Create a configuration file

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 a-z, 0-9 and _ ). 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.

Add components to the config file

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.

Flash the firmware to the Sonoff basic

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.

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.

Integrate ESPHome with Home Assistant

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.

OTA (Over The Air) update

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 switch and 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.

The binary_sensor, under on_press, change the id name for the switch.toogle from relay to 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.

Add an OTA password, enable safe mode and Captive Portal

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.

Store passwords and other sensitive data using !secret

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.

Open ESPHome from the sidebar

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.