16. ESPHome

ESPHome è il ponte fra il DIY (chip ESP8266/ESP32 con sensori economici comprati su AliExpress) e Home Assistant. Scrivi un file YAML con “voglio un ESP32 che legga un DHT22 e un sensore di movimento”, ESPHome lo compila in firmware, lo flashi sul chip, e il device compare in HA come qualsiasi altra integrazione, senza scrivere una riga di C né toccare Arduino IDE.

Questo capitolo è una intro operativa: cos’è ESPHome, come installarlo, il primo device (temperatura + umidità), e i trucchi che riducono i tempi di compilazione da 10 minuti a 30 secondi.

Se dopo averlo letto vuoi andare a fondo, quale board scegliere, come si legge un pinout, cosa si può fisicamente collegare, i display, i device a batteria e i nuovi strumenti visuali (Device Builder, ESPHome Designer, ESPConfig Designer), il seguito è il Corso ESP32.

Cosa è ESPHome, esattamente

Un progetto open source che:

Prende un file YAML (semplice) come “sorgente” del firmware.
Lo compila usando internamente PlatformIO + esp-idf o arduino framework.
Genera un .bin da flashare sul chip.
Al primo boot, il chip si connette al Wi-Fi, ping il broker ESPHome (o direttamente HA), e HA lo scopre come integrazione ESPHome.
Da lì è come qualsiasi altro dispositivo HA: entità, dashboard, automazioni.

Supporta ESP32 (variante originale, C3, S2, S3, C6), ESP8266, RP2040 (con qualche limite). Tutte le famiglie ESP32 con Wi-Fi + BLE lavorano bene.

Installazione via add-on

Il modo standard è l’add-on ufficiale HA (per installazioni HAOS o Supervised).

Impostazioni → Add-on → Add-on store → ESPHome Builder → Installa (oppure la variante “beta” se vuoi le ultime feature).
Avvia l’add-on. Attiva Show in sidebar per un accesso rapido.
Apri ESPHome dalla sidebar. Vedi l’interfaccia web di ESPHome.

Se non usi HAOS/Supervised, esiste esphome come CLI Python installabile con pip install esphome. Ma con l’add-on è più comodo (nessun setup Python, interfaccia web).

Il primo device: sensore temperatura + umidità

Hardware minimo:

Una board ESP32-C3 o ESP32-S2 (~5 €).
Un sensore DHT22 (~3 €) o meglio un BME280 (~5 €, più preciso e legge anche pressione).
Cavo USB per programmare la board la prima volta.

Il resto: solder, jumper wire, o breadboard.

Config YAML minima

Dall’interfaccia ESPHome: New device → nome, Wi-Fi SSID e password → scelta board → Next → Skip (per ora).

Ottieni un YAML del tipo:

esphome:
  name: sensore-cucina
  friendly_name: Sensore Cucina
 
esp32:
  board: esp32-c3-devkitm-1
  framework:
    type: esp-idf
 
logger:
api:
  encryption:
    key: "..."
ota:
  - platform: esphome
    password: "..."
 
wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
  ap:
    ssid: "Fallback Hotspot"
    password: "12345678"
 
captive_portal:

Manca il sensore. Aggiungi in fondo:

i2c:
  sda: GPIO8
  scl: GPIO9
 
sensor:
  - platform: bme280_i2c
    address: 0x76
    temperature:
      name: "Temperatura Cucina"
    humidity:
      name: "Umidità Cucina"
    pressure:
      name: "Pressione Cucina"
    update_interval: 60s

Salvi. ESPHome valida la config. Se ok, Install → Plug into this computer (per il primo flash via USB) o Wireless (per gli aggiornamenti dopo il primo. OTA).

Al primo boot il chip si connette al Wi-Fi, HA lo riconosce e ti chiede se aggiungere l’integrazione ESPHome. Da lì compaiono sensor.temperatura_cucina, sensor.umidita_cucina, sensor.pressione_cucina.

Il flow di sviluppo tipico

Colleghi il device via USB al PC (o Raspberry HA se accessibile).
Modifichi il YAML dal browser (nella pagina del device, “Edit”).
Install → Wireless (OTA). ESPHome compila, invia via Wi-Fi, il chip si riavvia con la nuova config in 20-40 secondi.

Il vantaggio è che dopo il primo flash non tocchi più il cavo USB. Tutto avviene wireless: aggiungi un sensore nuovo, cambi un intervallo, aggiungi un’automazione locale, sempre OTA.

Automazioni locali (on-device)

ESPHome può eseguire logica sul chip, senza aspettare HA. Esempio: pulsante fisico che accende/spegne una luce collegata al chip, con risposta istantanea anche se HA è down.

