Come installare ESPHome con Home Assistant — Guida completa

ESPHome è un framework firmware open‑source che ti permette di trasformare microcontrollori comuni — come le schede ESP32, ESP8266 e RP2040 — in dispositivi smart home completamente controllabili.

Una “configurazione” del dispositivo in ESPHome è composta da uno o più file YAML. Basandosi su questi file, ESPHome compila un firmware personalizzato che puoi installare direttamente sul tuo dispositivo. Qualsiasi hardware definito nella configurazione — sensori, interruttori, luci, ecc. — apparirà automaticamente nell'interfaccia di Home Assistant.

ESPHome ha due parti principali:

1. Il firmware che gira sul tuo microcontrollore.

2. Lo strumento di gestione che gira sul tuo computer o server (ad esempio, un Raspberry Pi, laptop o desktop) — in questa guida useremo l'add‑on ESPHome Device Builder per Home Assistant, che offre una semplice interfaccia web per creare, modificare e installare configurazioni.

1. Installazione dell'add‑on ESPHome Device Builder

Il modo più semplice per iniziare è installare ESPHome come add‑on di Home Assistant.

Passaggi:

1. In Home Assistant, vai su Impostazioni → Negozio add‑on.

2. Search for ESPHome and click Install.

3. Attendi che l'installazione sia completata (potrebbe richiedere uno o due minuti).

4. Clicca su Avvia, poi su Apri interfaccia Web per avviare il Device Builder.

Nota: Se la tua installazione di Home Assistant non supporta gli add‑on, puoi eseguire ESPHome Device Builder separatamente in Docker.

2. Creazione della tua prima configurazione

Quando apri l'interfaccia Web per la prima volta, una procedura guidata ti accompagnerà nella creazione della tua prima configurazione del dispositivo.

Dovrai:

• Inserisci un nome dispositivo (si consiglia minuscolo con trattini).

• Seleziona il tuo tipo di scheda (es. ESP32 DevKit v1).

• Fornisci il tuo SSID e password Wi‑Fi affinché il dispositivo possa connettersi alla rete dopo il flashing.

Consiglio: La prima installazione su un nuovo dispositivo è spesso il passaggio più intimidatorio. Se non l'hai mai fatto prima, consulta la guida Connessione fisica al tuo dispositivo.

3. Flashare il firmware per la prima volta

Dopo aver creato la tua configurazione, devi installarla sul dispositivo:

1. Collega la tua scheda all'host di Home Assistant tramite USB.

2. In ESPHome, clicca su Installa e scegli l'opzione USB.

3. Una volta flashato, il dispositivo si connetterà al tuo Wi‑Fi e comunicherà con Home Assistant.

4. Esplorare l'interfaccia di Device Builder

La schermata principale di ESPHome Device Builder elenca tutte le configurazioni dei tuoi dispositivi ("nodi"). Per ogni configurazione, puoi:

• Aggiorna — se la versione ESPHome del dispositivo è più vecchia di quella dell'add‑on.

• Modifica — apri l'editor di configurazione YAML.

• Log — visualizza i log del dispositivo tramite USB/seriale o Wi‑Fi.

• Menu overflow — accedi ad azioni extra:

  • Convalida — controlla la configurazione per errori.

  • Installa — apri la finestra di dialogo di installazione.

  • Pulisci i file di build — elimina i file di build generati per risolvere problemi di compilazione.

  • Elimina — rimuovi la configurazione.

Nota: I file di configurazione sono memorizzati in <HOME_ASSISTANT_CONFIG>/esphome/. Accedervi direttamente potrebbe richiedere l'add-on SSH e la disattivazione della “Modalità Protezione” — valuta le implicazioni di sicurezza prima di procedere.

5. Aggiungere funzionalità al tuo dispositivo

Esempio: Interruttore GPIO

Apri il file YAML del tuo dispositivo nell'editor e aggiungi:

 
interruttore:
  - piattaforma: gpio
    nome: "Deumidificatore del Soggiorno"
    pin: GPIO5
  

Questo crea un'entità interruttore in Home Assistant che controlla qualunque cosa sia collegata a GPIO5 — potrebbe essere una luce, un ventilatore o qualsiasi altro dispositivo.

Nell'esempio sopra, stiamo semplicemente aggiungendo un interruttore chiamato "Deumidificatore del Soggiorno" collegato al pin GPIO5. Questo interruttore potrebbe controllare qualsiasi cosa – luci o un ventilatore da tavolo, per esempio. Il suo nome e funzione sono arbitrari e dovrebbero essere impostati in base alla tua applicazione specifica.

Esempio: Sensore Binario

Per monitorare lo stato di un pin GPIO (ad esempio, un sensore di contatto per finestra), aggiungi:

  - piattaforma: gpio
    nome: "Finestra del Soggiorno"
    pin:
      numero: GPIO0
      invertito: true
      modalità:
        input: true
        pullup: true
  

Dopo aver modificato, clicca su Salva per memorizzare le modifiche.

6. Aggiornare il tuo dispositivo

Salvare il file YAML non aggiorna automaticamente il dispositivo. Ogni volta che apporti modifiche:

1. Clicca su Installa per ricompilare il firmware.

2. Reinstallalo sul dispositivo.

Se ESPHome è già installato sul dispositivo, puoi aggiornarlo wireless (OTA) senza riconnettere USB.

7. Collegare il dispositivo a Home Assistant

 AGGIUNGI INTEGRAZIONE AL MIO

Una volta che il dispositivo è stato flashato e connesso al Wi‑Fi:

• Home Assistant dovrebbe scoprirlo automaticamente (se la tua rete supporta mDNS).

• Se no, vai su Impostazioni → Dispositivi & Servizi → Aggiungi Integrazione, cerca ESPHome e inserisci il nome host del dispositivo (es., living-room-lamp.local) o l'indirizzo IP.

Ripeti questo processo per ogni dispositivo ESPHome che aggiungi.

8. Dove andare dopo

🎉 Congratulazioni — hai configurato il tuo primo progetto ESPHome e installato firmware personalizzato sul tuo dispositivo! Hai anche imparato come aggiungere componenti base tramite YAML.

Passi successivi:

• Sfoglia il  Indice dei Componenti per trovare tutto l'hardware supportato.

• Consulta le FAQ per le domande comuni.

• Se riscontri problemi o vuoi richiedere funzionalità, apri un ticket sul  GitHub issue tracker.