Il Device Builder che hai usato in 6 Il primo device l’hai usato come un editor di testo con un pulsante “compila”. Sa fare parecchio di più, e le funzioni che quasi nessuno scopre da solo sono proprio quelle che risolvono i due fastidi cronici di ESPHome: il tempo di compilazione e il “avevo una configurazione che funzionava, l’ho modificata, adesso non funziona più e non ricordo cosa ho cambiato”.
La riscrittura arrivata con ESPHome 2026.6.0 non è un restyling: ha aggiunto una cronologia delle versioni basata su git, una coda di compilazione persistente, e la possibilità di delegare i build a un’altra macchina. In questo capitolo vediamo il costruttore visuale, la mappa dei GPIO, la version history, il remote build, e i trucchi per non passare la vita ad aspettare il compilatore.
Il costruttore visuale dei componenti
La differenza più evidente rispetto alla vecchia dashboard è che non sei più obbligato a scrivere YAML a memoria. Dalla pagina di un device, il costruttore ti mostra il catalogo dei componenti disponibili, filtrabile per categoria, e per ognuno un modulo con i campi da compilare: pin, indirizzo, intervallo di aggiornamento, unità di misura.
Quello che scrivi nei campi diventa YAML nel file, in tempo reale e visibile a fianco. Non è un editor alternativo che ti nasconde il testo: è un modo di scoprire cosa esiste e con quali opzioni, senza dover tenere aperta la documentazione in un’altra scheda. Quando conosci già il componente, scrivere a mano resta più veloce; quando stai cercando di capire se ESPHome supporta quel sensore strano che hai comprato, il catalogo è la strada più corta.
Il catalogo di componenti e board viene sincronizzato ogni notte dall’upstream ESPHome, quindi non resta indietro rispetto alla documentazione ufficiale.
La mappa dei GPIO
Questa è la funzione che avrebbe fatto risparmiare a chiunque un paio di serate. La pagina del device mostra la piedinatura della board selezionata, con lo stato di ogni pin: liberi, già assegnati (e a quale componente), e quelli che è meglio non toccare.
Serve a due cose. La prima è vedere i conflitti prima di compilare: se hai assegnato GPIO8 sia all’I²C sia a un pulsante, la mappa lo evidenzia. La seconda, più preziosa, è avere sott’occhio i vincoli di cui abbiamo parlato in 3 Pin bus e alimentazione, pin di strapping, pin della flash, input-only, senza doverli ricordare a memoria per sei chip diversi.
Rimane comunque uno strumento di supporto, non un oracolo: conosce la board che gli hai dichiarato, e se hai comprato un clone con una piedinatura leggermente diversa non può saperlo. Il pinout stampato sul PCB resta l’ultima parola.
Version history: la rete di sicurezza
Ogni volta che salvi un file, il Device Builder fa un commit git. Non devi configurare niente, non devi sapere cosa sia git: la cronologia c’è e basta.
Da qui si fanno due cose che prima erano impossibili senza disciplina personale:
Confrontare. Apri la cronologia di un device e vedi le differenze fra due versioni. Quando un chip smette di funzionare dopo una modifica, la domanda “cosa ho cambiato esattamente?” ha una risposta in dieci secondi.
Recuperare. Configurazioni cancellate per sbaglio, modifiche che sembravano buone e non lo erano, file sovrascritti: tutto è recuperabile. È il rimedio a un errore che capita a tutti almeno una volta, cioè cancellare il device sbagliato dalla lista.
Non sostituisce il backup: se muore il disco del server, muore anche il repository git. Continua a valere quello che dice 13 Backup e disaster recovery, con l’add-on le configurazioni sono già dentro i backup di Home Assistant, negli altri casi la cartella va salvata a parte.
Remote build: compilare altrove
Questa è la risposta al problema più concreto di chi ha Home Assistant su hardware modesto. La compilazione è pesante di CPU e soprattutto di disco: su un Home Assistant Green o su un Raspberry con scheda SD, un build da zero può richiedere dieci minuti, e nel frattempo tutta l’istanza rallenta.
Il remote build permette di accoppiare due Device Builder sulla stessa rete locale: uno fa da interfaccia e gestisce i device, l’altro (un PC, un NAS, un server) fa il lavoro di compilazione. Il flash resta locale, cioè il firmware viene comunque inviato al chip dalla macchina giusta.
Il vantaggio è netto: un build che sul Green dura otto minuti su un PC recente ne dura uno. Se hai un computer acceso in casa e Home Assistant su hardware piccolo, è la prima cosa da configurare dopo aver letto questo capitolo.
La coda di compilazione
I build finiscono in una coda persistente, che sopravvive al riavvio del Device Builder e dell’host. Se lanci l’aggiornamento di sei device e nel frattempo riavvii Home Assistant, la coda riprende da dove era rimasta invece di perdere tutto.
Lo scheduler dà priorità ai device che stanno aspettando di ricevere il firmware, il che in pratica significa che se ne aggiorni molti insieme non resti bloccato dietro a un build lungo per un chip che è comunque offline.
È una di quelle funzioni che non noti finché non hai dieci device: con due chip non cambia niente, con dieci è la differenza fra un aggiornamento gestibile e un pomeriggio perso.
Scoperta e stato dei device
La lista dei device mostra chi è online e chi no, e la scoperta avviene via mDNS. Due conseguenze pratiche.
La prima: se un chip risulta offline ma tu sai che funziona, quasi sempre è un problema di multicast, non del chip. Succede con Docker senza --net=host, con VLAN separate per l’IoT, e con certi access point che filtrano il traffico multicast fra client. Il chip continua a parlare con Home Assistant, semplicemente il Device Builder non lo vede.
La seconda: i device configurati con name_add_mac_suffix: true sono esclusi dalla scoperta. È voluto, quell’opzione serve ai firmware di provisioning generici, che si presentano tutti con lo stesso nome, ma se stai usando quella opzione per altri motivi, sappi che il device non comparirà nella lista.
Non aspettare dieci minuti a ogni compilazione
Il tempo di build è il fastidio quotidiano quando lavori attivamente su un chip. Le cose che lo riducono davvero, in ordine di impatto:
Non svuotare la cache. Il pulsante “Clean build files” esiste ed è tentante quando qualcosa non va, ma butta via tutto il lavoro fatto e ti riporta al build da zero. Serve solo dopo un aggiornamento major di ESPHome che ha rotto qualcosa, o quando un errore di compilazione è chiaramente incoerente. Nel resto dei casi, un rebuild “sporco” dopo una modifica minore dura 30-60 secondi.
Compila su una macchina seria. O sposti tutto il Device Builder (Docker su un server, vedi 5 Installare ESPHome Device Builder), o usi il remote build. È l’intervento con più effetto.
Usa esp-idf. Il framework moderno di Espressif è mediamente più veloce da compilare e più efficiente in RAM rispetto ad arduino. Per i progetti nuovi non c’è motivo di usare altro; l’unica eccezione sono i componenti che richiedono ancora esplicitamente il framework Arduino, e sono sempre meno.
Un file per device, senza macro acrobatiche. Condividere configurazioni fra chip diversi con substitutions e packages è ottimo per la manutenzione (ne parliamo in 14 Troubleshooting e pratiche di buon uso), ma se esageri con le condizioni ogni modifica invalida la cache di tutti i device che includono quel pezzo. Tieni in comune le cose stabili (Wi-Fi, OTA, API) e lascia specifico il resto.
HO AGGIORNATO ESPHOME E ORA UN DEVICE NON COMPILA PIÙ. CHE FACCIO?
Nell’ordine: leggi il messaggio d’errore, che di solito nomina il componente colpevole; controlla le breaking changes nel changelog della versione; prova a svuotare la cache solo per quel device. Gli aggiornamenti major di ESPHome ogni tanto cambiano la sintassi di qualche componente (è successo con
ota:, diventato una lista, e con i sensori one-wire). I chip che non ricompili restano intanto perfettamente funzionanti con il firmware vecchio: non c’è nessuna fretta di aggiornare tutto lo stesso giorno.
Modalità expert
C’è un’impostazione expert mode che sblocca opzioni normalmente nascoste: parametri di build avanzati, dettagli del toolchain, funzioni sperimentali. La menziono per completezza e per dire che finché non sai esattamente perché ti serve, lasciala spenta. Le opzioni nascoste sono nascoste perché le impostazioni predefinite sono giuste per quasi tutti.
Ricapitolando
- Il costruttore visuale serve a scoprire componenti e opzioni senza tenere aperta la documentazione; il YAML resta sempre visibile e modificabile.
- La mappa GPIO mostra pin occupati e conflitti, ma conosce solo la board dichiarata: il pinout stampato ha l’ultima parola.
- La version history committa su git a ogni salvataggio: puoi confrontare versioni e recuperare configurazioni cancellate.
- La cronologia non è un backup: la cartella delle config va comunque salvata (con l’add-on lo fa già Home Assistant).
- Il remote build delega la compilazione a una macchina più potente sulla LAN e tiene il flash locale: da otto minuti a uno.
- La coda persistente sopravvive ai riavvii e dà priorità ai device pronti a ricevere: si nota da dieci device in su.
- Chip offline nella lista ma funzionante in Home Assistant = problema di mDNS/multicast, non del chip.
- Non svuotare la cache per abitudine; usa
esp-idf; tieni in comune solo le parti stabili della configurazione.