Smart Home Made Simple
Turn your ESP32, ESP8266, or RP2040 boards into powerful smart home devices with simple YAML configuration
Quick Links¶
What is ESPHome?¶
ESPHome is an open-source firmware framework that simplifies the process of creating custom firmware for popular WiFi-enabled microcontrollers. With ESPHome, you can:
Create custom smart home devices using simple YAML configuration files
Integrate seamlessly with Home Assistant for a unified smart home experience
Control and monitor your devices through multiple interfaces (web, API, MQTT)
Automate your home with powerful on-device automations
Update your devices wirelessly “Over The Air” (OTA) updates without physical access
ESPHome takes care of the complex parts of firmware development, allowing you to focus on what matters - building your smart home exactly how you want it.
Simple YAML configuration files instead of complex C++ code
Update your devices over-the-air without physical access
Support for hundreds of sensors, displays, and other components
Devices work locally without cloud dependencies
Who Uses ESPHome?¶
Create custom sensors, switches, and displays tailored to specific needs
Extend their home automation systems with affordable custom devices
Deploy reliable, locally-controlled smart devices for clients
Create Made for ESPHome certified products with standardized firmware
Which microcontrollers does ESPHome support?¶
Wide support for ESP32 and ESP8266 microcontrollers, the heart of many IoT projects.
Support for Raspberry Pi's RP2040 microcontroller.
Realtek RTL87xx and Beken BK72xx chips are supported.
Many ESPHome components can be run on a desktop computer using the host platform!
Getting Started¶
Getting started with ESPHome is easy. Choose the method that works best for you:
From Home Assistant
The easiest way to get started with ESPHome is through the Home Assistant add-on.
- Open Home Assistant
- Go to Settings → Add-ons → Add-on Store
- Find and install the ESPHome add-on
- Open the ESPHome Device Builder and create your first device
Command Line
For advanced users who prefer working with the command line.
- Install Python 3.11 or higher
- Install ESPHome:
pip install esphome - Create a configuration file
- Compile and upload:
esphome run my_config.yaml
Ready-Made Projects
Start with a pre-configured project for common use cases.
- Browse the project library
- Select a project that matches your hardware
- Follow the installation instructions
- Customize as needed
Basic Configuration Example¶
Here’s a simple example of an ESPHome configuration file:
# Basic configuration for an ESP32 device
esphome:
name: living-room-sensor
friendly_name: Living Room Sensor
# Hardware configuration
esp32:
board: esp32dev
framework:
type: esp-idf
# Enable Home Assistant API
api:
# Enable over-the-air updates
ota:
platform: esphome
# Connect to WiFi
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
# Enable fallback hotspot if WiFi connection fails
ap:
# Enable web server
web_server:
# Add a temperature sensor
sensor:
- platform: dht
pin: GPIO15
temperature:
name: "Temperature"
humidity:
name: "Humidity"
update_interval: 60s
Using with Home Assistant¶
ESPHome and Home Assistant are designed to work together seamlessly, providing a powerful smart home ecosystem.
Automatic Discovery¶
Home Assistant automatically discovers ESPHome devices on your network. When you add a new ESPHome device:
Make sure your device is connected to the same network as Home Assistant
Home Assistant will show a notification when it discovers the new device
Click “Configure” to add it to your system
The device and all its entities will appear in your Home Assistant dashboard
Dashboard Integration¶
ESPHome entities appear in Home Assistant just like any other device:
Sensors show up in the appropriate cards and graphs
Switches and lights can be controlled directly
Binary sensors can trigger automations
Climate devices integrate with the thermostat controls
Automations¶
You can create powerful automations using ESPHome devices in Home Assistant:
Use sensor readings to trigger actions
Control ESPHome devices based on conditions
Include ESPHome devices in scenes and scripts
Create complex automations using multiple sensors and conditions
Advanced Features¶
ESPHome Device Builder Add-on: Manage all your ESPHome devices directly from Home Assistant
Backup Integration: Include ESPHome configurations in your Home Assistant backups
Firmware Updates: Update ESPHome devices directly from the Home Assistant interface
Join the Community¶
Ready to get started?¶
Join thousands of smart home enthusiasts building custom devices with ESPHome.
