ESPHome
Overview
This integration allows ESPHome
ESPHome is a firmware generator and configuration system that enables the transformation of microcontrollers into fully customizable smart home devices. Using a simple YAML configuration file, ESPHome allows users to define hardware components like sensors, actuators, and peripherals. These configurations are then compiled into custom firmware that can be flashed onto the target device.
Key Features
- YAML Configuration: Specify hardware components, sensors, actuators, and integrations using a clean and straightforward YAML syntax.
- Custom Firmware Generation: ESPHome compiles the provided configuration into a highly optimized, device-specific firmware image that is ready to be flashed onto microcontrollers.
-
Seamless Integration: After flashing, ESPHome devices can integrate seamlessly with Home Assistant using the ESPHome native API. This documentation page focuses on the native API
, which allows devices to communicate directly with Home Assistant for real-time automation and monitoring. For other integrations, such as MQTT or HTTP, please refer to the relevant sections of the ESPHome documentation .
ESPHome supports a variety of microcontrollers beyond just the ESP family. These include:
- ESP32: A powerful microcontroller with Wi-Fi and Bluetooth capabilities.
- ESP8266: A low-cost microcontroller with Wi-Fi support.
- BK72xx: A series of microcontrollers from Beken, commonly used in smart home applications.
- RP2040: A microcontroller developed by Raspberry Pi, known for its flexibility and cost-effectiveness.
- RTL87xx: A series of microcontrollers from Realtek, supporting various wireless communication protocols.
For a list of officially supported microcontrollers and devices, refer to the ESPHome device database
For inspiration and examples of complete, ready-to-use configurations, check out the ESPHome ready-made projects
If you’re looking for pre-built solutions, the Voice PE is an excellent example. It’s a pre-built voice assistant device powered by ESPHome, offering an easy way to integrate voice control into your Home Assistant system. Many pre-built solutions, like the Voice PE, are open-source and can be customized, giving you flexibility to adapt them to your needs.
For detailed information on configuring unsupported or custom devices, consult the official ESPHome documentation
Configuration
To add the ESPHome device to your Home Assistant instance, use this My button:
ESPHome can be auto-discovered by Home Assistant. If an instance was found, it will be shown as Discovered. You can then set it up right away.
Manual configuration steps
If it wasn’t discovered automatically, don’t worry! You can set up a manual integration entry:
-
Browse to your Home Assistant instance.
-
In the bottom right corner, select the
Add Integration button. -
From the list, select ESPHome.
-
Follow the instructions on screen to complete the setup.
Required manual input
To configure an ESPHome device, enter the following information:
IP address or hostname of the ESPHome device.
This will be pre-filled if the device was auto-discovered.
Port used by the ESPHome native API (default: 6053).
This will be pre-filled if the device was auto-discovered.
The pre-shared key used for encryption.
This is a 32‑byte base64‑encoded string. Leave blank if native encryption is not enabled.
For more information, see the ESPHome Native API Component documentation
Removing the integration
This integration follows the standard integration removal process; no extra steps are required.
To remove an integration instance from Home Assistant
- Go to Settings > Devices & services and select the integration card.
- From the list of devices, select the integration instance you want to remove.
- Next to the entry, select the three-dot
menu. Then, select Delete.
Options
Options for ESPHome can be set via the user interface, by taking the following steps:
- Browse to your Home Assistant instance.
- Go to Settings > Devices & Services.
- If multiple instances of ESPHome are configured, choose the instance you want to configure.
- Select the integration, then select Configure.
These options are disabled by default and not required—only set them if specifically needed.
No/Yes
When enabled, ESPHome devices can perform Home Assistant actions, such as calling services or sending events. Only enable this if you trust the device.
Supported devices
The ESPHome integration works with devices that run ESPHome firmware and expose their functionality through the native ESPHome API
Updating data
Rather than polling for sensor values or device states, Home Assistant maintains a persistent connection to each ESPHome device using the native API. This allows state changes—such as a temperature sensor update, a button press, or a binary sensor trigger—to be sent immediately as they happen, reducing latency and improving responsiveness in automations.
Additional Technical Details
-
Efficient Communication Protocol: ESPHome uses a lightweight, bi-directional protocol over TCP, optimized for microcontrollers. This protocol is implemented in aioesphomeapi
, the async Python library used by Home Assistant to handle real-time communication with ESPHome devices. It enables low-latency updates and near instant command execution. - Automatic Reconnection: Home Assistant maintains a persistent connection to each ESPHome device and will automatically attempt to reconnect if the connection is lost. This includes support for “sleepy” or battery-powered devices that periodically wake from deep sleep. When such a device comes online, Home Assistant quickly re-establishes the connection—especially when mDNS (Multicast DNS) is available—allowing the device to be discovered and connected without requiring static IPs or manual configuration.
This real-time behavior enables fast, reactive automations and a smooth user experience compared to traditional polling-based integrations.
Supported Functionality
Entities
The available entities depend on the components defined in the ESPHome YAML configuration for each device. These entities are exposed through the Native API Component
Firing Events on the Home Assistant Event Bus
When using the native API with Home Assistant, you can trigger events on the Home Assistant event bus directly from ESPHome. For more details, see the homeassistant.event Action
Actions
Each device can define Home Assistant Actions based on its ESPHome YAML configuration. For more information, refer to the Actions
Retrieving Data from Home Assistant
ESPHome can retrieve the state of Home Assistant entities using the Native API
Home Assistant Actions
ESPHome devices can call any Home Assistant Action
Tag Scanning Support
The Native API Component
Entity naming and IDs
ESPHome uses different naming and entity ID rules based on the configuration of the ESPHome device. It is recommended to set a friendly_name
in the ESPHome configuration.yaml
The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] to take advantage of the newer naming structure, which is consistent with Home Assistant naming standards and makes it much easier to tell similar devices apart. The legacy naming rules apply when the friendly_name
is not set in the configuration.yaml
The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more].
Friendly naming
- Entity name is a combination of the friendly name and component name
- Entity ID is derived from the entity name with the device name prepended
Example:
esphome:
name: "livingroomdesk"
friendly_name: "Living room desk"
sensor:
name: "Temperature"
The entity will be named Living room desk Temperature
and will default to having an entity ID of sensor.livingroomdesk_temperature
.
Legacy naming
- Entity name is the component name
- Device name is not prepended to the entity name
- Entity ID is derived solely from the entity name
Example:
esphome:
name: "livingroomdesk"
sensor:
name: "Temperature"
The entity will be named Temperature
and will default to having an entity_id of sensor.temperature
.
Troubleshooting
Viewing Live Logs
To troubleshoot your ESPHome devices, you can easily view live logs, whether you’re using the ESPHome Device Builder Add-on or the ESPHome CLI. The logs contain detailed information such as Wi-Fi connection status, errors, and debug messages, which can help you identify and resolve issues with your device.
Using the ESPHome Device Builder Add-on
- In the ESPHome Device Builder Add-on add-on, find the device you’re working with.
- Click the LOGS button to open the log view.
Using the ESPHome CLI
If you’re using the ESPHome CLI, follow the instructions for the logs Command
Obtaining Logs from the Device
If you want the device to send logs without requiring you to be actively monitoring, follow these steps:
-
To have the device send logs to Home Assistant, in the options flow, enable
Subscribe to logs from the device
.- They are logged under the
homeassistant.components.esphome
logger at the equivalent level.
- They are logged under the
-
To adjust the logging level, there are two options:
-
enable debug logging,
-
or use the Developer Tools to call the
logger.set_level
action to specify the desired level:action: logger.set_level data: homeassistant.components.esphome: debug
-
Known Limitations
Each ESPHome device must have a unique name. This name is important for mDNS announcements, ensuring that the device can be properly discovered, quickly reconnected when it comes online or wakes from deep sleep (for devices that support deep sleep), and correctly linked to the ESPHome Device Builder Add-on. It’s also crucial for DHCP discovery if mDNS is not available.
Using duplicate names can lead to connection issues, failed discovery, and unexpected behavior with both the integration and the add-on.