The complete ESPHome guide for Home Assistant

If you want smart home sensors that never touch the cloud, ESPHome is the most direct way to build them. It turns cheap, repairable hardware into Home Assistant devices that talk to your server directly on your own network, with no cloud account anywhere in the loop. Whether you buy a ready-made board or solder your own sensor, the result is the same: fast, private, fully local automation that keeps working when the internet does not.

What ESPHome is

ESPHome takes inexpensive ESP32 and ESP8266 microcontrollers and turns them into Home Assistant devices that you configure with a few lines of YAML. You describe the sensors and switches wired to the board, ESPHome compiles that description into firmware, and the device connects to Home Assistant over the native API - an encrypted, push-based connection on your local network. There is no polling, no cloud relay, and no account. It is maintained by the team behind Home Assistant (Nabu Casa and the Open Home Foundation), so it stays in lockstep with HA itself.

What you get

No cloud, ever: the device and Home Assistant talk directly, nothing leaves your network, and an internet outage changes nothing. Updates are instant and pushed the moment a state changes, so motion and presence feel immediate instead of laggy. You own the firmware; after the first flash, updates are over-the-air and you decide what runs and when. A spare ESP32 can act as a Bluetooth proxy, relaying nearby Bluetooth devices back to Home Assistant and extending BLE range across the house for next to nothing. And it’s cheap and repairable, since boards and sensors cost a few dollars and if one dies you reflash a new one in minutes.

The easiest way in: no-solder, ready-made ESPHome devices

You do not have to touch a breadboard to get the benefits. A growing market of pre-flashed ESPHome devices adopts straight into Home Assistant:

• The Everything Presence One pairs mmWave radar with a PIR sensor for reliable room presence. The cheaper Everything Presence Lite is mmWave-only: it carries an LD2450 radar and an ambient light sensor, but no PIR. Both sit in the wider comparison of mmWave presence sensors for Home Assistant, alongside the wired and battery-powered options.
• The Apollo Automation line - the Apollo MSR-2 multisensor, the Apollo MTR-1 radar, and the Apollo AIR-1 air quality sensor - ships flashed and ready. The AIR-1’s true-CO₂ SCD40 is an optional module rather than standard equipment, so check the roundup of air quality sensors for Home Assistant before ordering if CO₂ is what you are after.
• Even the Home Assistant Voice Preview Edition, which I run, is ESPHome under the hood.

These are the best starting point: you learn the workflow and get the local-first payoff without any wiring.

Rolling your own

When you want something that does not exist off the shelf, the recipe is simple: an ESP32 dev board plus a sensor or two. The common building blocks: for presence, the HiLink LD2410 24GHz mmWave module is what most DIY builds use to detect a still person sitting on a couch, where a PIR sensor would give up. I haven’t built with the bare module myself; that pick comes from the spec sheet and what other ESPHome users report. For environment, a BME280 covers temperature, humidity, and pressure, an SCD40 or SCD41 gives true CO2, and an SEN5x handles particulate matter. Reed switches, photoresistors, and tactile buttons cover contact, light, and buttons, and all of them map to ESPHome components in a few lines.

Getting started in three steps

1. Install the app. In Home Assistant, open Settings, then Apps, then the App Store, and install ESPHome Device Builder. It gives you a dashboard for all your ESPHome devices. (Home Assistant 2026.2 renamed add-ons to “apps” - same software, new menu; older guides still say “Add-on Store”.)
2. Flash the board once over USB. The first flash needs a cable. The easiest path is the browser-based flasher at web.esphome.io (Chrome or Edge), or use the Install option in the dashboard. Every update after that is over-the-air.
3. Write a little YAML. A minimal environmental sensor looks like this:

esphome:
  name: porch-sensor
esp32:
  board: esp32dev
api:
  encryption:
    key: !secret api_key
wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
sensor:
  - platform: bme280_i2c
    temperature:
      name: Porch Temperature
    humidity:
      name: Porch Humidity

ESPHome compiles it, flashes it, and the device appears in Home Assistant ready to add.

Tips and gotchas

• Power the board from a solid 5V supply. Flaky USB power is the most common cause of random reboots.
• Name your devices and entities clearly up front - it is much harder to untangle later.
• Keep Wi-Fi credentials and API keys in a secrets.yaml file so you can share configs safely.
• mmWave presence sensors need a little tuning (distance gates and sensitivity) to stop them tripping on a moving curtain or a fish tank.

Learn more

The official documentation at esphome.io covers every component, sensor, and platform, with a config example for each. Start with its Getting Started guide, then use the components index to find the exact YAML for the hardware you have.

For a worked example on this site, building a noise monitor with Home Assistant takes an ESP32 and an I2S microphone from wiring to a graphed sound level.