A lot has changed since I wrote my original articles about ESPHome. The ecosystem has matured significantly, and ESPHome is now maintained by the Open Home Foundation. The tooling has been simplified with the introduction of the ESPHome Device Builder, making it easier than ever to create smart home devices.
This article replaces my previous guides on flashing ESP chips with ESPHome and the 2022 update.
What is ESPHome?
ESPHome allows you to create configurations that turn common microcontrollers into smart home devices. A device configuration consists of one or more YAML files, and based on the content of these files, ESPHome creates custom firmware which you can install directly onto your device.
Hardware defined in the configuration—such as sensors, switches, lights, and so on—will automatically appear in Home Assistant's user interface. No coding required!
There are two parts to ESPHome:
- The firmware that runs on your device/microcontroller
- The ESPHome Device Builder that runs on your computer or Home Assistant server, providing a web interface to create, edit, and install configurations
What are ESP32 and ESP8266 boards?
ESP boards are low-cost Wi-Fi chips with built-in flash memory, allowing you to build single-chip devices capable of connecting to Wi-Fi. Newer versions like the ESP32 also provide BLE (Bluetooth Low Energy) connectivity.
You can buy them for about 4-9 euros on AliExpress or with faster delivery on Amazon.
Read more about ESP boards in my introduction to ESP boards article.
Installing ESPHome Device Builder
The easiest way to get started with ESPHome is to install the Device Builder as a Home Assistant add-on.
- In Home Assistant, go to Settings → Add-ons → Add-on Store
- Search for ESPHome Device Builder and click on it
- Click the Install button
- Once installed, click Start
- Click Open Web UI to launch the Device Builder
Alternatively, you can use this button to go directly to the add-on page:
Note: If you're running Home Assistant Core or in a way that does not provide access to add-ons, you can run the ESPHome Device Builder independently in Docker.
Creating Your First Device Configuration
When you open the Device Builder for the first time, a wizard will guide you through creating your first configuration. You have three options:
New Device Setup
The wizard guides you through platform selection, board configuration, and Wi-Fi setup to create a basic working configuration. This is the recommended option for beginners.
Import from File
Upload an existing ESPHome configuration file (.yaml or .yml). This is useful for restoring backups and migrating configurations from other systems.
Empty Configuration
Creates a minimal configuration file for advanced users who prefer to write their own configuration from scratch or paste from devices.esphome.io.
Initial Installation on Your Device
After creating your configuration, you'll need to install it on your ESP device. The initial installation is often the most challenging part—but only until you've done it a few times!
Method 1: Direct USB Installation (Recommended)
This is the easiest method if your Home Assistant runs with HTTPS:
- Connect your ESP board to your computer via USB
- In the Device Builder, click the three-dot menu on your device and select Install
- Choose Plug into this computer
- A browser popup will appear—select your device's COM port and click Connect
- ESPHome will compile and flash the firmware directly from your browser
Note: This method requires HTTPS. If you use Nabu Casa, you can use the secure public URL found in Settings → Home Assistant Cloud → Remote Control.
Method 2: Plug into Home Assistant Server
If your ESP is connected directly to your Home Assistant server via USB:
- Connect the ESP board to a USB port on your Home Assistant server
- In the Device Builder, click Install on your device
- Choose Plug into the computer running ESPHome Dashboard
- Select the correct serial port and proceed with installation
Method 3: Manual Download
If the above methods don't work for your setup:
- Click Install and choose Manual Download
- Wait for compilation to complete and download the .bin file
- Go to ESPHome Web in your browser
- Connect your ESP via USB and click Connect
- Select Install and choose your downloaded .bin file
Device Builder Interface
Once you have devices configured, the main page displays all your configuration files. For each device, you can:
- UPDATE: Appears when the device runs an older ESPHome version than available in the add-on
- EDIT: Opens the configuration editor
- LOGS: View device logs via USB/serial or Wi-Fi connection
- Overflow menu (three dots):
- Validate: Check configuration for errors
- Install: Open the install dialog
- Clean Build Files: Delete generated build files to fix compile issues
- Delete: Remove the configuration
Configuration files are stored in <HOME_ASSISTANT_CONFIG>/esphome/.
Updating Your Device (Over-the-Air)
Once ESPHome is installed on your device, you never need to plug in a USB cable again! ESPHome supports Over-the-Air (OTA) updates.
Whenever you modify your device's configuration:
- Click Save to store your changes
- Click Install and choose Wirelessly
- ESPHome will compile and push the new firmware over Wi-Fi
Connecting Your Device to Home Assistant
Once your configuration is installed and the device connects to Wi-Fi, Home Assistant will automatically discover it. You'll see a notification offering to configure the new device.
Alternatively, manually add the device:
- Go to Settings → Devices & Services → Integrations
- Click Add Integration and search for ESPHome
- Enter the device hostname (e.g.,
living-room-sensor.local) or IP address
Adding Features to Your Device
Edit your device's YAML configuration to add components. Here's an example adding a GPIO switch:
switch:
- platform: gpio
name: "Living Room Dehumidifier"
pin: GPIO5
And a binary sensor for monitoring a GPIO pin:
binary_sensor:
- platform: gpio
name: "Living Room Window"
pin:
number: GPIO0
inverted: true
mode:
input: true
pullup: true
After adding components, save and install to update your device. The new entities will automatically appear in Home Assistant!
My ESPHome Projects
Read more about how I use ESPHome in my smart home:
- Make your fireplace smart with ESPHome
- Build a cheap Air Quality sensor using ESPHome
- Measure your water usage using ESPHome
Resources
Happy automating! 🏠