Arrivato qui sai costruire un device, collegargli quasi qualsiasi cosa e integrarlo in Home Assistant. Questo capitolo non aggiunge capacità: aggiunge metodo. È il capitolo che separa chi dopo un anno ha dodici chip che funzionano e sa cosa fanno, da chi ha dodici chip di cui tre non si sa più cosa siano e due sono spenti da mesi senza che nessuno se ne sia accorto.
In questo capitolo vediamo come si diagnostica un problema in modo sistematico, l’elenco dei guasti che capitano a tutti con il rimedio, e le abitudini organizzative che rendono un parco di device gestibile invece che un debito.
I log sono la prima cosa, sempre
Dalla pagina di un device nel Device Builder, Logs apre uno streaming in tempo reale. Il 90% dei problemi si diagnostica lì, e l’errore più comune di chi inizia è provare a indovinare invece di guardare.
Cosa ci leggi, nell’ordine in cui compare all’avvio: la versione di ESPHome e il motivo dell’ultimo riavvio, l’inizializzazione di ogni componente (con gli errori, se ci sono), la scansione I²C se l’hai attivata, l’aggancio al Wi-Fi con l’indirizzo IP ottenuto e la potenza del segnale, la connessione all’API, e poi le letture dei sensori man mano che arrivano.
Ogni riga ha un livello: [I] informativo, [W] avviso, [E] errore. Quando qualcosa non va, cerca la prima [E] in ordine di tempo, non l’ultima: gli errori a valle sono spesso conseguenze del primo.
Se il device è irraggiungibile via Wi-Fi e non puoi vedere i log via rete, collegalo via USB: i log escono anche dalla seriale, ed è l’unico modo di diagnosticare un chip che non si connette.
Il metodo: dividere il problema in due
Il principio che funziona meglio è banale ma va applicato con disciplina: isola l’hardware dal software.
Se un sensore non legge, la domanda non è “cosa c’è di sbagliato” ma “il problema è nei fili o nella configurazione?“. Il modo di rispondere è caricare una configurazione minima con solo quel sensore e niente altro. Se funziona, il problema era nell’interazione con il resto (conflitto di pin, alimentazione insufficiente). Se non funziona nemmeno da solo, è hardware.
Il secondo strumento è il chip di riserva, il motivo per cui in 2 Famiglie e scelta della board consigliavo di comprarne due. Stessa configurazione, chip diverso: se sul secondo funziona, il primo è danneggiato o ha un difetto. Sono dieci minuti che ti risparmiano una serata.
Il terzo è la version history del Device Builder (7 Device Builder in profondita): quando un device funzionava e adesso no, la domanda “cosa ho cambiato” ha una risposta esatta in dieci secondi.
I guasti che capitano a tutti
Il computer non vede la board
Nell’ordine di frequenza: il cavo è solo-carica (è la causa numero uno in assoluto, provane un altro prima di ogni altra cosa); il browser non supporta la Web Serial API (serve Chrome o Edge, non Firefox né Safari); manca il driver CH340 o CP2102 sulle board vecchie; la porta USB della board è danneggiata (succede, le prese micro-USB si staccano).
Il flash parte e fallisce
La board non è entrata in modalità programmazione. Rimedio manuale: tieni premuto BOOT, premi e rilascia RESET, rilascia BOOT, e rilancia. Su alcune board serve anche staccare tutto quello che è collegato ai pin, perché un sensore attaccato a un pin di strapping impedisce l’ingresso in boot mode.
Il chip si riavvia in continuazione
Se nei log leggi Brownout detector was triggered, è alimentazione: alimentatore troppo debole, cavo troppo lungo e sottile, o un carico che assorbe più di quanto la board può erogare. Rimedi in 3 Pin bus e alimentazione, a partire dal condensatore da 470-1000 µF.
Se invece leggi errori di memoria o Guru Meditation Error, è un problema software: un componente che va in crash, o memoria esaurita (tipico sugli ESP8266). Togli componenti finché non smette, e hai trovato il colpevole.
Il sensore I²C non risponde
Found 0 i2c devices nei log significa che il bus è vuoto. Nell’ordine: controlla che SDA e SCL non siano invertiti; verifica l’alimentazione del sensore col multimetro (3,3 V presenti sui pin del sensore, non della board); prova l’indirizzo alternativo (0x77 invece di 0x76); accorcia i fili, perché sopra il mezzo metro l’I²C diventa inaffidabile. Se il scan trova un indirizzo diverso da quello che ti aspetti, hai trovato il problema.
Il sensore UART non manda niente
TX e RX invertiti, nel 90% dei casi. Non c’è nessun messaggio d’errore che te lo dica: semplicemente non arriva niente. Scambiali e riprova. Se invece nei log vedi byte casuali, è il baud rate sbagliato.
Il Wi-Fi si aggancia e cade
Guarda l’entità della potenza del segnale: sotto i -75 dBm i problemi iniziano, sotto i -85 dBm il collegamento è inutilizzabile. Rimedi: avvicinare un access point, usare una board con antenna esterna, o passare a Zigbee (13 Bluetooth proxy Assist Zigbee e Thread). Se il segnale è buono ma il device cade lo stesso, sospetta la banda a 2,4 GHz congestionata (Wi-fi 2.4 Ghz) o un access point che fa band steering e prova a spingere un client solo-2,4 GHz sui 5 GHz.
Aggiungi sempre questo sensore diagnostico ai device che stanno lontani:
sensor:
- platform: wifi_signal
name: "Segnale Wi-Fi"
update_interval: 60s
entity_category: diagnosticIl device è online in Home Assistant ma offline nel Device Builder
Non è un guasto: è mDNS che non passa. Docker senza --net=host, VLAN separate per l’IoT, access point che filtrano il multicast. Il chip funziona, semplicemente il Device Builder non lo scopre.
Dopo un aggiornamento di ESPHome un device non compila più
Leggi il messaggio, che di solito nomina il componente; controlla le breaking changes del changelog; svuota la cache solo di quel device. Intanto il chip continua a funzionare col firmware vecchio: non c’è nessuna urgenza.
Naming: le regole prima, non dopo
Vale in ESPHome esattamente quello che vale in Home Assistant (17 Pratiche di buon uso): rinominare cose già usate in venti posti è il debito più costoso che puoi contrarre.
Le convenzioni che uso:
Nome del device: <tipo>-<luogo>, minuscolo, con trattini. sensore-cucina, relay-caldaia, btproxy-primo-piano, display-ingresso. Il tipo davanti fa sì che l’elenco ordinato alfabeticamente raggruppi per funzione.
Nomi delle entità: corti, senza ripetere il luogo, perché ESPHome antepone già il friendly_name. "Temperatura", non "Temperatura Cucina".
Entità diagnostiche: sempre con entity_category: diagnostic. Segnale Wi-Fi, uptime, tempo dall’ultimo riavvio, versione del firmware finiscono in una sezione separata della scheda del dispositivo e non intasano le dashboard.
- platform: uptime
name: "Uptime"
entity_category: diagnostic
text_sensor:
- platform: version
name: "Versione ESPHome"
entity_category: diagnosticL’uptime merita una parola: un device che si riavvia da solo lo scopri solo se hai l’uptime esposto. Senza, un chip che va in brownout tre volte al giorno sembra perfettamente funzionante. È due righe di configurazione e ti dice la verità su quanto è stabile il tuo parco.
Packages e substitutions: non copiare dodici volte
Al terzo device ti accorgi che stai copiando gli stessi blocchi. La soluzione sono le substitutions per i valori e i packages per i blocchi interi.
Crea un file comune.yaml con tutto quello che è identico ovunque:
esphome:
name: ${nome}
friendly_name: ${nome_esteso}
esp32:
board: esp32-c3-devkitm-1
framework:
type: esp-idf
logger:
api:
encryption:
key: !secret api_key
ota:
- platform: esphome
password: !secret ota_password
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
ap:
ssid: "${nome} Fallback"
captive_portal:
sensor:
- platform: wifi_signal
name: "Segnale Wi-Fi"
entity_category: diagnostic
- platform: uptime
name: "Uptime"
entity_category: diagnosticE poi ogni device diventa corto:
substitutions:
nome: sensore-cucina
nome_esteso: Sensore Cucina
packages:
comune: !include comune.yaml
i2c:
sda: GPIO8
scl: GPIO9
scan: true
sensor:
- platform: bme280_i2c
address: 0x76
temperature:
name: "Temperatura"
humidity:
name: "Umidità"Il vantaggio è che aggiungere l’uptime a tutti i device diventa una modifica sola invece di dodici. L’avvertenza è quella già data in 7 Device Builder in profondita: tieni in comune le cose stabili, perché ogni modifica al file condiviso invalida la cache di tutti i device che lo includono.
Backup: cosa salvare davvero
Le cose che devi poter recuperare sono tre: i file YAML dei device, il secrets.yaml, e le chiavi di cifratura dell’API (che stanno nei file dei device, o nei secrets se hai fatto le cose per bene).
Con l’add-on di Home Assistant le configurazioni stanno in /config/esphome/ e finiscono nei backup automatici (13 Backup e disaster recovery): non devi fare niente. Con Docker o standalone, la cartella va salvata a parte.
La cronologia git del Device Builder non è un backup: sta sullo stesso disco. È una rete di sicurezza contro i tuoi errori, non contro i guasti hardware.
Se metti tutto sotto Git (ottima idea), il secrets.yaml va nel .gitignore prima del primo commit.
Il firmware in sé non va salvato: si ricompila dal YAML in cinque minuti.
Aggiornare, o non aggiornare
ESPHome rilascia una versione al mese. Un chip che non aggiorni da un anno continua a funzionare perfettamente: non c’è nessun obbligo di stare al passo, e nessuna pressione a “tenere tutto aggiornato per il gusto di farlo”.
L’aggiornamento della versione di ESPHome (l’add-on, o l’immagine Docker) non tocca i chip: i device continuano col firmware che hanno finché non li ricompili. La ricompilazione avviene quando decidi tu.
La regola sana: aggiorna ESPHome quando ti serve un componente o una correzione nuova, ricompila un device alla volta partendo da quello meno critico, e verifica che funzioni prima di passare al successivo. Non ricompilare dodici device lo stesso pomeriggio dopo un aggiornamento major, perché se qualcosa si è rotto non saprai cosa.
E prima di un aggiornamento major, leggi le breaking changes del changelog. Sono cinque minuti che evitano di scoprire da soli che ota: è diventato una lista.
Quando riscrivere da zero
Vale la stessa regola del corso Home Assistant: se una configurazione ha dato problemi due volte, indaga; se ne dà tre, buttala e riscrivi.
Le configurazioni ESPHome crescono per accumulo. Aggiungi un filtro perché il valore ballava, poi un delay perché qualcosa arrivava troppo presto, poi un global per ricordare uno stato, e dopo un anno hai un file che nessuno capisce più, nemmeno tu. Riscriverlo da zero sapendo cosa deve fare richiede venti minuti e produce qualcosa di più corto e più chiaro di quanto otterresti debuggando.
Il test finale
Se fra sei mesi un device smette di funzionare mentre sei in vacanza, quanto è facile capire cosa fa e come si ripara? Se la risposta è “apro il YAML, ci sono venti righe leggibili, il nome dice dove sta e l’uptime dice da quanto si riavvia”, sei a posto. Se la risposta è “non ho idea di quale dei tre chip senza nome sia quello in cantina”, il problema non è tecnico: è che hai saltato questo capitolo.
Ricapitolando
- I log sono la prima cosa, sempre. Cerca la prima
[E]in ordine di tempo, non l’ultima. - Il metodo è isolare: configurazione minima con un solo sensore, chip di riserva identico, version history per sapere cosa è cambiato.
- Il computer non vede la board? Cambia cavo prima di ogni altra cosa.
- Riavvii continui +
Brownout detector= alimentazione. Sensore I²C muto = fili invertiti o indirizzo sbagliato. UART muto = TX e RX da incrociare. - Online in Home Assistant ma offline nel Device Builder = mDNS, non un guasto.
- Naming prima:
<tipo>-<luogo>per i device, nomi corti per le entità. - Esponi sempre uptime e segnale Wi-Fi come
entity_category: diagnostic: senza uptime, un device che si riavvia sembra sano. - Packages e substitutions per non copiare dodici volte, ma solo per le parti stabili.
- Salva YAML + secrets + chiavi API; la cronologia git non è un backup; il firmware si ricompila.
- Un chip non aggiornato funziona lo stesso: aggiorna quando ti serve, un device alla volta, leggendo le breaking changes.
- Tre problemi sulla stessa configurazione = riscrivila. È più veloce che debuggarla.
E qui si chiude il corso. La domotica DIY non premia chi ha più device, premia chi ha device che continuano a funzionare quando ci si dimentica che esistono: un sensore da otto euro montato bene, con un nome sensato e l’uptime sotto controllo, vale dieci prototipi su breadboard che nessuno osa più toccare.