ESPHome Explained: Build Your First Smart Home Device with ESP32

ESPHome empowers users to convert common microcontrollers into smart home devices without complex programming. The idea of creating your own smart energy meter or voice assistant might interest you. ESPHome and ESP32 make this possible!

ESPHome generates custom firmware from YAML configuration files that install directly onto your device. Smart home enthusiasts have successfully built energy meters that track their home’s electricity consumption and show data through smartphone apps.

These ESP32 devices prove even more valuable once connected to Home Assistant, an open-source software that monitors IoT devices. Users can create automations to receive alerts if their home’s temperature falls below specific thresholds. ESPHome’s uninterrupted WiFi connectivity between ESP32 and ESP8266 boards and Home Assistant makes the setup straightforward.

What is ESPHome and How It Works with ESP32

ESPHome transforms YAML configuration files into custom firmware for microcontrollers that turn them into smart home devices. You won’t need complex programming skills – just a few lines of configuration can create your own smart devices.

ESPHome architecture: device and host components

ESPHome works through two main components that team up to create and manage your smart devices:

1. Device Component: The firmware running on your microcontroller (like the ESP32) makes your hardware “smart.” It reads sensors, controls switches, and talks to your home network.
2. Host Component: Your computer system (like a Raspberry Pi or laptop) runs this part. It helps you build configurations, create firmware, and load it onto your devices. Think of it as your workshop where smart devices come to life before deployment.

The process starts with creating a YAML configuration file on the host component. This configuration becomes custom firmware loaded onto your ESP32. Your device runs by itself after installation but stays connected to your smart home system.

The beauty lies in the simple YAML configuration – you don’t need to know C++ programming to build custom devices.

Supported microcontrollers and use cases

ESPHome supports microcontrollers of all types, not just ESP boards:

• ESP32: The powerhouse option comes with WiFi, Bluetooth, extra memory, and GPIO pins. Perfect for complex projects like voice assistants or multi-sensor devices.
• ESP8266: A budget-friendly choice with WiFi support works great for basic sensors and switches.
• RP2040: The microcontroller from Raspberry Pi (like the Pi Pico).
• BK72xx: Beken microcontrollers show up often in smart home devices.
• RTL87xx: Realtek microcontrollers support various wireless protocols.
• Host: Some ESPHome components can run on regular computers too!

ESP32 stands out as the most reliable choice for most projects. Its built-in features deliver better performance than the ESP8266, making it ideal for complex setups.

How ESPHome integrates with Home Assistant

ESPHome devices connect to Home Assistant smoothly yet powerfully. Your ESP32 device connects through these steps:

1. Home Assistant finds ESPHome devices on your network automatically through mDNS (network permitting).
2. Adding the device takes just one click once it appears as an integration.
3. Every sensor, switch, and component from your configuration shows up in Home Assistant’s interface automatically.

This integration shines because of its communication method. Home Assistant maintains a constant connection to each ESPHome device instead of checking for updates regularly. Your sensors and switches update instantly in Home Assistant.

The ESP32 device and Home Assistant communicate through a lightweight, two-way protocol over TCP built specifically for microcontrollers. This creates a responsive system where automations react right away to ground changes.

Installing ESPHome in Home Assistant

Building your own smart home devices starts with ESPHome setup. You can choose from multiple installation methods based on your current configuration.

Installing ESPHome add-on in Home Assistant OS

Home Assistant OS makes ESPHome installation quick and simple. Here’s what you need to do:

1. Log into your Home Assistant dashboard
2. Click on your username in the lower left corner and enable “Advanced Mode”
3. Go to Settings → Add-ons → Add-on Store
4. Search for “ESPHome” and click on it
5. Press the INSTALL button and wait until completion
6. After installation, click “Start” and then “Open Web UI”

The ESPHome add-on might not appear in your store. Some users fixed this by adding https://github.com/hassio-addons/repository.

Important: You can only use ESPHome add-ons with Home Assistant Operating System or Home Assistant Supervised installations. Docker container installations won’t support add-ons.

Running ESPHome in Docker for advanced users

Docker container users can run ESPHome separately with these commands:

docker pull ghcr.io/esphome/esphome

