05. Installare ESPHome Device Builder

Il Device Builder è l’interfaccia web da cui si creano, si compilano e si aggiornano i device ESPHome. Fino a poco tempo fa si chiamava semplicemente “la dashboard ESPHome”; da ESPHome 2026.6.0 il vecchio strumento è stato sostituito da una riscrittura da zero, con un costruttore visuale dei componenti, una mappa dei GPIO e una coda di compilazione vera. Se hai installato ESPHome un anno fa e non l’hai più aggiornato, quello che vedrai dopo l’update è un’interfaccia diversa: è normale, ed è un miglioramento.

Ci sono quattro modi di installarlo, che non differiscono per funzionalità ma per dove gira la compilazione e per come si gestisce l’autenticazione. In questo capitolo vediamo tutte e quattro, quale scegliere in base a com’è fatta la tua installazione, e come non esporre per sbaglio su Internet uno strumento che scrive firmware.

VERSIONI DI RIFERIMENTO:

Il Device Builder è arrivato alla 1.0 ed è diventato il dashboard predefinito dell’add-on ufficiale con ESPHome 2026.6.0 (giugno 2026). Su versioni precedenti trovi ancora la dashboard classica, oppure il Device Builder come opzione beta da attivare a mano.

Add-on di Home Assistant: la strada normale

Se hai Home Assistant OS o Supervised, questa è la scelta giusta e non ci sono ragioni per complicarsi la vita.

Impostazioni → Add-on → Add-on store → ESPHome → Installa.

Dopo l’installazione, prima di avviarlo, attiva Show in sidebar: ti ritrovi ESPHome fra le voci del menu di Home Assistant e ci accedi con un clic. Avvia l’add-on e apri la voce dalla sidebar.

L’accesso passa per Ingress, il meccanismo con cui Home Assistant fa da proxy agli add-on: sei già autenticato come utente Home Assistant, non c’è una seconda password da gestire e la porta non è esposta separatamente. È il modo più sicuro e il più comodo insieme.

I file delle configurazioni finiscono in /config/esphome/ nella cartella di Home Assistant, quindi entrano nei backup di Home Assistant senza che tu debba fare niente. Se hai seguito 13 Backup e disaster recovery, i tuoi device ESPHome sono già coperti.

L’unico limite serio è la potenza di calcolo. La compilazione è pesante e usa molto disco: su un Home Assistant Green, su un Raspberry con scheda SD o su una VM sottodimensionata, un primo build può richiedere dieci minuti buoni. La soluzione non è cambiare metodo di installazione, è usare il remote build di cui parliamo in 7 Device Builder in profondita.

ESPHome Desktop: se non hai Home Assistant sotto mano

ESPHome Desktop è un’applicazione per Windows, macOS e Linux che porta il Device Builder sul computer, senza dipendere da Home Assistant.

Dalla versione 0.7.0 in poi, l’icona nella tray di sistema permette di scegliere quale backend usare: Backend → ESPHome Builder (stable) oppure (beta), con la possibilità di tornare alla dashboard classica quando serve.

Si lega a 127.0.0.1, quindi non è raggiungibile dalla rete e non c’è nessuna password da configurare. È la strada comoda quando vuoi lavorare sul divano col portatile, o quando il computer è molto più veloce del server che ospita Home Assistant. I device compilati qui compaiono comunque in Home Assistant appena si accendono: la scoperta avviene sulla rete, non attraverso il Device Builder.

Docker: per chi ha già un server

Se hai un NAS o un server con Docker, l’immagine ufficiale include il Device Builder e lo avvia come dashboard predefinita dalla versione 2026.6.0:

docker run --rm -it \
  -v "${PWD}/config:/config" \
  --net=host \
  ghcr.io/esphome/esphome:2026.6.0

L’interfaccia risponde sulla porta 6052. Il --net=host serve perché la scoperta mDNS dei device non funziona con la rete bridge di Docker: senza quello, la dashboard non vedrà mai i chip online.

