Come configurare e integrare un dispositivo ESPHome in Home Assistant

ESPHome è un sistema software che genera firmware da un file YAML per microcontrollori come ESP32 ed ESP8266. Il microcontrollore è l’hardware; ESPHome è il firmware/configuratore; l’integrazione ESPHome di Home Assistant usa la Native API per una connessione locale persistente. Questa guida crea un nodo base sicuro e lo aggiunge a Home Assistant senza assumere pin, sensori o tensioni che cambiano da una scheda all’altra.

Prerequisiti & Hardware Necessario

• Scheda compatibile ESPHome, per esempio ESP32 o ESP8266, con cavo USB dati e alimentazione conforme alla scheda.
• Home Assistant aggiornato, preferibilmente Home Assistant OS con l’app ESPHome Device Builder.
• Rete Wi-Fi 2,4 GHz se la scheda usa Wi-Fi, oppure Ethernet per hardware compatibile.
• Configurazione dei pin e tensioni dal datasheet della scheda. La logica GPIO è spesso 3,3 V, ma ingresso USB, regolatore e morsetti non sono intercambiabili.
• Nessun link d’acquisto viene inserito: la guida è software e non prescrive una specifica scheda.

Procedura passo-passo

1. Identifica la scheda. Leggi modello del microcontrollore, tipo di porta USB, flash disponibile e schema dei pin. Non usare esp32dev o un GPIO solo perché compila: il modello della scheda e il pin reale devono corrispondere.
2. Installa ESPHome Device Builder. In Home Assistant OS apri Impostazioni → App → App store, installa ESPHome Device Builder, abilita Avvia all’avvio e apri l’interfaccia. Per Home Assistant Container/Core usa il metodo ESPHome compatibile con il tuo ambiente.
3. Crea il file YAML del nodo. Sostituisci nome, piattaforma, scheda e credenziali. La chiave API deve essere diversa per ogni dispositivo:

   esphome:
     name: nodo-esp32
     friendly_name: Nodo ESP32
   
   esp32:
     board: esp32dev
     framework:
       type: esp-idf
   
   logger:
   
   api:
     encryption:
       key: !secret api_encryption_key
   
   ota:
     - platform: esphome
   
   wifi:
     ssid: !secret wifi_ssid
     password: !secret wifi_password
     power_save_mode: none
   
   captive_portal:

   Usa il blocco esp8266: e la board corretta se la scheda è ESP8266. Non copiare la piattaforma di un altro modello.
4. Inserisci i segreti. Nel file secrets.yaml della configurazione ESPHome salva SSID, password Wi-Fi e una chiave API Noise PSK base64 di 32 byte:

   wifi_ssid: "NomeWiFi-2G4"
   wifi_password: "PASSWORD_WIFI"
   api_encryption_key: "CHIAVE_BASE64_UNICA_32_BYTE"

   Non condividere secrets.yaml o il YAML completo con le credenziali.
5. Valida e compila. Nel Device Builder apri il nodo e seleziona Validate. Correggi errori YAML, schema della scheda e componenti prima di compilare. La compilazione non dimostra che i pin o l’alimentazione siano corretti.
6. Installa il firmware. Per il primo flash usa USB e il metodo proposto dal Device Builder. Se il browser non rileva la scheda, prova un cavo dati diverso o installa il driver USB-UART richiesto dal chip della scheda. Dopo il primo flash puoi usare OTA solo quando il dispositivo è già online e l’OTA è configurata.
7. Collega il nodo alla rete. Alimenta la scheda secondo il suo manuale e attendi il collegamento Wi-Fi. Il nome mDNS sarà normalmente nodo-esp32.local; una prenotazione DHCP è consigliata per la diagnostica.
8. Aggiungi l’integrazione ESPHome. In Home Assistant apri Impostazioni → Dispositivi e servizi. Se il nodo è scoperto, selezionalo; altrimenti aggiungi ESPHome manualmente e inserisci hostname/IP. La porta predefinita della Native API è 6053/TCP.
9. Inserisci la chiave di cifratura. Quando richiesta, usa la stessa api.encryption.key del firmware. La chiave è una stringa base64 codificata di 32 byte; la vecchia opzione password è deprecata. Non lasciare l’API senza cifratura su una rete non fidata.
10. Aggiungi componenti hardware dopo il nodo base. Inserisci sensori, binary sensor, switch o light solo dopo aver validato il collegamento. Per ogni GPIO consulta schema e datasheet; evita GPIO di boot, flash o seriale quando la scheda li usa internamente.
11. Limita le azioni Home Assistant. Nell’opzione dell’integrazione abilita Allow the device to perform Home Assistant actions solo per nodi fidati che devono richiamare azioni. I log possono essere sottoscritti solo quando servono per diagnostica.
12. Aggiorna con cautela. Prima di aggiornare ESPHome o il firmware esporta YAML e backup Home Assistant. Dopo l’OTA verifica API, entità e comportamento del microcontrollore; mantieni un metodo USB per il recupero.

Verifica del funzionamento

1. In ESPHome esegui Validate e poi compila senza errori.
2. In Home Assistant verifica che il nodo sia disponibile e che la connessione Native API sia cifrata.
3. Controlla che il dispositivo riappaia dopo un riavvio e che il nome resti univoco.
4. Se hai aggiunto un sensore o un relay, modifica il valore/attuatore e osserva l’aggiornamento in tempo reale.
5. Disconnetti temporaneamente Internet lasciando attiva la LAN: l’integrazione locale deve continuare a funzionare.

Problemi comuni

FAQ essenziali

ESPHome usa MQTT?

Non è necessario. La Native API ESPHome comunica direttamente con Home Assistant sulla porta predefinita 6053/TCP. MQTT resta un percorso alternativo se il progetto lo richiede.

Posso usare la stessa chiave API su più dispositivi?

È sconsigliato. Genera una chiave unica per ogni nodo: in caso di compromissione puoi sostituire una sola credenziale.