ESPHome builder

Devices and their YAML config files are read/written directly from an ESPHome-compatible config directory - no database table, so anything already hand-managed there stays hand-manageable. This is the config/compile side of ESPHome (called "ESPHome Dashboard" by the underlying sidecar itself, titled "ESPHome builder" here so it doesn't read as a duplicate of the "ESPHome" native-device tile right next to it - see Devices & Services); for discovering and live-connecting to devices over their own API, see ESPHome instead.

Like every other integration on Devices & Services, this tile is hidden until it's actually configured - a "Settings" item in the page header's own three-dot menu sets the Dashboard URL and optional credentials (this used to be a card on the System settings page; it moved here once ESPHome builder became an opt-in integration rather than an always-on sidebar item).

Devices tab

Card view (the default) or list view, toggled top-right, with a filter-icon menu right next to it for Online/Offline (both unchecked by default shows every device; checking one or both narrows to just those statuses). A search field to their left matches name/friendly name/platform/board together while typing. A card shows the friendly name and file name up top, its Status badge, then Edit and Logs, and a three-dot menu (opening to the right of the trigger, or left near the screen edge) with everything else.

• Status - the ESPHome dashboard's own reachability check, polled every 15s, shown as a green/red/muted badge. "Unknown" (no dashboard configured, or never reached) shows the same red "Offline" badge as a confirmed-offline device.
• Validate / Compile - stream live output from the ESPHome dashboard sidecar in a modal. Requires a Dashboard URL to be configured (see "Settings" above); without it, device YAML editing and the Files tab below still work.
• Install - opens a modal choosing USB or network (see "Flashing firmware" below for what each does).
• Show API key - displays the device's own api: encryption: key: value (if set) with a copy-to-clipboard button.
• Download YAML - saves the device's raw config file as-is.
• Edit friendly name / Rename hostname - quick single-field edits of esphome: friendly_name: / esphome: name: without opening the full YAML editor. Renaming the hostname only changes that internal field (the device's real network/mDNS name), not this list's own file/URL identity - that's a separate rename via the device's own Edit page.
• Duplicate - copies the device's config byte-for-byte into a new file under a name you choose; its internal esphome: name/friendly_name fields are left untouched, so edit those (Rename hostname / Edit friendly name above) before ever compiling the copy - two devices sharing the same ESPHome name will collide once both are online.
• Download - downloads the most recently compiled firmware binary.
• Archive / Delete - Archive moves the config into the dashboard's own archive/ subfolder (restore it by moving the file back via the Files tab); Delete removes it outright.

Flashing firmware

Two ways to get compiled firmware onto a device - pick one from a card's own "Install" menu item, or from the device's own page.

OTA (on the network)

Relays the ESPHome dashboard's own "run" operation - the same mechanism Compile/Validate use - targeting the device's mDNS hostname by default. Needs a Dashboard URL configured (see "Settings" above) and the device already reachable on the network.

Browser USB (WebSerial)

For a brand-new chip with nothing on it yet - flashing happens entirely client-side via ESP Web Tools (the same library the real ESPHome dashboard uses), with no Docker/host USB passthrough needed. Plug the device into the computer running your browser, not into the Athena server. Picking "Plug into this computer" in the Install modal compiles automatically first (a compile can take a while, and the browser only allows opening its own USB port picker within a couple of seconds of a real click, so it can't be triggered automatically the instant compiling finishes) - once that succeeds, one more click on the button shown in the same modal opens the port picker and flashes.

After either method, the device should reappear in the Status check above within about 15 seconds, and in ESPHome discovery shortly after that once it's back on the network.

Logs

The device's own page also has a "Logs" button, at the right edge of the same row as Save/ Validate/Compile/Flash - streams that device's own live log output straight from the ESPHome dashboard sidecar, the same view the dashboard's own "Logs" action shows, targeting the device's mDNS hostname the same way Flash does.

Files tab

A generic file manager over the whole config directory, for packages, interfaces, or anything else referenced by hand from a device's YAML via !include/packages:.

Split deploy

If ESPHome's own compiles are more than your Athena machine wants to carry, run the dashboard on a separate, beefier machine instead (docker-compose-esphome.yml) and point this integration's own "Settings" Dashboard URL at it - see Installation. ESPHOME_DASHBOARD_URL in .env still works too, as the starting value a fresh install reads before anyone's saved anything from Settings.