ESPHome

What is ESPHome?

ESPHome compiles custom firmware for cheap ESP-based microcontrollers from a small YAML file. Sensors, relays, displays and buttons become native devices in your home automation system, with no cloud in between.

Best for

Building your own sensors and switches that work locally

Why choose ESPHome

ESPHome turns cheap microcontrollers into well-behaved smart devices without any cloud. You describe what the hardware is — a temperature sensor, a relay, a display, a button — in a short YAML file, and it compiles firmware that presents the device natively to your automation platform. That means a five-dollar board becomes a sensor that reports locally, responds instantly, and keeps working when the internet is down, with no vendor account and no app. It also gives you devices that do not exist commercially: a mailbox sensor, a water level probe, a custom display panel, made from parts you can buy anywhere. Because configuration is a text file, your devices are reproducible, reviewable and rebuildable rather than governed by a phone app somebody stopped updating.

Replaces

• Tuya Cloud
• SmartLife
• Shelly Cloud

Key features

• YAML device configuration compiled to firmware
• Hundreds of supported sensors and components
• Over-the-air firmware updates
• Native Home Assistant integration

What to watch out for

It requires physical work: buying the right board, wiring sensors correctly, flashing firmware over USB the first time, and understanding enough electronics not to damage anything. Voltage levels matter, and a sensor that expects 5 volts connected to a 3.3-volt pin will either not work or will not work for long. Compiling firmware happens on a host machine and takes real time, so a rebuild-and-flash cycle is slower than editing an automation. Over-the-air updates are convenient but a board that fails mid-update may need physical access to recover. If the Wi-Fi credentials or API key change, every device needs updating, which is manageable at a dozen devices and tedious at fifty.

How to deploy

• Install the dashboard add-on or CLI
• Flash a device over USB once
• Update over the air afterwards

Getting started

Start with one well-documented board and a sensor you can verify, rather than a custom circuit, so the first success is about the toolchain rather than your soldering. Set up secrets in the configuration for Wi-Fi credentials and API keys rather than pasting them into every device file, and keep those files in version control. Confirm the device appears in your automation platform and that its readings change plausibly before deploying more. Use a USB extension and a stable power supply, since unreliable power causes symptoms that look like firmware bugs. Keep a spare board and a USB cable accessible, because the one device that will need a physical reflash is the one in the least convenient location.

Typical setup

A configuration directory in version control with Wi-Fi credentials and API keys held in a secrets file rather than repeated in every device definition. One well-documented board and a simple sensor are brought up first, so the initial success is about the toolchain rather than custom wiring. Devices are powered from stable supplies, since unreliable power produces symptoms that look like firmware faults. Each new device is confirmed to appear in the automation platform and report plausible values before the next is built. A spare board and cable are kept accessible, because the device that needs a physical reflash is always the one in the least convenient place.

Who should look elsewhere

Do not choose it if you are not prepared to wire hardware and troubleshoot it, because no amount of good software removes that requirement. Avoid it for anything where safety depends on reliability — mains switching, heating control, anything that must not fail — unless you are confident in both the electronics and the failure modes. And if a commercial device already does exactly what you need for a similar price, the time you spend building your own is time you are not spending on the rest of the setup.

Project health

• GitHub stars: 11,759
• Last code push: 2026-10-02
• Open issues: 742
• Status: actively developed

Figures pulled from the GitHub API and refreshed periodically.