Home Assistant Container Part 9: ESPHome

Intro ¶

If you like designing systems with ESP8266 and ESP32 microcontrollers, definitely check out ESPHome if you haven’t already.

By the end of this post, you’ll have ESPHome installed, accessible via the Dashboard and connected to a device over USB. In a future post (or a later edit of this post), we’ll discuss setting up HTTPS so we can flash via the web browser.

Install ESPHome container ¶

Docker-compose ¶

We expand our docker-compose.yaml with the config for the ESPHome container.

services:
  [...]

  esphome:
    container_name: esphome
    image: esphome/esphome
    restart: unless-stopped
    ports:
      - "6052:6052/tcp"
    environment:
      - TZ=Europe/Brussels
    # mDNS doesn't work across VLANs, use static IP for devices when disabling mDNS
    #   - ESPHOME_DASHBOARD_USE_PING=true
    volumes:
      - /opt/esphome/config:/config
      - /etc/localtime:/etc/localtime:ro
    # devices:
    #   - /dev/ttyUSB0:/dev/ttyUSB0
    network_mode: host

You’ll have noticed a commented-out devices section. We’ll get back to this in a minute.

Start and access ESPHome ¶

If we then run docker-compose up -d Docker will pull the image and will launch it.

Once running, the ESPHome dashboard can be reached at http://<ip.of.our.box>:6052.

Home Assistant Sidebar ¶

We have done it a few times already: add an entry for ESPHome to the sidebar of our Home Assistant dashboard using panel-iframe.

Add the following lines to configuration.yaml:

panel_iframe:
  portainer:     # part 3
    [...]
  nodered:       # part 5
    [...]
  configurator:  # part 6
    [...]
  duplicati:     # part 7
    [...]
  esphome:
    title: ESPHome
    icon: mdi:chip
    url: http://192.168.10.106:6052
    require_admin: true

After a reboot, ESPHome will be accessible from within the Home Assistant Dashboard.

Connecting and flashing a device ¶

Let’s imagine you want to set up an ESP to control a LED strip and relais.

You’ll have to create a new device in the ESPHome dashboard and add the configuration you want to it. Afterwards, you’ll have to flash that configuration onto the ESP8266/ESP32 board.

Multiple options are available, but for the purpose of this posts we’ll focus on the option Plug into the computer running ESPHome Dashboard.

Before you can chose this option, however, we’ll first need to connect our ESP board to the Docker container.

Connecting the device to our ESPHome container ¶

Identify the device ¶

First you’ll need to figure out the path to the ESP when you connect it over USB to your Docker machine.

To do this, run the command ls -l /sys/class/tty/*/device/driver before and after connecting the ESP board via USB or FTDI adapter. This command will show a list of all serial (TTY) devices on your system which have an actual driver for them installed (skipping virtual terminals). You should notice an additional line appearing when you run the command after connecting the board.

For example

ls -l /sys/class/tty/*/device/driver
lrwxrwxrwx 1 root root 0 Sep  4 13:05 /sys/class/tty/ttyS0/device/driver -> ../../../../bus/platform/drivers/dw-apb-uart
lrwxrwxrwx 1 root root 0 Sep 15 15:36 /sys/class/tty/ttyS1/device/driver -> ../../../bus/platform/drivers/serial8250
lrwxrwxrwx 1 root root 0 Sep 15 15:36 /sys/class/tty/ttyS2/device/driver -> ../../../bus/platform/drivers/serial8250
lrwxrwxrwx 1 root root 0 Sep 15 15:36 /sys/class/tty/ttyS3/device/driver -> ../../../bus/platform/drivers/serial8250

# Plugin the device (in this case a D1 ESP32)

ls -l /sys/class/tty/*/device/driver
lrwxrwxrwx 1 root root 0 Sep  4 13:05 /sys/class/tty/ttyS0/device/driver -> ../../../../bus/platform/drivers/dw-apb-uart
lrwxrwxrwx 1 root root 0 Sep 15 15:36 /sys/class/tty/ttyS1/device/driver -> ../../../bus/platform/drivers/serial8250
lrwxrwxrwx 1 root root 0 Sep 15 15:36 /sys/class/tty/ttyS2/device/driver -> ../../../bus/platform/drivers/serial8250
lrwxrwxrwx 1 root root 0 Sep 15 15:36 /sys/class/tty/ttyS3/device/driver -> ../../../bus/platform/drivers/serial8250
lrwxrwxrwx 1 root root 0 Sep 15 15:54 /sys/class/tty/ttyUSB0/device/driver -> ../../../../../../../bus/usb-serial/drivers/cp210x

Notice the line at the end for a USB serial device using the CP210x USB to UART Bridge Virtual COM Port (VCP) driver. Note that it is identified as ttyUSB0. This means we can address our device at /dev/ttyUSB0.

Forward to the container ¶

Remember the commented-out section? Uncomment it and make sure the first section matches the path to your connected ESP.

    devices:
    # - [path to your device]:/dev/ttyUSB0
      - /dev/ttyUSB0:/dev/ttyUSB0

This will map/mount your ESP microcontroller to /dev/ttyUSB0 within the Docker container, allowing the ESPHome Dashboard to “see” it.

To finalise this device forwarding, you will need to rebuild the ESPHome container. Save your changes and run docker-compose up -d so Docker recreates the container using our new config.

Install configuration on the ESP ¶

With the container restarted, go back to the ESPHome dashboard. You’ll find your device config listed there.

Press the 3 dots at the bottom-right of your device and choose Install. Then – as said before – pick the option Plug into the computer running ESPHome Dashboard.

ESPHome will now show the connected device. Notice how the path is /dev/ttyUSB0 and a CP2104 driver is used.

ESPHome will now turn your configuration in a firmware for the board and will flash it. This may take a minute.

Once the device is flashed, ESPHome will be able to connect to the API and see data like the WiFi configuration.

Add device to Home Assistant ¶

With the board now flashed and connected to our WiFi, we still need to add the device to our Home Assistant install via the ESPHome integration. This will allow us to read data from connected (and configured) sensors.

Home Assistant should’ve automatically discovered the new ESPHome device and will send you a notification about this. Clicking Check it out will send you to the integrations page, where the newly discovered device will be highlighted.

You can now add the device by clicking Configure. However, you’ll need the (randomly generated) API encryption key, which you can find in the ESPHome configuration of your device.

Copy the API encryption key and paste it when asked while configuring the ESPHome device.

Once added, you’ll be able to view the device and (if applicable) entities created by the integration. If you have sensors configured in the ESPHome config, you’ll find these as entities in Home Assistant.

Now we’re ready to build custom devices using ESP8266/ESP32 board or flash existing devices (like Sonoff NSPanel) with a custom configuration.

Next, we’ll install Zigbee2MQTT so we can set up a Zigbee network.