È la strada che consiglio a chi ha già un server per altre cose: la compilazione gira su una macchina seria, le configurazioni stanno in una cartella che puoi mettere sotto backup o sotto Git, e non pesi sull’istanza Home Assistant. Il tema container in generale è già trattato in Container.

Standalone via pip: server headless e sviluppatori

L’ultima strada è il pacchetto Python:

pip install 'esphome-device-builder[esphome]'
esphome-device-builder ~/esphome-configs

Si avvia su http://localhost:6052 puntando alla cartella che gli passi. Serve soprattutto su server senza interfaccia grafica e a chi vuole integrare ESPHome in uno script o in una pipeline. Se ti serve solo compilare senza dashboard, esiste anche il comando esphome run nomefile.yaml, che fa tutto da riga di comando.

Non esporre il Device Builder su Internet

Questo è il punto su cui vale la pena rallentare. Il Device Builder scrive firmware su dispositivi che stanno in casa tua e contiene le credenziali del tuo Wi-Fi nel file dei secrets. Chi ci arriva dentro non “vede dei sensori”: può caricare codice arbitrario su chip collegati alla tua rete elettrica.

La regola sana è che non deve essere raggiungibile da fuori. Se usi l’add-on con Ingress non devi fare nulla, sei già protetto dall’autenticazione di Home Assistant. Negli altri casi:

• Docker e standalone vanno tenuti sulla LAN. La versione standalone supporta le variabili d’ambiente ESPHOME_USERNAME e ESPHOME_PASSWORD: impostale prima dell’avvio, sempre, anche in casa.
• Se davvero ti serve raggiungerlo da remoto, la risposta è una VPN (WireGuard, Tailscale), non un port forward. Vale esattamente lo stesso ragionamento fatto per Home Assistant in 14 Utenti auth ed esposizione sicura.
• Se lo metti dietro un reverse proxy, configura il proxy perché inoltri l’header Host pubblico, oppure aggiungi il dominio all’opzione --trusted-domains. Senza questo il Device Builder rifiuta le richieste, ed è un comportamento voluto, non un bug.

IL FILE secrets.yaml NON VA SU GIT PUBBLICO:

Se metti la cartella delle configurazioni sotto controllo di versione (ottima idea), aggiungi secrets.yaml al .gitignore prima del primo commit. Contiene la password del Wi-Fi di casa in chiaro. Vale anche per le chiavi di cifratura dell’API e le password OTA, che però stanno dentro i file dei singoli device: se il repository è pubblico, usa !secret anche per quelle.

Quale scegliere, in pratica

Situazione	Strada consigliata
Home Assistant OS o Supervised	Add-on ufficiale, con Ingress e Show in sidebar
HA in container su un server capace	Docker, sullo stesso server, con --net=host
HA su hardware lento (Green, Pi con SD)	Add-on più remote build verso un PC
Nessun Home Assistant, o lavoro dal portatile	ESPHome Desktop
Server headless, automazione, CI	Standalone via pip, o esphome run da CLI

Nel dubbio: add-on. È la configurazione che il 90% delle persone usa, è quella con la documentazione migliore, ed è quella su cui sono scritti gli esempi di questo corso.

Ricapitolando

• Il Device Builder ha sostituito la vecchia dashboard ESPHome ed è il default dell’add-on da ESPHome 2026.6.0.
• Con HAOS/Supervised usa l’add-on ufficiale: Ingress ti autentica già, e le config finiscono nei backup di Home Assistant.
• ESPHome Desktop (v0.7.0+) porta tutto sul computer, legato a 127.0.0.1; il backend si sceglie dalla tray.
• Docker vuole --net=host, altrimenti l’mDNS non scopre i device; risponde sulla porta 6052.
• Standalone via pip per server headless e automazioni; c’è anche esphome run senza dashboard.
• Il Device Builder scrive firmware: non esporlo su Internet. VPN sì, port forward no.
• Fuori da Ingress, imposta sempre ESPHOME_USERNAME e ESPHOME_PASSWORD; dietro reverse proxy serve l’header Host o --trusted-domains.
• secrets.yaml nel .gitignore prima del primo commit, non dopo.