Guides

ESPHome: build custom sensors with an ESP32

With ESPHome you create sensors and switches for Home Assistant yourself, without programming. You describe what’s connected to your ESP32 in a text file (YAML); ESPHome creates the software from that, puts it on the board, and Home Assistant sees the device immediately. This way you build a temperature sensor, motion detector, or remote control for just a few euros.

What do you need?

  • An ESP32 board (a DevKit works fine) and a USB cable with data (some cables only charge).
  • A sensor to start with, for example a BME280 for temperature, humidity, and air pressure (I2C).
  • Four wires: power (3.3 V), ground, SDA, and SCL.
  • Home Assistant, and the ESPHome add-on or the standalone tool.

Installing ESPHome

  • Home Assistant OS: install the add-on ESPHome Device Builder from the add-on store and open it via the sidebar.
  • Without add-on: install ESPHome with pip install esphome or use the Docker image from ESPHome.

Your first device

  1. Click New device and give it a name, for example woonkamer. Choose your wifi and board type.
  2. The builder creates a YAML file. Add the sensor (see the example below).
  3. Click Install. The first time you go via USB. If Plug into this computer doesn’t work (that requires a secure connection), use the page web.esphome.io with the downloaded file, or install from a computer with the standalone tool.
  4. After that, updates happen wirelessly (OTA) via your wifi.
  5. Home Assistant reports the new device under Devices and services. Click Configure and enter the encryption key from your YAML file.

Example: temperature and humidity

This is an example for an ESP32 and a BME280 on the default I2C pins (GPIO21 and GPIO22). Fill in the names and keys yourself; the builder already creates the key.

esphome:
  name: woonkamer

esp32:
  board: esp32dev

logger:

api:
  encryption:
    key: "YOUR_OWN_KEY"

ota:
  - platform: esphome
    password: "YOUR_OWN_PASSWORD"

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
  ap:
    ssid: "Woonkamer Hotspot"
    password: "choose-a-password"

captive_portal:

i2c:
  sda: GPIO21
  scl: GPIO22

sensor:
  - platform: bme280_i2c
    address: 0x76
    temperature:
      name: "Temperature"
    humidity:
      name: "Humidity"
    pressure:
      name: "Air Pressure"
    update_interval: 60s

The name of the component and the formatting occasionally change with new versions. If you see an error message, check the documentation for your ESPHome version. If your BME280 has a different address (often 0x77), adjust that.

Tips

  • Choose your pins wisely. Not every pin of an ESP32 is suitable everywhere: some have a special function during boot, others are input only. See our pinout of ESP32, Pico, and Arduino Uno.
  • On battery? Use the deep_sleep component so the board sleeps between measurements. You can calculate how long a battery will last with our Battery life tool.
  • Keep your secrets separate. Put passwords in secrets.yaml and don’t share or upload that file anywhere.
  • Turn on encryption. The device can then only be used with your Home Assistant.
  • Keep your sensors away from each other: a hot chip next to the sensor gives too high a temperature.

Sources and attribution

This article was written in our own words. Further reading: