ESPHome
YAML-configured firmware framework for ESP32, ESP8266 and other microcontrollers, integrated with Home Assistant.
software
Knowledge about ESPHome
- Battery sensors with ESPHome deep_sleep, and how to still get OTA updates onto themcode · unverified · deep_sleep wakes the device for run_duration, then sleeps for sleep_duration; each wake is a full reboot. Because a sleeping device misses OTA uploads, keep a switch (Home Assistant helper or MQTT message) that triggers deep_sleep.prevent. On ESP8266, GPIO16 must be wired to RST.
- Debugging ESPHome devices: log levels, esphome logs, the debug component and web_serverprocedure · unverified · Read logs over the network or serial with esphome logs, raise the log level per component only where needed (levels above the global one aren't compiled in), add the debug component for reset reason, free heap and loop time, and use web_server only on trusted networks.
- ESP32 as Bluetooth proxy for Home Assistant: setup, connection slots and placementguide · unverified · An ESPHome bluetooth_proxy extends Home Assistant's BLE range. Use ESP-IDF (less memory), prefer Ethernet boards, keep the proxy free of heavy components, and don't raise active connection slots beyond what ESPHome recommends.
- ESPHome basics: YAML becomes firmware, native API or MQTT, and an encryption keyguide · unverified · ESPHome compiles a YAML configuration into firmware. Devices talk to Home Assistant through the encrypted native API (recommended) or through MQTT. On ESP32, ESP-IDF is the default framework and the only one for C6, H2 and other newer chips.
- ESPHome device reboots every 15 minutes: the API and Wi-Fi reboot_timeoutwarning · unverified · By default an ESPHome device reboots when no client has connected to its native API for 15 minutes, and when it has had no Wi-Fi connection for 15 minutes. MQTT-only or standalone devices must set api reboot_timeout to 0s or drop api:.
- ESPHome devices in Home Assistant: native API encryption, action permission and Bluetooth proxiesguide · unverified · ESPHome devices are auto-discovered and connect over the native API (port 6053) with a noise encryption key. They can't call Home Assistant actions unless you allow it per device, and they can act as Bluetooth proxies to extend Home Assistant's Bluetooth range.
- ESPHome sensor filters: smooth noise and cut traffic with averages, delta, throttle and heartbeatcode · unverified · Read sensors often but publish only meaningful changes: average with sliding_window_moving_average, suppress small changes with delta, cap the rate with throttle, still send a periodic value with heartbeat, and drop known bogus readings with filter_out. Filters run in the order written.
- ESPHome: flash once over USB, then update over the air with an encrypted OTAprocedure · unverified · The first ESPHome install needs a serial/USB connection (GPIO0 to GND for bootloader mode); after that, updates go over the air. Prefer OTA encryption, which reuses the API key, over an OTA password.
- I2C sensors in ESPHome: default pins, the startup scan, pull-ups and address conflictsprocedure · unverified · ESPHome's i2c: bus defaults to GPIO21/22 on ESP32 and GPIO4/5 on ESP8266, scans the bus at startup by default and logs found addresses. Use external pull-ups for longer wires, a second bus or a TCA9548A multiplexer for duplicate addresses.
- Many similar ESPHome devices: !secret, substitutions and packages instead of copy-pastecode · unverified · Keep credentials in secrets.yaml (never in git), parametrize names with substitutions, and share common blocks with packages (local files or a git repo). The device file wins over package values.
- Recover an ESPHome device without USB: fallback hotspot, captive portal and safe modeprocedure · unverified · Configure wifi ap: and captive_portal so a device that can't reach Wi-Fi opens its own hotspot for new credentials or firmware. After repeated failed boots, ESPHome's safe mode keeps only logging, network and OTA running.
- Replacing Tuya firmware: check the chip first. tuya-convert only fits old ESP-based deviceswarning · unverified · tuya-convert only flashes ESP82xx-based devices and newer firmware is patched. Many current Tuya devices use Beken BK7231 or Realtek chips: use tuya-cloudcutter (unpatched firmware only), OpenBeken, or ESPHome via LibreTiny, often via serial flashing. Never open or flash a device while it is connected to mains power.
Related
- alternative to (from): OpenBeken – Replacement firmware options for Tuya hardware; OpenBeken covers more non-ESP chips.