ESPHome is an open-source firmware framework that transforms ESP32, ESP8266, RP2040, and other microcontrollers into fully-featured smart home devices. Write a YAML configuration file, and ESPHome compiles and flashes custom firmware — no C++ knowledge needed. Devices integrate seamlessly with Home Assistant and work fully locally, with no cloud dependency.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/esphome/esphome.io/llms.txt
Use this file to discover all available pages before exploring further.
Get Started with Home Assistant
Install the ESPHome Device Builder add-on and flash your first device in minutes.
Get Started with CLI
Use the ESPHome command line or Docker to compile and manage devices.
Browse Components
Explore hundreds of sensors, lights, displays, and actuator components.
CLI Reference
Full reference for all ESPHome CLI commands, flags, and options.
What is ESPHome?
ESPHome reads a YAML configuration file that describes your device — its platform, network settings, sensors, lights, switches, and more — and generates a complete C++ firmware project, which it compiles and uploads to your microcontroller. Changes are pushed over-the-air (OTA), so you never need a USB cable again after the first flash.Install ESPHome
Install the ESPHome Device Builder as a Home Assistant add-on, or run
pip install esphome / pull the Docker image for command-line use.Write a YAML configuration
Define your device platform, Wi-Fi credentials, and the components you want — sensors, lights, switches, displays, and more.
Compile and flash
Run
esphome run your-device.yaml. ESPHome validates your config, compiles the firmware, and uploads it to your device.Key Features
No Coding Required
Simple YAML configuration replaces complex C++ code. Hundreds of pre-built components cover the vast majority of hardware.
Wireless Updates
After the first flash, all firmware updates are delivered over-the-air. No serial cable or physical access needed.
Home Assistant Native
First-class integration with Home Assistant via the native API. Devices are auto-discovered and all entities appear automatically.
Local Control
All communication happens on your local network. No cloud account or internet connection required for device operation.
Powerful Automations
Respond to sensor readings, button presses, and time schedules with triggers, actions, and C++ Lambda expressions.
Broad Platform Support
ESP32 (all variants), ESP8266, RP2040, nRF52, BK72xx, and RTL87xx are all supported.
Supported Platforms
| Platform | Status | Notes |
|---|---|---|
| ESP32 (original) | ✅ Best supported | Built-in Ethernet MAC, large community |
| ESP32-S3 | ✅ Recommended | USB peripheral, ML acceleration |
| ESP32-C3 | ✅ Recommended | Low cost, replaces ESP8266 |
| ESP32-C6 | ✅ Recommended | Thread/OpenThread support |
| ESP8266 | ⚠️ Maintained | Limited RAM; ESP32-C3 preferred for new projects |
| RP2040 | ✅ Supported | Raspberry Pi microcontroller |
| BK72xx / RTL87xx | ✅ Supported | Via LibreTiny integration |
Explore the Documentation
YAML Configuration
Learn ESPHome’s YAML syntax, secrets, substitutions, and packages.
Automations
Triggers, actions, scripts, globals, and Lambda templates.
OTA Updates
Configure safe-mode, passwords, and update strategies.
Web API
REST and Server-Sent Events API for custom integrations.
Cookbook
Complete worked examples: displays, power meters, garage doors.
FAQ
Which ESP to choose, common errors, and migration tips.