binary_sensor:
  - platform: gpio
    pin:
      number: GPIO0
      mode: INPUT_PULLUP
      inverted: true
    name: "Pulsante Camera"
    on_press:
      - light.toggle: luce_camera
 
light:
  - platform: monochromatic
    output: output_pwm
    id: luce_camera
    name: "Luce Camera"

Il pulsante toggla la luce direttamente, senza roundtrip HA → chip. Utile per luci essenziali (bagno, cucina): funzionano anche se il Wi-Fi cade o HA è in riavvio.

Trucchi per non aspettare 10 minuti a ogni compilazione

Il tempo di compilazione ESPHome è il singolo fastidio più grosso quando lavori attivamente su un chip. Un ESP32 vergine può richiedere 5-10 minuti al primo build.

Cose che accelerano molto:

Non usi Home Assistant Green / Yellow con SD lenta come host del compile: la compilazione è I/O intensive. Meglio un PC dedicato con SSD, o un altro server, con esphome CLI puntato lì.
Cache dei build: già attiva di default; non svuotare mai la cache salvo problemi noti. Un rebuild “sporco” (con modifiche minori) dura 30-60s.
Framework esp-idf vs arduino: esp-idf è più moderno e mediamente più veloce. Nuovi progetti: framework: type: esp-idf.
Un file per device: non condividere config fra chip diversi con macro complessi; i macro invalidano la cache.
Preferisci OTA a USB: il flash via USB richiede spesso reset manuale del chip (boot mode); via OTA è automatico e più veloce end-to-end (anche se la compilazione è uguale).

Debug: la console log integrata

Dalla pagina del device in ESPHome, Logs apre uno stream in tempo reale. Vedi:

Il boot del chip
Le connessioni Wi-Fi / API HA
Le letture dei sensori
Gli errori (I2C non risponde, sensor non trovato, calibrazione fallita)

Se un sensore non pubblica valori in HA, la prima cosa è aprire i log: quasi sempre c’è un errore chiaro (indirizzo I2C sbagliato, pin GPIO in conflitto, sensor non alimentato).

Casi pratici tipici

Ecco cose che si costruiscono comunemente:

Sensori multi-parametro per stanza: BME280 (temp+umi+pressione) + PIR (movimento) + LDR (luce) su un ESP32-C3 ~10 €.
Interruttori smart con relè + pulsante fisico: tap del pulsante toggla il relè + push a HA.
Sensori porta / finestra magnetici (reed switch) alimentati a batteria: ESP32-C3 con deep sleep, dura mesi.
Presence detection con mmWave (LD2410, LD2450): sensori “vede persona ferma” utilissimi per luci a movimento (i PIR falliscono se stai fermo, mmWave no).
Sensori consumo energia con clamp CT: PZEM-004T + ESP32 = wattmetro casalingo.
Display e-ink con dashboard casa: piccolo pannello che mostra temperatura, meteo, prossimo appuntamento.
Sensori acqua (leak detector): un piccolo cavo che fa contatto quando c’è umido, ESP32 che dorme e si sveglia ogni tot.

Il rapporto costo/funzionalità è imbattibile: 5-10 € per un sensore che le controparti commerciali vendono a 30-50 €.

Quando NON usare ESPHome

Se il device commerciale ufficiale funziona bene e costa poco. Non c’è ragione di rifare in DIY una lampadina IKEA da 10 €.
Se non hai tempo per il debug hardware. Un progetto ESPHome semplice è veloce; uno complesso con sensori che si comportano male richiede pazienza.
Per progetti dove serve UI locale ricca. ESPHome è per sensori/attuatori, non per tablet touch con dashboard (usa un tablet + HA app per quello).

Aggiornare ESPHome / firmware ESP

L’add-on ESPHome si aggiorna dall’add-on store, come tutti gli add-on.
Dopo un aggiornamento major di ESPHome, alcuni device potrebbero necessitare di un rebuild. Non è automatico: la prossima volta che modifichi la config e fai “Install”, il chip riceve la nuova versione.
I chip che non aggiorni da mesi restano stabili: ESPHome mantiene compatibilità retroattiva. Non c’è pressione ad aggiornare “per il gusto di farlo”.

Ricapitolando

ESPHome = YAML → firmware ESP compilato → device HA nativo.
Setup: add-on ESPHome Builder, primo device configurato via web, primo flash via USB, poi tutto OTA.
La mesh Wi-Fi + BLE dell’ESP32 apre a mille sensori DIY a costo minimo.
Le automazioni on-device rendono luci/pulsanti resilienti a caduta di HA/Wi-Fi.
Compilazioni lunghe = cache è tuo amico, non svuotarla; usa esp-idf.
Log del device è la prima diagnostica quando qualcosa non funziona.

Appunti di Simon

Esplora