Come installare ESPHome in Home Assistant e creare il primo dispositivo

Installa ESPHome Device Builder in Home Assistant, crea il primo dispositivo con la procedura guidata e collegalo, passo dopo passo.

Ultimo aggiornamento: 7 novembre 2026. Versioni testate su Raspberry Pi 5: Home Assistant Core 2026.11.0, Supervisor 2026.10.5, Operating System 18.4, Frontend 20261028.4, ESPHome Device Builder 2026.10.2.

ESPHome è lo strumento che ti permette di dare “istruzioni” a schede economiche (le più comuni si chiamano ESP32 ed ESP8266) e a molte prese e interruttori smart, senza scrivere programmi veri e propri: descrivi quello che vuoi in un file di testo e ESPHome prepara il software per te. In questa guida installi ESPHome dentro Home Assistant e crei il tuo primo dispositivo. Io lo uso da tempo per quasi tutti i miei progetti, quindi ti segnalo anche i punti in cui è facile inciampare.

ESPHome Device Builder

Cosa otterrai

  • ESPHome Device Builder installato e aperto dalla barra laterale di Home Assistant.
  • Un primo dispositivo creato con la procedura guidata e collegato a Home Assistant.
  • Un file di configurazione che capisci riga per riga, pronto per essere ampliato.

Come si chiama oggi e a cosa serve

Lo strumento si chiama ESPHome Device Builder. In passato era chiamato “add-on ESPHome”; nelle versioni recenti di Home Assistant i componenti aggiuntivi sono indicati come app. Se in rete trovi guide che parlano di “Impostazioni → Add-on”, sappi che il percorso corrispondente oggi è Impostazioni → App.

Il Device Builder è una pagina web: da lì scrivi la configurazione, la “compili” (cioè la trasformi nel software per la scheda) e la invii al dispositivo.

Cosa serve

Alcuni link in questa pagina sono link di affiliazione: se acquisti da lì io ricevo una piccola commissione, senza alcun costo per te. Trovi i dettagli nella pagina Trasparenza e affiliazioni.

  • Home Assistant OS già installato e funzionante (se parti da zero, leggi prima la guida sull’installazione).
  • Una scheda ESP32 per la prova, ad esempio una scheda di sviluppo con presa USB Vedi su Amazon
    Va benissimo anche una ESP8266, ma ha meno memoria.
  • Un cavo USB che trasmetta anche i dati: alcuni cavi (per esempio quelli delle power bank) servono solo a caricare e non funzionano.
  • Un computer con il browser Chrome o Edge per il primo caricamento via USB.
  • Una rete Wi-Fi a 2,4 GHz: questi dispositivi non usano la banda a 5 GHz.

Installare ESPHome Device Builder

  1. Apri Home Assistant e vai in Impostazioni → App, poi scegli Installa app.
    Installazione ESPHome tramite Aggiungi integrazione di Home Assistant
  2. Cerca ESPHome Device Builder e aprilo.
  3. Premi Installa, aspetta la fine e poi premi Avvia.
  4. Premi Apri interfaccia web. Se vuoi, attiva anche l’opzione per mostrarlo nella barra laterale.

Se l’app non compare in elenco, la documentazione ufficiale indica di aggiungere il deposito (repository) dal menu con i tre puntini in alto a destra, alla voce Repositories, inserendo l’indirizzo https://github.com/esphome/home-assistant-addon.

Creare il primo dispositivo

  1. Nella pagina iniziale del Device Builder premi Create device (o il pulsante equivalente nella tua lingua).
    ESPHome creazione nuovo dispositivo tramite ESPHome builder
  2. Scegli New Device Setup, la procedura guidata consigliata a chi inizia. Le altre due voci servono per importare un file esistente o partire da una configurazione vuota.
  3. Dai un nome al dispositivo. Usa solo lettere minuscole, numeri e trattini, per esempio prova-scrivania. Questo nome non si cambia facilmente dopo, quindi sceglilo con cura.
  4. Inserisci il nome e la password della tua rete Wi-Fi quando la procedura li chiede. Se li salti, dovrai aggiungerli tu nel file, altrimenti il dispositivo non potrà collegarsi.
  5. Scegli il tipo di scheda (per esempio ESP32) e il modello più vicino al tuo.
    Scelta scheda da utilizzare in ESPHome builder
  6. Al termine la procedura ti mostra una chiave di cifratura: è la “chiave” con cui Home Assistant e il dispositivo si riconoscono. Non pubblicarla mai. Ne parlo nella guida sulla sicurezza.

