Some of my posts assume that the user already has ESPHome installed, so I’m documenting how to install it here so I don’t have to repeat it everywhere.

Installation

This assumes you already have a machine with docker and docker-compose installed on it. If not, go install that first. You don’t need to run the ESPHome server all of the time, just when you’re configuring/adding devices.

You’re going to need a USB->UART adapter to reflash devices - mine is a DollaTek 3.3V / 5V USB to TTL Converter CH340G UART Serial Adapter Module. If you don’t already have an adapter, make sure that the one you get works with both 3.3 volt and 5 volt devices for flexibility later.

Prep your ESPHome directory

First, make a directory to put a docker-compose.yml file in. Create a config subdirectory in it so that ESPHome has someplace to put device configuration YAML files. You’re going to want to keep those files to make it easier to update your devices later.

Create a docker-compose.yml file with the following contents:

version: '3'
services:
  esphome:
    container_name: esphome
    environment:
      - TZ=America/Denver
    image: ghcr.io/esphome/esphome
    ports:
      - "6052:6052/tcp"
    volumes:
      - $PWD/config:/config
      - /etc/localtime:/etc/localtime:ro
    privileged: true
    restart: unless-stopped

You’re also going to need a file to store secrets like your WIFI network name and password. Create config/secrets.yml with the following contents:

wifi_ssid: "WIFI_NETWORK_TO_JOIN"
wifi_password: "WIFI_PASSWORD"
api_password: "AnAPIPassword"

This will let you use secrets in your device configurations as !secretname.

Run it

I only run ESPHome when I’m adding a new device or updating an existing one, so I usually run it on my laptop. It’s more convenient this way since I don’t have to go downstairs to the server rack to connect whatever device I’m working on.

Run docker-compose up -d on your laptop and you’ll see the ESPHome UI at http://localhost:6532.

You need a browser that supports Webserial to be able to flash devices directly from the ESPHome webui - on my Mac, I use Chrome for this since Firefox doesn’t support it.