Overview#

ESPHome runs as a host-networked Podman container on ereshkigal (192.168.0.20), port 6052. It serves as the sole firmware builder and dashboard for all ESP devices on the falseblue-iot VLAN (192.168.2.0/24).

Open Dashboard

Network Setup#

Why host networking#

The container runs with --network=host so ESPHome can:

  • Participate in mDNS on vmbr0 (LAN) via Avahi — necessary for device discovery and persistent native API connections that drive the live status dashboard
  • Reach IoT VLAN devices through the static route below without Podman NAT breaking the source IP that the Unifi firewall rule expects

Static route#

ereshkigal has no direct IoT VLAN interface. A static route is provisioned by the module:

192.168.2.0/24 via 192.168.0.1 dev vmbr0

Traffic flows: ereshkigal → Unifi (192.168.0.1) → IoT VLAN. The Unifi firewall rule permitting this must exist on the falseblue-iot network.

Unifi requirements#

Two Unifi settings are needed beyond the default IoT isolation:

Setting Where What
mDNS repeater Settings → Networks → falseblue-iot → mDNS Reflects mDNS between LAN and IoT VLAN so ESPHome can discover IoT devices
Firewall rule Settings → Firewall & Security Allow IoT → LAN, dst 192.168.0.20, port 6052 TCP — required for HA Green (192.168.2.66) to reach the dashboard

Home Assistant Integration#

ESPHome is embedded in the HA dashboard via panel_iframe. Add to /config/configuration.yaml on HA Green:

panel_iframe:
  esphome:
    title: ESPHome
    icon: mdi:chip
    url: http://192.168.0.20:6052
    require_admin: true

Restart HA after adding. An ESPHome entry will appear in the sidebar.

Note: If HA is accessed over HTTPS (Nabu Casa / cloud), the browser will block the HTTP iframe (mixed content). In that case, put ESPHome behind a reverse proxy with TLS using the existing step-ca infrastructure.

The HA ESPHome integration (Settings → Devices & Services → ESPHome) is separate — it connects directly to each device’s native API on port 6053 and is unaffected by which dashboard is used.

Device Config Workflow#

Device configs (*.yaml, *.h) are declaratively managed in the nix module and symlinked read-only into /var/lib/esphome/. The ESPHome dashboard UI cannot save edits to these files.

To modify an existing device: 1. Edit the relevant file in modules/nixos/containers/esphome/ 2. nixos-rebuild switch on ereshkigal 3. The new symlink is picked up immediately; trigger a recompile from the dashboard

To add a new device: 1. Create it through the ESPHome dashboard UI — new files land as writable files alongside the managed symlinks 2. Once stable, move the YAML into the module directory and add an L+ line in default.nix under systemd.tmpfiles.rules

secrets.yaml#

secrets.yaml is not managed by Nix (it contains wifi credentials). It must be placed manually:

scp secrets.yaml ereshkigal:/var/lib/esphome/secrets.yaml

Contents:

wifi_ssid: "FalseBlue-IoT"
wifi_password: "<password>"

Managed Devices#

File Device Board Notes
co-sensor.yaml CO Sensor (SEN0466) DFRobot FireBeetle ESP32-E Raw I2C, CO + temp + VOC
office-dev.yaml Govee Hub ESP32 (generic) BLE proxy for Govee H5151
esphome-web-6b6e3f.yaml WeatherStation NodeMCU v2 (ESP8266) DHT11, BMP180, BH1750, OLED

Building and Flashing#

From the dashboard at http://192.168.0.20:6052:

  • Install → Wirelessly — OTA push directly to the device on IoT VLAN
  • Install → Manual download — downloads firmware.bin for USB flash

For first-time USB flash (before wifi is configured), use the ESPHome Web installer or connect to ereshkigal and run:

podman exec -it esphome esphome upload co-sensor.yaml --device /dev/ttyUSB0