ESPHome turns a YAML file describing your hardware (board, sensors, relays, buttons) into firmware, which it compiles and flashes to the device. You don't write C++ unless you want to (lambdas and custom components are available).
A minimal ESP32 device
esphome:
name: living-room-sensor
esp32:
board: esp32dev
framework:
type: esp-idf
logger:
api:
encryption:
key: !secret api_encryption_key
ota:
- platform: esphome
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
Native API or MQTT?
| Native API | MQTT | |
|---|---|---|
| Used by | Home Assistant (ESPHome integration), ESPHome tool, ioBroker | any MQTT broker and client |
| Home Assistant features | full: entities, actions, Bluetooth proxy, device logs | MQTT entity discovery only |
| Needs | nothing else | a broker (e.g. Mosquitto) |
- Using Home Assistant? Use the native API. ESPHome's docs say MQTT isn't needed in that case, and that the API supports more features than MQTT discovery alone.
- Not using Home Assistant, or other systems read the data? Use MQTT. It's fine to keep the device on MQTT only, but then remove
api:or set itsreboot_timeout: 0s(see the reboot-timeout warning).
Always set an encryption key
The API encryption key is a 32-byte base64 string. Without it, the API traffic isn't encrypted. Home Assistant asks for the key when you add the device. Keep it in secrets.yaml, not in the device YAML.
Framework on ESP32
ESP-IDF is ESPHome's default and recommended framework on ESP32. It's the only option for ESP32-C2, C5, C6, C61, H2 and P4. Use type: arduino only if a component or library you need requires it (available on the classic ESP32, C3, S2 and S3).