ESPHome lets you describe a device in a YAML file and flash it to an ESP board. Home Assistant then finds the device and adds it, without MQTT. This guide covers Home Assistant OS first, and then Container installs. Before you start, you may want to read ESPHome compared with Tasmota to confirm it is the right firmware for your board.
What you need
- A working Home Assistant install
- An ESP8266, ESP32 or similar board. Most of these chips support 2.4 GHz Wi-Fi only. The ESP32-C5 also supports 5 GHz.
- A USB cable that carries data. A charge-only cable causes “no port found” errors.
- A USB-serial driver if your board uses one. The common ones are CP210x and CH340.
- Your Wi-Fi name and password
Step 1: Install ESPHome Device Builder (Home Assistant OS)
- Go to Settings > Apps (older releases call this Add-ons) and open the app store.
- Search for ESPHome Device Builder and select Install. This add-on was called ESPHome before 2024. If it doesn’t appear, add
https://github.com/esphome/home-assistant-addonunder the three-dot menu, using Repositories. - Turn on Show in sidebar and Watchdog, then select Start.
Step 2: Create the device config
- Open the ESPHome dashboard from the sidebar and select New device.
- Enter a name for the device, then choose its chip, such as ESP32 or ESP8266.
- The wizard stores your Wi-Fi details in
secrets.yaml, using the keyswifi_ssidandwifi_password.
A minimal configuration looks like this:
esphome:
name: living-room-sensor
esp32:
board: esp32dev
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
api:
ota:
- platform: esphome
logger:
The wizard also adds an encryption key under the api: block. Home Assistant asks for that key when you adopt the device, so keep it handy. The ota: syntax shown above is the format used since ESPHome 2024.6.
Step 3: Flash the first time over USB
The first flash must go over USB. Plug the board into the computer you are using, then in the dashboard choose Install and then Plug into this computer.
This method uses Web Serial, which works only in Chrome and Edge, and only when Home Assistant is served over HTTPS. If it doesn’t work for you, choose Manual download instead, and flash the .bin file with the ESPHome Web tool at web.esphome.io.
Step 4: Adopt the device in Home Assistant
- Once the board connects to Wi-Fi, Home Assistant usually detects it. Go to Settings > Devices & services and select Configure on the discovered ESPHome card.
- When Home Assistant asks, enter the encryption key from the
api:block.
If Home Assistant doesn’t find the device, add it manually. Choose Add integration, select ESPHome, and enter the device’s hostname, such as living-room-sensor.local, or its IP address, with port 6053. Enter the encryption key if you set one.
Step 5: Update over Wi-Fi
After the first flash, update the device from the dashboard with Install, then Wirelessly. Over-the-air updates use port 3232 on ESP32 and port 8266 on ESP8266.
To add components, edit the YAML and choose Install, then Wirelessly. The first compile on a Raspberry Pi can take 5 to 15 minutes or more.
Container installs
If you run Home Assistant Container, run the official ESPHome Docker image, esphome/esphome, instead of the add-on. Mount a volume for your configuration folder, so your device files survive restarts.
Optional: a fallback hotspot
Add an ap: block under wifi: and a captive_portal: section to your configuration. If the device can’t join your Wi-Fi, it opens its own hotspot, so you can reconnect it.
Troubleshooting flashing
- The board won’t enter flash mode. Hold the BOOT (GPIO0) button while you connect the board.
- No serial port appears. Try a different USB cable. Charge-only cables are a common cause.
- The driver is missing. Install the CP210x or CH340 driver for your board.
- The flash option is missing. Use Chrome or Edge. Firefox and Safari can’t flash over Web Serial.
Safety
Don’t wire mains voltage to development boards. If a device needs to switch mains loads, use a rated relay module designed for that purpose.