Capire il file di configurazione

Premi Edit sul tuo dispositivo: si apre il file in formato YAML. È un semplice testo in cui l’indentazione (gli spazi a sinistra) conta: due spazi in più o in meno cambiano il significato. Ecco un esempio completo e minimo, dove ho aggiunto un pulsante di riavvio per avere qualcosa da provare:

esphome:
  name: prova-scrivania

esp32:
  board: esp32dev

logger:

api:
  encryption:
    key: !secret prova_scrivania_api_key

ota:
  - platform: esphome
    encryption:

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
  ap:
    ssid: "prova-scrivania-hotspot"
    password: !secret prova_scrivania_ap_password

captive_portal:

switch:
  - platform: restart
    name: "Riavvia prova scrivania"

Che cosa fa ogni blocco, in breve:

  • esphome e esp32: il nome e il tipo di scheda.
  • logger: abilita i messaggi di diagnostica, utili quando qualcosa non va.
  • api: il canale cifrato con Home Assistant.
  • ota: permette di aggiornare il dispositivo via Wi-Fi, senza più cavo. La riga encryption: lasciata vuota riusa la stessa chiave di api per proteggere gli aggiornamenti.
  • wifi: la connessione alla tua rete, più un hotspot di emergenza (ap) che parte se il Wi-Fi non è raggiungibile.
  • switch di tipo restart: crea in Home Assistant un interruttore che riavvia la scheda.

Le scritte !secret prendono il valore dal file riservato secrets.yaml, che si trova nella stessa cartella e a cui si accede dal pulsante Secrets del Device Builder. Non scrivere password direttamente nel file: lo vedremo meglio nella guida sulla sicurezza.

Nota: nella versione che ho provato, la procedura guidata genera già la configurazione con i riferimenti ai secrets (le scritte !secret): password e chiavi non compaiono in chiaro. Se nella tua versione le vedi scritte per esteso, spostale tu nel file secrets.

Caricare il software sulla scheda per la prima volta

  1. Collega la scheda con il cavo USB al computer da cui stai usando il browser.
  2. Premi Install sul dispositivo e scegli l’opzione per collegarlo a questo computer (la dicitura esatta può cambiare).
  3. Il browser chiede di scegliere la porta seriale: selezionala e conferma.
  4. Aspetta la compilazione. La prima volta richiede alcuni minuti: nel mio caso circa 3-4 minuti.
  5. Quando ha finito, la scheda si riavvia e si collega al Wi-Fi.

Attenzione: il browser consente l’accesso alla porta USB solo su pagine protette (HTTPS) oppure da localhost. Se apri Home Assistant con un normale indirizzo http://, l’interfaccia ti rimanda al sito ufficiale web.esphome.io per completare il caricamento. In alternativa puoi scaricare il file compilato e caricarlo con strumenti dedicati. Dalla seconda volta in poi gli aggiornamenti passano dal Wi-Fi.

Collegare il dispositivo a Home Assistant

Di solito Home Assistant lo trova da solo: in Impostazioni → Dispositivi e servizi compare la scheda “Rilevato” con il tuo dispositivo, e basta premere Configura. Se non compare, premi Aggiungi integrazione, scegli ESPHome e inserisci il nome del dispositivo seguito da .local (per esempio prova-scrivania.local) oppure il suo indirizzo IP. Se richiesta, incolla la chiave di cifratura.

Prova ora l’interruttore di riavvio: la scheda deve riavviarsi e tornare online da sola.

Problemi comuni

  • Il browser non vede la porta USB. Quasi sempre è un cavo solo-ricarica. Prova un altro cavo. Su alcune schede serve un driver per il chip USB.
  • La compilazione fallisce. Controlla gli spazi di indentazione e usa il comando Validate dal menu con i tre puntini. Nella guida sui log trovi come leggere gli errori.
  • Home Assistant non trova il dispositivo. Verifica che sia sulla stessa rete e usa l’aggiunta manuale con l’IP.
  • Il dispositivo non si collega al Wi-Fi. Controlla nome e password nel file secrets e ricorda che serve il Wi-Fi a 2,4 GHz.

Riepilogo

Hai installato ESPHome Device Builder da Impostazioni → App, creato un dispositivo con la procedura guidata, caricato il primo software via USB e collegato la scheda a Home Assistant. Da qui in avanti gli aggiornamenti arrivano via Wi-Fi.

Articoli correlati

Fonti

Lascia una risposta