Getting started with ESPHome

What ESPHome is

You describe the device in a YAML file: which board, which sensors on which pins, how it reaches your network. ESPHome turns that description into firmware, compiles it and installs it on the board. Home Assistant then talks to the device over ESPHome’s native API, a direct connection on TCP port 6053 that can be encrypted with a 32-byte key.

There is no code to write for the usual parts. When you change the YAML, you install again and the device runs the new firmware.

Installing ESPHome

The tool you work in is called the ESPHome Device Builder: a web dashboard that keeps your YAML files, compiles them and installs the firmware. Pick one way to run it:

• In Home Assistant. Go to Settings → Apps → Install app, find ESPHome Device Builder, then click Install, Start and Open Web UI. Home Assistant now calls its add-ons “apps”; if the app is missing, add the repository https://github.com/esphome/home-assistant-addon from the ⋮ menu.
• As a desktop app. The install page offers ESPHome Device Builder for macOS (a .dmg), Windows and Linux (a .deb or an AppImage). On Linux, add yourself to the dialout group if serial ports don’t show up.
• In Docker. The same dashboard listens on port 6052. Run the container with host networking (--net=host) so it can find devices by mDNS; with Docker Desktop, publish port 6052 instead.
• On the command line. Run pip install esphome (in a virtual environment if you can); then esphome run living-room.yaml validates, compiles, installs and shows the logs in one go.

For the very first flash you can also use ESPHome Web at web.esphome.io, which writes firmware to a board straight from the browser. It needs Web Serial: Chrome, Edge and, according to the ESP Web Tools documentation, Firefox; not iOS.

Choosing a board

Any ESP32 or ESP8266 development board will do. These four are common, cheap and well supported; the board ID is what goes in the YAML.

Board IDs checked with esphome config on ESPHome 2026.10.2. Our ESP32 comparison lists the differences between the chips.

If you are unsure, start with an ESP32 DevKit: this guide uses one, and most answers you will find online assume one.

A first configuration, line by line

In the Device Builder, Create device starts a wizard that writes most of this for you. Here is the whole file for a device called living-room, before any sensor:

esphome:
  name: living-room            # host name: lowercase, digits, hyphens
  friendly_name: Living room   # the name Home Assistant shows

esp32:
  board: esp32dev              # your board
  framework:
    type: esp-idf              # the default since 2026.1

logger:                        # log over USB and Wi-Fi

api:                           # the link to Home Assistant
  encryption:
    key: !secret api_key

ota:
  - platform: esphome          # updates over Wi-Fi
    encryption:                # reuses the API key

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
  ap:                          # fallback hotspot
    password: !secret ap_password

captive_portal:                # its setup page

• esphome: → name is the host name on your network, living-room.local: up to 31 characters, lowercase letters, digits and hyphens. friendly_name is what Home Assistant displays.
• esp32: → board tells ESPHome the chip and its flash size. Since ESPHome 2026.1 the framework defaults to ESP-IDF on the ESP32; writing it out keeps the file clear. Arduino is still supported with type: arduino.
• logger: → logs over USB and over the network, at DEBUG level and 115200 baud by default.
• api: → the native API that Home Assistant uses, with its encryption key. Without a key the connection isn’t encrypted.
• ota: → updates over Wi-Fi. Since ESPHome 2026.9 an empty encryption: encrypts them with the API key.
• wifi: → your network, read from secrets.yaml. ap: starts a fallback hotspot, named after the device, if it can’t connect within 90 seconds.
• captive_portal: → a page on that hotspot where you can enter new Wi-Fi details.

The !secret values come from a second file, secrets.yaml, in the same folder:

wifi_ssid: "MyNetwork"
wifi_password: "MyWiFiPassword"
api_key: "…"                   # openssl rand -base64 32
ap_password: "…"

The API key is 32 random bytes in base64: the wizard makes one, or the command in the comment does. Keep secrets.yaml out of anything you publish.

A first sensor: BME280 over I²C

A BME280 measures temperature, humidity and pressure and talks over I²C, so it needs two signal wires. On an ESP32 DevKit, ESPHome’s usual I²C pins are GPIO21 for SDA and GPIO22 for SCL.

Add this to the end of the file:

i2c:
  sda: GPIO21
  scl: GPIO22
  scan: true                   # lists the addresses it finds

