ESPHome

ESPHome turns a cheap ESP32, ESP8266, or RP2040 board into a purpose-built smart home device by writing a YAML file instead of C++. You describe the sensors, GPIO pins, and behavior you want; ESPHome compiles that into a real firmware binary and flashes it to the chip. Once it’s running, the device talks to Home Assistant over ESPHome’s own native API, no separate MQTT broker required unless you want one for something else.

From YAML file to compiled firmware

Every ESPHome device starts as one YAML file: board type, Wi-Fi credentials, and a list of components, a DHT22 temperature sensor on a given pin, a relay, an OLED display, a binary sensor for a door reed switch. ESPHome reads that file and generates actual C++ source code underneath, then hands it to PlatformIO to cross-compile into a firmware binary for that specific chip. You never open the generated C++ unless something goes wrong at compile time, and even then the errors usually point straight back to a YAML typo. This is the opposite of Tasmota’s model, more on that below, where one pre-built binary gets flashed everywhere and configured afterward through a web UI.

The component library covers most of what a homelabber ends up wanting: temperature and humidity sensors, relays, dimmers, e-ink and OLED displays, PIR motion, air quality, even ESP32-based cameras. Each new component means a config block, not a rewrite, and the same YAML file can target completely different hardware just by changing the board line at the top.

Installing ESPHome

Two paths cover almost everyone. Inside Home Assistant OS or Supervised, the ESPHome add-on installs from the Apps store in a couple of clicks and gets you the same dashboard without touching a terminal. Everyone else, including anyone on Home Assistant Container or running ESPHome standalone, uses the official Docker image:

services:
  esphome:
    container_name: esphome
    image: ghcr.io/esphome/esphome
    restart: unless-stopped
    volumes:
      - /path/to/your/config:/config
      - /etc/localtime:/etc/localtime:ro
    network_mode: host

docker compose up -d

1. Host networking is the path of least resistance on Linux; it’s what lets the dashboard show devices as online/offline via ping. On macOS, Docker Desktop can’t do host mode, so map -p 6052:6052 instead and set ESPHOME_DASHBOARD_USE_PING=true.
2. Open http://your-server-ip:6052; the dashboard lists every device you’ve created, each with its own YAML file stored under /config.
3. Click “New device,” pick a board (ESP32, ESP8266, RP2040, and several others), and the dashboard scaffolds a starting YAML file with Wi-Fi and API already wired up.
4. Add components by editing the YAML directly, or use the dashboard’s built-in editor with inline validation before you compile.

Flashing: USB the first time, OTA after that

The very first flash has to happen over USB, there’s no factory firmware on a bare ESP32 that already speaks ESPHome’s OTA protocol. Plug the board into the machine running the dashboard (or into your own computer if the dashboard runs on a headless server, using the browser-based flasher), hit “Install,” and pick the USB port. ESPHome compiles the firmware, then pushes it over serial using esptool under the hood. Most boards flash cleanly; the common failure is a data-only USB cable that can’t handle both power and a serial connection, or a board that needs its BOOT button held during the handshake.

Every flash after that first one is over-the-air. Change the YAML, hit “Install” again, and ESPHome compiles a new binary and pushes it to the device’s IP address over Wi-Fi, no cable, no physical access. That’s the detail that makes ESPHome practical past two or three devices: a sensor mounted inside a wall box or a light switch box stays exactly where it is for every future config change.

Native Home Assistant integration, not MQTT by default

ESPHome ships its own native API, a persistent TCP connection using a compact binary protocol, and it’s the default and recommended path into Home Assistant, not MQTT. Add a device once, either auto-discovered or by IP, and every entity it exposes shows up without touching configuration.yaml again. State changes push to Home Assistant the moment they happen, no polling, and the device is its own tiny server rather than a client depending on a shared broker staying up. MQTT support still exists in ESPHome and matters when several separate systems, Home Assistant plus Node-RED plus an InfluxDB logger, say, all need the same sensor reading at once; the native API only talks to Home Assistant.

