The first install is the awkward part of ESPHome. You need a USB data cable, a browser that talks to serial ports, and a board that actually enters programming mode. After that, every change can go over the air. This guide covers installing the Device Builder, creating a first configuration, flashing over USB, joining Wi-Fi, and connecting the device to Home Assistant.

What you need

  • An ESP32 board. For a first project the original ESP32 (ESP32-WROOM and similar) is the safest pick: ESPHome rates it as the best-supported platform. ESP32-S3, ESP32-C3 and ESP32-C6 are fine for new work; skip the ESP8266 for a new build unless you already own one that works.
  • A USB cable that carries data, not a charge-only cable. Charge-only cables are a common reason flashing never starts.
  • A computer with Chrome, Edge or Firefox (WebSerial support) if you flash from the browser.
  • Home Assistant with the ESPHome Device Builder app, or the Device Builder running as a desktop app or Docker container. The YAML is the same either way.

Install the ESPHome Device Builder

Most people run Device Builder next to Home Assistant:

  1. In Home Assistant go to Settings > Apps > Install App.
  2. Find ESPHome Device Builder, install it, start it, then open the web UI.
  3. If it is missing from the list, open the three-dot menu, choose Repositories, add https://github.com/esphome/home-assistant-addon, and look again.

You can also install a desktop Device Builder for Windows, macOS or Linux from the ESPHome install page, or run the official Docker image and open http://localhost:6052. Compiling on a Home Assistant Green or a Raspberry Pi can take several minutes; the Device Builder can hand the compile to another dashboard on a faster machine on your network if you pair them in Settings.

Create the first configuration

Open Device Builder. With an empty list it invites you to create a device. Choose New Device Setup unless you already have a YAML file to import.

The wizard asks for a name, the platform (ESP32) and Wi-Fi credentials. Enter the Wi-Fi details when prompted. Without them the board cannot reach the network, Home Assistant cannot discover it, and later updates over the air will not work. Device Builder stores those credentials in secrets.yaml in the ESPHome config directory and references them with !secret in the device file, so you do not paste the password into every YAML you share.

At the end you have a minimal configuration: Wi-Fi, logging, the Home Assistant API and OTA updates. That is enough to flash.

A typical skeleton looks like this (names and secrets will match what the wizard wrote):

esphome:
  name: living-room-node

esp32:
  board: esp32dev
  framework:
    type: esp-idf

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

  ap:
    ssid: "Living-Room-Fallback"
    password: !secret ap_password

captive_portal:

logger:

api:
  encryption:
    key: !secret api_encryption_key

ota:
  - platform: esphome
    password: !secret ota_password

Exact keys in secrets.yaml depend on how the wizard named them. Keep secrets.yaml off public repos; Device Builder is set up to ignore it when the config directory is a git repo.

Flash over USB the first time

The first install must use a USB cable. Wireless install only works after ESPHome is already on the chip.

  1. Plug the board into the computer that can see the serial port. If Home Assistant and Device Builder run on a different machine than the one with the USB port, use Install > Plug into this computer so the browser on your laptop opens ESPHome Web and talks to the board locally.
  2. In Device Builder click Install on the device card and follow the prompts. For a browser flash you need WebSerial (Chrome, Edge or Firefox).
  3. Select the serial port when asked. On Linux the port is often /dev/ttyUSB0 or /dev/ttyACM0; on Windows it shows as a COM port in Device Manager.
  4. Wait for the compile and upload to finish. The board reboots into your configuration.

If the browser says it failed to initialize, unplug the board, hold the BOOT button while you reconnect and select the port, and keep holding until preparation starts. Some boards also need a short press of RESET while BOOT is held. If the port never appears, try another cable, another USB port, and the USB-to-serial drivers for your board's chip (CP210x, CH340 and similar).

You can also download a firmware binary from Device Builder (Install > Manual download) and flash it with ESPHome Web or with esptool. Those paths process the file on your machine; nothing is uploaded to a cloud service.

Join Wi-Fi and open the logs

After a successful flash the board should associate with the SSID you configured. In Device Builder the card should flip to Online. Open Logs on that card: over USB you get the serial console; once the device is on the network, logs come over the API.

If the board stays offline, check that the SSID and password in secrets.yaml match a 2.4 GHz network the ESP32 can join, that the board is in range, and that you did not use a charge-only cable that left the first flash incomplete. For a hidden SSID, enable fast_connect under wifi:. A static IP (manual_ip) helps when mDNS is unreliable across VLANs.

Add the device in Home Assistant

When the node is on Wi-Fi, Home Assistant usually discovers it automatically if mDNS works on your LAN. Accept the discovery under Settings > Devices & services.

To add it by hand: Add Integration, search for ESPHome, and enter the hostname or IP. A device named living-room-node is reachable as living-room-node.local when mDNS works. If you use the encrypted API (default in current wizards), paste the encryption key from Device Builder (overflow menu > Show API Key) when Home Assistant asks for it.

Repeat discovery for each new ESPHome node. After the first USB flash, later edits only need Save then Install; choose the wireless option so you can leave the board where it lives.

Add something useful before you stop

A bare Wi-Fi node is a good smoke test, but you will want at least one entity. ESPHome's getting-started guide uses a GPIO switch as the first example:

switch:
  - platform: gpio
    name: "Desk Lamp"
    pin: GPIOXX

Replace GPIOXX with the pin wired to your relay or LED. On many NodeMCU-style boards you can use labels such as D1 instead of the raw GPIO number. Save, install over the air, and the switch appears in Home Assistant without further YAML on the server side.

Avoid strapping pins (often GPIO0 and similar) for outputs that might be pulled the wrong way at boot, unless you know the board's boot requirements. ESPHome warns about those pins in the compile log.

Common first-flash problems

  • Port missing or "Failed to initialize". Charge-only cable, missing drivers, or the board not in bootloader mode. Hold BOOT while selecting the port.
  • Compile succeeds, Wi-Fi never comes up. Wrong secrets, 5 GHz-only SSID, or the board still running stock firmware because the USB step never finished.
  • "Brownout detector was triggered". The 3.3 V rail dipped during a Wi-Fi transmit spike. Use a stronger 5 V supply, a short thick USB cable, lower wifi.output_power, or add bulk capacitance on 3.3 V as the ESPHome FAQ describes.
  • Device online in Device Builder but Home Assistant never finds it. mDNS blocked between VLANs or Docker without host networking. Add the integration with a fixed IP, or fix multicast routing.
  • Underscores in the hostname. Prefer hyphens in name:. Underscores are invalid in hostnames per common DNS practice and break some router setups.

What to do next

Browse the ESPHome components index for the sensor or bus you actually have on the bench. Keep one secrets.yaml for Wi-Fi, API keys and OTA passwords, and treat Device Builder as the place you edit YAML - saving alone never changes the chip until you install again.