sensor:
  - platform: bme280_i2c
    address: 0x76              # or 0x77, see the log
    temperature:
      name: Temperature
    pressure:
      name: Pressure
    humidity:
      name: Humidity
    update_interval: 60s

• i2c: → the bus and its pins. scan: true, the default, lists the addresses it finds in the log.
• platform: bme280_i2c → the BME280 driver. Its default address is 0x77; many cheap boards answer on 0x76, as here. Our BME280 address page explains how the SDO pin chooses between them.
• Each reading gets a name, which becomes an entity in Home Assistant. update_interval: 60s reads the sensor once a minute.

Prefer to click? Our generator builds an equivalent file, with this BME280 already added, and makes the keys for you. It puts the API key in the file itself rather than in secrets.yaml, and adds Wi-Fi signal and uptime sensors.Open the ESPHome generator

Choosing a different sensor? Our sensor comparison puts the common ones side by side, from the DHT22 to the SHT4x.

First flash over USB, then over Wi-Fi

The very first install has to go over a USB cable. In the Device Builder, click Install on the device card and pick how:

• Plug into this computer flashes from your browser. It uses Web Serial, which needs a secure page: the dashboard opened over HTTPS, or on localhost, as with the desktop app.
• Plug into the computer running ESPHome Device Builder flashes from the machine that runs the dashboard, for example your Home Assistant server.
• Manual download, then Factory format, gives you a .bin file to write with ESPHome Web: Connect, choose the port, Install.

On the command line, esphome run living-room.yaml asks which serial port to use. If no port appears:

• Try another USB cable: charge-only cables have no data wires.
• Install the driver for the board’s USB-serial chip, usually a CH34x or a CP2102.
• Hold the board’s BOOT button while you plug it in, then release it: that starts the chip in download mode.

Once the device has joined your Wi-Fi, every later Install offers Wirelessly, and esphome run uploads over the network.

Adding it to Home Assistant

If mDNS works on your network, Home Assistant finds the new device by itself. Go to Settings → Devices & services: under Discovered you’ll see an ESPHome card with its name. Click Configure, enter the encryption key when asked (when the Device Builder runs as a Home Assistant app it is often filled in for you), and pick an area.

If nothing is discovered, click Add integration, choose ESPHome and enter living-room.local or the device’s IP address. The sensor’s three readings appear as entities, ready for the dashboard.

The integration’s options include Allow the device to perform Home Assistant actions, off by default. Turn it on only for devices you trust, and only if your YAML needs it.

Reading the logs

The log is where every problem shows up first. In the Device Builder, Logs reads it over USB if the board is plugged in, otherwise over the network; on the command line, esphome logs living-room.yaml. When you connect, the device prints its configuration, including the I²C scan:

[C][i2c:113]: Results from bus scan:
[C][i2c:119]: Found device at address 0x76

The number after i2c is a line number in ESPHome’s source code, so it changes from one version to the next. “Found no devices” means a wiring or power problem, not a YAML one. A reading every minute, in [D] lines, means the sensor works.

Common errors

Strapping pins decide how the chip starts; a sensor or LED holding one of them high or low can stop it booting.

Security

• API encryption. Always set a key: without it the connection is neither encrypted nor tied to a secret, so any device on your network can connect.
• Encrypted updates. With encryption: under ota: (ESPHome 2026.9 and newer) the device only accepts firmware encrypted with your key. Older guides use password:; ESPHome now warns that it costs flash and RAM and recommends encryption, and the two can’t be combined.
• A password on the fallback hotspot. Its page lets whoever connects change the Wi-Fi settings and upload firmware.
• Keep secrets.yaml private, and back it up: without the key you can’t update the device over Wi-Fi.

Keeping it up to date

ESPHome ships a new version every month. Updating the Device Builder (or pip install --upgrade esphome) doesn’t change your devices: each one keeps running the firmware last installed on it until you click Install again. Read the release notes’ breaking changes first, then update one device before the rest.

On a battery: deep sleep

A sensor that only needs to report every few minutes can sleep in between with the deep_sleep: component, set with run_duration and sleep_duration. While it sleeps Home Assistant shows it as unavailable, and it can only take an update while it is awake. Choosing the board, battery and regulator, with real current figures, is covered in our guide to powering an ESP32 from a battery.