Home Assistant ESPHome: Getting Started Guide
ESPHome is a system that turns inexpensive ESP32 and ESP8266 microcontrollers into local, Wi-Fi-connected sensors and switches that talk directly to Home Assistant. You describe what a device should do in a short YAML file, ESPHome compiles that into firmware, flashes it to the board, and the device then appears in Home Assistant automatically. To get started, install the ESPHome Device Builder add-on, create a device configuration, flash it once over USB, and let Home Assistant discover it. The rest happens over the air.
What you need before you start
ESPHome is free and open source, maintained by the same organization behind Home Assistant. The friction is almost entirely in the first flash, so it helps to have the right pieces ready.
- A supported board. An ESP32 dev board is the common starting point because it has Bluetooth and more memory than the older ESP8266. Both work.
- A USB data cable. Many cheap USB cables are charge-only and will not enumerate the board. This is the single most common reason a first flash fails.
- 2.4 GHz Wi-Fi. ESP chips do not connect to 5 GHz networks. If your router broadcasts one merged network name, the board will still find the 2.4 GHz band, but a dedicated 2.4 GHz SSID removes doubt.
- Home Assistant with the add-on store, which means a Home Assistant OS or Supervised install. If you are still deciding on an install method, see our beginner's guide to installing Home Assistant.
Step 1: Install the ESPHome add-on
In Home Assistant, open Settings > Add-ons, go to the add-on store, and install ESPHome Device Builder (listed under official/community add-ons). After it installs, enable Show in sidebar and start it. This add-on is the web interface where you create, compile, and flash device configurations — it is separate from the ESPHome integration, which is what actually connects finished devices to Home Assistant.
Step 2: Create your first device
Open the ESPHome dashboard from the sidebar and click New device. Give it a name, pick your board type, and provide your Wi-Fi SSID and password when prompted. ESPHome stores those credentials as reusable secrets, so you only type them once even if you build ten devices later.
The wizard generates a starter YAML file. At minimum it contains the board definition, Wi-Fi settings, an OTA section, and an API block that lets Home Assistant talk to the device. It also creates an encryption key for that API connection — keep it, because Home Assistant will ask for it during discovery.
Step 3: Flash the device once over USB
Plug the board into the computer running your browser (not necessarily the Home Assistant server). Use Install > Plug into this computer and let the browser-based installer flash it directly. This first flash is the only time you need a cable. Once the firmware is on the board and it joins Wi-Fi, every future change compiles and uploads wirelessly.
- 1Create the device in the ESPHome dashboard
- 2Connect the board with a USB data cable
- 3Flash the initial firmware from the browser
- 4Wait for the board to join Wi-Fi and report “online”
- 5Adopt it in Home Assistant when the discovery card appears
Step 4: Adopt the device in Home Assistant
Within a minute or two of coming online, Home Assistant detects the device and shows a Discovered card under Settings > Devices & services. Click to configure it, paste the API encryption key if asked, and the device's sensors and controls become entities you can drop on a dashboard or use in automations. If you are new to those, our automations for beginners guide is a good next stop.
Step 5: Add sensors and outputs
A bare device is not useful yet — you add capabilities by editing its YAML. ESPHome's component library covers temperature and humidity sensors, motion and contact sensors, relays, LEDs, buttons, and much more. Each component is a small block of YAML that references a GPIO pin. After editing, click Install and the update flashes over the air.
ESPHome vs. off-the-shelf integrations
ESPHome is not always the right tool. Here is how it compares to buying a ready-made device.
| Factor | ESPHome (DIY) | Off-the-shelf smart device |
|---|---|---|
| Setup effort | Higher — flashing and YAML | Lower — app pairing |
| Local control | Always local, no cloud | Often cloud-dependent |
| Cost per node | Low (a few dollars) | Varies, usually higher |
| Customization | Full — you define behavior | Limited to the vendor's app |
If your goal is a mesh of battery-powered sensors instead of Wi-Fi nodes, ESPHome may not be the best fit — weigh it against a dedicated radio, as we cover in Zigbee vs. Z-Wave for Home Assistant.
Keeping it maintainable
Because every device is defined in YAML, ESPHome configs are easy to back up and reuse. Save copies of your device files alongside your regular Home Assistant backups so a rebuild is a copy-paste rather than a redo. Shared configuration — Wi-Fi, common sensors — can be pulled into a reusable package to avoid repeating yourself across many boards.
Frequently asked questions
Do I need an account or the cloud for ESPHome?
No. ESPHome runs entirely on your own hardware and communicates with Home Assistant over your local network. There is no vendor account, no companion app, and devices keep working if your internet drops.
Can I flash a device without a soldering iron?
Yes. Most ESP32 and ESP8266 dev boards have a USB port and flash directly from the browser. Soldering only comes in when you wire external sensors or relays to the board's pins.
Why does my device flash but never appear in Home Assistant?
The board is online but not reachable, or it never joined Wi-Fi. Check that you used a 2.4 GHz network, that the SSID and password secrets are exact, and that the ESPHome integration is installed. The ESPHome dashboard's status indicator tells you whether the board itself is online.
Is ESPHome only for advanced users?
No, though it asks more of you than pairing a plug in an app. The wizard writes the hard parts, and the payoff is fast, fully local devices. If you have already added HACS or add-ons, ESPHome is a comparable step up.