Create a storage folder for your ESPHome configurations:

mkdir -p /opt/esphome/

Launch the container:

docker run -d --name esphome \
  -v /opt/esphome:/config \
  -v /etc/localtime:/etc/localtime:ro \
  --restart always \
  --privileged \
  --network host \
  -e USERNAME=YOUR_NAME \
  -e PASSWORD=YOUR_PASSWORD \
  ghcr.io/esphome/esphome

Docker-compose offers an alternative approach. Create a docker-compose.yml file with:

version: '3'
services:
  esphome:
    container_name: esphome
    image: ghcr.io/esphome/esphome
    volumes:
      - /path/to/esphome/config:/config
      - /etc/localtime:/etc/localtime:ro
    restart: always
    privileged: true
    network_mode: host
    environment:
      - USERNAME=test
      - PASSWORD=ChangeMe

Note for Mac users: Mac’s Docker implementation doesn’t support USB device passthrough. Web flashing works, but USB flashing won’t be available.

Accessing the ESPHome dashboard

You can reach the ESPHome dashboard through:

• Home Assistant Add-on: Click “OPEN WEB UI” on the add-on page
• Docker Installation: Visit http://[your-server-ip]:6052 in your browser

Browser cookie blocking or enhanced tracking protection might cause “401 Unauthorized” errors when accessing the dashboard.

The dashboard lets you:

• Create new device configurations
• Edit existing configurations
• Check your YAML files
• Flash firmware to devices (USB or Over-The-Air)
• View device logs

Docker users can add the ESPHome dashboard to Home Assistant’s sidebar through an iFrame panel configuration in their configuration.yaml file.

Your ESPHome installation now stands ready. You can start creating device configurations and building smart home devices with your ESP32.

Creating and Flashing Your First ESP32 Device

You’ve got ESPHome installed, and now comes the exciting part – building your first smart device with an ESP32!

Creating a new device in ESPHome dashboard

The first device setup is straightforward. Look for the New Device button in your ESPHome dashboard and click it. A setup wizard will walk you through the configuration steps.

Your device needs a name first. Choose something descriptive based on its function or location, such as “living_room_sensor” or “kitchen_light”. Remember to use underscores instead of spaces.

The next step is selecting your ESP chip type. Pick ESP32 from the list. You’ll also need your WiFi credentials so your device can connect to your network once it’s ready.

Writing a simple YAML configuration

The system creates a YAML configuration file after device setup. This file works like a recipe that tells ESPHome your device’s functions.

A typical configuration looks like this:

esphome:
  name: living_room_light
  platform: ESP32
  board: esp32dev

wifi:
  ssid: "YourWiFiName"
  password: "YourWiFiPassword"

# Enable logging
logger:

# Enable Home Assistant API
api:

# Enable over-the-air updates
ota:

The device needs components to be useful. To cite an instance, see how to add a switch connected to GPIO pin 5:

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

Click Save after making your changes.

Flashing firmware via USB or OTA

The next step puts your configuration on your ESP32 device. Your first upload requires a USB connection to your computer. Here’s the process:

1. Connect your ESP32 to your computer with a USB cable
2. Find your device in the ESPHome dashboard and click Install
3. Select Plug into this computer at the prompt
4. Pick the right USB port from the list (like /dev/ttyUSB0 on Linux or COM3 on Windows)
5. Let ESPHome compile and upload the firmware

The first installation often presents the biggest challenge. Once complete, you can update your device wirelessly through Over-The-Air (OTA) updates.

Future updates are simpler. Make configuration changes, save them, and click Install. Just choose Wirelessly instead of the USB option.

Some boards might need “flash mode” during the process. This could mean holding a specific button while powering up. Your board’s documentation should help if you run into issues.

Your ESP32 will restart after successful flashing and connect to WiFi, ready for Home Assistant to find it.

Adding Sensors and Switches to Your ESP32 Device

Now that you’ve created and flashed your ESP32 device, let’s make it do something useful by adding sensors and switches.

Adding a GPIO switch in YAML

Your ESP32 can control lights or fans using GPIO switches. You’ll need to specify which pin to use. Here’s how to add a simple switch:

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

