How to Install ESPHome with Home Assistant — Complete Guide

ESPHome is an open‑source firmware framework that allows you to turn common microcontrollers — such as ESP32, ESP8266, and RP2040 boards — into fully controllable smart home devices.

A device “configuration” in ESPHome is made up of one or more YAML files. Based on these files, ESPHome compiles custom firmware that you can install directly onto your device. Any hardware defined in the configuration — sensors, switches, lights, etc. — will automatically appear in Home Assistant’s interface.

ESPHome has two main parts:

1. The firmware that runs on your microcontroller.

2. The management tool that runs on your computer or server (e.g., a Raspberry Pi, laptop, or desktop) — in this guide, we’ll use the ESPHome Device Builder add‑on for Home Assistant, which provides a simple web UI to create, edit, and install configurations.

1. Installing the ESPHome Device Builder Add‑on

The easiest way to get started is to install ESPHome as a Home Assistant add‑on.

Steps:

1. In Home Assistant, go to Settings → Add‑on Store.

2. Search for ESPHome and click Install.

3. Wait for the installation to finish (this may take a minute or two).

4. Click Start, then Open Web UI to launch the Device Builder.

Note: If your Home Assistant installation does not support add‑ons, you can run ESPHome Device Builder separately in Docker.

2. Creating Your First Configuration

When you open the Web UI for the first time, a setup wizard will guide you through creating your first device configuration.

You’ll need to:

• Enter a device name (lowercase with hyphens is recommended).

• Select your board type (e.g., ESP32 DevKit v1).

• Provide your Wi‑Fi SSID and password so the device can connect to your network after flashing.

Tip: The very first installation onto a new device is often the most intimidating step. If you’ve never done it before, check the Physically Connecting to your Device guide.

3. Flashing the Firmware for the First Time

After creating your configuration, you need to install it onto your device:

1. Connect your board to the Home Assistant host via USB.

2. In ESPHome, click Install and choose the USB option.

3. Once flashed, the device will connect to your Wi‑Fi and communicate with Home Assistant.

4. Exploring the Device Builder Interface

The ESPHome Device Builder home screen lists all your device configurations (“nodes”). For each configuration, you can:

• Update — if the device’s ESPHome version is older than the add‑on’s version.

• Edit — open the YAML configuration editor.

• Logs — view device logs via USB/serial or over Wi‑Fi.

• Overflow menu — access extra actions:

  • Validate — check the configuration for errors.

  • Install — open the install dialog.

  • Clean build files — delete generated build files to fix compile issues.

  • Delete — remove the configuration.

Note: Config files are stored in <HOME_ASSISTANT_CONFIG>/esphome/. Accessing them directly may require the SSH add‑on and disabling “Protection mode” — assess the security implications before doing so.

5. Adding Functionality to Your Device

Example: GPIO Switch

Open your device’s YAML file in the editor and add:

 
switch:
  - platform: gpio
    name: "Living Room Dehumidifier"
    pin: GPIO5
  

This creates a switch entity in Home Assistant that controls whatever is connected to GPIO5 — it could be a light, fan, or any other device.

n the example above, we’re simply adding a switch that’s called “Living Room Dehumidifier” and is connected to the pin GPIO5. This switch could really control anything – lights or a tabletop fan, for example. Its name and function is arbitrary and should be set as is appropriate for your particular application.

Example: Binary Sensor

To monitor a GPIO pin’s state (e.g., a window contact sensor), add:

  - platform: gpio
    name: "Living Room Window"
    pin:
      number: GPIO0
      inverted: true
      mode:
        input: true
        pullup: true
  

After editing, click Save to store your changes.

6. Updating Your Device

Saving the YAML file does not automatically update the device. Each time you make changes:

1. Click Install to recompile the firmware.

2. Reinstall it onto the device.

If ESPHome is already installed on the device, you can update it wirelessly (OTA) without reconnecting USB.

7. Connecting the Device to Home Assistant

 ADD INTEGRATION TO MY

Once the device is flashed and connected to Wi‑Fi:

• Home Assistant should auto‑discover it (if your network supports mDNS).

• If not, go to Settings → Devices & Services → Add Integration, search for ESPHome, and enter the device’s hostname (e.g., living-room-lamp.local) or IP address.

Repeat this process for each ESPHome device you add.

8. Where to Go Next

🎉 Congratulations — you’ve set up your first ESPHome project and installed custom firmware on your device! You’ve also learned how to add basic components via YAML.

Next steps:

• Browse the  Components Index to find all supported hardware.

• Check the FAQ for common questions.

• If you encounter issues or want to request features, open a ticket on the  GitHub issue tracker.