That native connection is also how Node-RED reaches ESPHome devices in practice: the same node-red-contrib-home-assistant-websocket package that exposes Home Assistant entities to a flow picks up ESPHome devices automatically once they’re added to Home Assistant, no separate ESPHome-specific node needed.

ESPHome vs Tasmota

Tasmota is the other major open-source ESP firmware, and the two solve the same problem from opposite directions. Tasmota ships one pre-built binary you flash once, then configure entirely through a web UI or MQTT commands, no compiling. ESPHome compiles a fresh, purpose-built binary per device from your YAML. Tasmota’s approach is faster for a single generic smart plug; ESPHome’s pays off once devices get custom or numerous, since the whole config lives in a text file you can version and copy between similar devices.

	ESPHome	Tasmota
Configuration model	YAML, compiled to a per-device binary	One generic binary, configured via web UI/console
Home Assistant integration	Native API, one-click add, no MQTT needed	MQTT-based, needs a broker and discovery config
Customization depth	High, add any supported component to any pin in YAML	Good for supported devices, custom builds need actual firmware compiling
Update path	OTA, recompiles and pushes automatically	OTA, flashes a new pre-built binary
License	MIT (Python) + GPLv3 (C++ runtime)	GPLv3

ESPHome: pros and cons

• No C++ required for the vast majority of use cases; the YAML config covers hundreds of components
• Native Home Assistant API means instant state pushes and zero MQTT broker to maintain
• OTA updates after the first flash, no physical access needed for devices mounted inside walls or fixtures
• Backed by the Open Home Foundation, the same non-profit steering Home Assistant, so it isn’t a solo-maintainer project

• The first flash always needs a USB cable and a working serial connection, no way around it
• Compiling firmware takes real time, seconds for small changes, longer for a first build or a big component list
• YAML anchors and packages help, but managing config across a dozen devices is still more upkeep than Tasmota’s flash-and-forget model
• Assumes some comfort with GPIO pinouts and basic electronics; picking the wrong pin for a sensor is a common first stumbling block

FAQ

Is ESPHome free?

Yes. ESPHome is free and open source, MIT for the Python codebase and GPLv3 for the C++ runtime that ends up on the device. There’s no paid tier and no account requirement to compile or flash.

Do I need to know C++ to use ESPHome?

No, not for the majority of devices. ESPHome generates the C++ for you from YAML. Writing raw C++ only comes up for genuinely custom components that don’t already exist in the library, which is a small minority of homelab use cases.

Does ESPHome need MQTT to work with Home Assistant?

No. The default and recommended path is ESPHome’s own native API, added directly in Home Assistant with no broker involved. MQTT is still available as an option, mainly useful when other systems besides Home Assistant need the same sensor data.

Is ESPHome owned by Nabu Casa?

Not anymore. Nabu Casa acquired ESPHome from creator Otto Winter in 2021 to keep it funded and maintained, then donated it to the Open Home Foundation in 2024, the non-profit that also governs Home Assistant. Nabu Casa remains a commercial supporter of the foundation, but doesn’t own ESPHome outright.

Should I pick ESPHome or Tasmota?

If Home Assistant is the only thing consuming device data and you like keeping configs in text files, ESPHome’s native integration and YAML model fit better. Tasmota still makes sense for a quick one-off flash of a generic smart plug, or if you’re deep in an existing MQTT-based setup already.

ESPHome is worth reaching for the moment you want a sensor or switch that doesn’t exist as a retail product, or want to replace a cloud-dependent smart plug’s stock firmware with something that stays local. Pair it with Home Assistant for the dashboard and automations, and Node-RED once flows built from ESPHome sensor events get more complex than the built-in automation editor handles cleanly. Our homelab setup guide for beginners covers the baseline hardware before you start flashing microcontrollers.