This creates a switch named “Living Room Light” connected to pin GPIO5. The switch will make GPIO5 go HIGH (3.3V) when turned on in Home Assistant. It goes LOW (0V) when off.

You can make your switch work the opposite way (HIGH when off, LOW when on) by adding the inverted option:

switch:
  - platform: gpio
    pin: 
      number: GPIO5
      inverted: true
    name: "Living Room Light"

We used GPIO numbers to specify pins. ESPHome understands different pin naming conventions. NodeMCU boards let you use D1 instead of GPIO numbers.

Adding a binary sensor with pull-up mode

Binary sensors detect ON/OFF states like door switches or buttons. Here’s the configuration:

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

The pullup: true setting prevents your pin from floating between ON and OFF states randomly. This keeps the pin in a known state until something changes it.

The pin reads HIGH normally with this mode. It reads LOW when connected to ground, like during a button press.

Validating and saving configuration changes

Your device needs updating after adding components. Follow these steps:

1. Click the “SAVE” button in the ESPHome dashboard
2. Click “INSTALL” to update your device
3. Choose “Wirelessly” if your device connects to WiFi

The device needs updating after every change. Saving the file alone won’t affect your ESP32.

You can monitor your device’s operation by adding:

# Enable logging
logger:

This allows you to view device messages using:

esphome logs devicename.yaml

ESPHome transforms your ESP32 into a smart home device with just a few lines of YAML code.

Connecting ESP32 to Home Assistant

Setting up your ESP32 with ESPHome leads to connecting it with Home Assistant. The process takes just a few minutes and it’s pretty straightforward.

Automatic discovery via mDNS

Your ESP32 device can be found automatically by Home Assistant through mDNS. Think of mDNS as a way devices say hello to each other on your network. The ESP32 broadcasts its presence once powered up, and Home Assistant picks up these signals.

Your device should show up in Home Assistant after about 5 minutes. A notification saying “New device discovered” will pop up with your ESP32’s name. Click “Configure” and you’re almost there!

Manual integration using IP or hostname

Automatic discovery might not work if Home Assistant and ESP32 are on different network segments. Here’s how to add your device manually:

1. Go to Home Assistant → Settings → Devices & Services
2. Click “Add Integration” and search for “ESPHome”
3. Enter your device’s name with “.local” (like “living-room-lamp.local”) or its IP address

The IP address tends to be more reliable. A device named “bedroom-sensor” would have “bedroom-sensor.local” as its hostname.

Assigning the device to a room in Home Assistant

Home Assistant needs to know which room your device belongs to. This helps keep your smart home organized:

1. Pick a room from the dropdown list (like “Living Room” or “Kitchen”)
2. Click “Finish”

Your ESP32 now belongs to your smart home system! The sensors and switches you set up will appear in the room you chose, ready to use in automations.

This setup makes your DIY device work just like any store-bought smart device – except you made it yourself!

Conclusion

ESPHome transforms your ESP32 board into a smart home device with just a few lines of code. The tool works like magic – you write some simple instructions and your inexpensive microcontroller becomes as capable as high-end store-bought gadgets.

Let’s recap what you’ve learned. ESPHome serves as a translator between you and your ESP32. You write simple instructions that ESPHome converts into device-readable code. You’ve found that there was a straightforward setup process – just install the add-on in Home Assistant or run a Docker container. Your first device comes to life with minimal YAML code.

The system connects to Home Assistant without any extra work. Your custom-built smart switch or sensor appears among your other smart devices. This lets you create a temperature sensor for your garden or a button that controls all your lights without breaking the bank.

Smart home device creation doesn’t need computer science expertise or years of experience. ESPHome makes it accessible to everyone. A child wants to track when parents return home? A door sensor solves that. Someone struggles with plant care? A soil moisture detector handles the job.

The potential applications are boundless. Lights, buttons, temperature sensors, motion detectors – each becomes a manageable project once you grasp the fundamentals. Your creativity sets the only boundary.

Pick up an ESP32, write some YAML, and begin creating. You’ll soon have smart devices throughout your home that you crafted yourself. That pride in telling friends “I built this!” when they admire your smart home setup? It’s better than any store-bought device could offer.

FAQs