HACS and Customization

How to Set Up ESPHome With Home Assistant, Step by Step

Install the ESPHome Device Builder add-on, flash your first ESP board over USB, then adopt it in Home Assistant. Steps for Home Assistant OS and Container.

On this page
  1. What you need
  2. Step 1: Install ESPHome Device Builder (Home Assistant OS)
  3. Step 2: Create the device config
  4. Step 3: Flash the first time over USB
  5. Step 4: Adopt the device in Home Assistant
  6. Step 5: Update over Wi-Fi
  7. Container installs
  8. Optional: a fallback hotspot
  9. Troubleshooting flashing
  10. Safety

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)

  1. Go to Settings > Apps (older releases call this Add-ons) and open the app store.
  2. 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-addon under the three-dot menu, using Repositories.
  3. Turn on Show in sidebar and Watchdog, then select Start.

Step 2: Create the device config

  1. Open the ESPHome dashboard from the sidebar and select New device.
  2. Enter a name for the device, then choose its chip, such as ESP32 or ESP8266.
  3. The wizard stores your Wi-Fi details in secrets.yaml, using the keys wifi_ssid and wifi_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

  1. 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.
  2. 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.

The complete guide to hacs and customization

What Is HACS and How to Install It in Home Assistant
Read the guide

Keep exploring

Guides from other topics

All topics →