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 actually 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 actually get

• No cloud, ever. The device and Home Assistant talk directly. Nothing leaves your network, and an internet outage changes nothing.
• Instant, push updates. State changes are pushed the moment they happen, so motion and presence feel immediate instead of laggy.
• You own the firmware. After the first flash, updates are over-the-air. You decide what runs and when.
• Bluetooth Proxy. A spare ESP32 can relay nearby Bluetooth devices back to Home Assistant, extending BLE range across the house for next to nothing.
• Cheap and repairable. 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 and Everything Presence Lite pair mmWave radar with a PIR sensor for reliable room presence.
• 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.
• Even the Home Assistant Voice Preview Edition runs 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. Common building blocks:

• Presence: the HiLink LD2410 24GHz mmWave module is the popular choice for detecting a still person sitting on a couch, where a PIR sensor would give up.
• Environment: a BME280 for temperature, humidity, and pressure; an SCD40 or SCD41 for true CO2; an SEN5x for particulate matter.
• Contact, light, and buttons: reed switches, photoresistors, and tactile buttons all map to ESPHome components in a few lines.

Getting started in three steps

1. Install the add-on. In Home Assistant, open Settings, then Add-ons, then the Add-on Store, and install ESPHome Device Builder. It gives you a dashboard for all your ESPHome devices.
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.

Bottom line

ESPHome keeps everything on your own network: no cloud, instant response, and full control of the firmware on cheap, repairable hardware. Start with a ready-made board like the Everything Presence One or an Apollo sensor to learn the workflow, then graduate to your own builds when you want something the market does not sell.