Come leggere i log e risolvere i problemi più comuni di ESPHome

Come aprire i log dal Device Builder e risolvere errori di compilazione, dispositivi irraggiungibili e Wi-Fi instabile con ESPHome.

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

Quando un dispositivo ESPHome non fa quello che ti aspetti, la prima cosa da fare è smettere di indovinare e leggere i log: il “diario” che il dispositivo scrive mentre lavora. In questa guida impari a leggerli dal Device Builder, a capire i tre problemi più frequenti (la configurazione non si compila, il dispositivo non è raggiungibile, il Wi-Fi si perde) e a risolverli con ordine.

Finestra dei log di un dispositivo nel Device Builder di ESPHome

Cosa otterrai

  • Il metodo per aprire e leggere i log, via Wi-Fi o via cavo.
  • Una lista di controllo per gli errori di compilazione.
  • Una traccia da seguire quando il dispositivo sembra sparito dalla rete.

Come aprire i log

Nel Device Builder, sulla scheda del dispositivo, trovi un pulsante con l’icona di un documento: sono i Logs. Si apre una finestra con il nome del dispositivo; in basso trovi i pulsanti Pulisci (svuota la finestra), Ferma (interrompe la lettura) e l’icona per scaricare il log in un file. Se il dispositivo è collegato via USB al computer, i messaggi arrivano dal cavo; altrimenti arrivano dalla rete. Se il dispositivo è raggiungibile in rete, i log arrivano dal Wi-Fi e nella finestra compare la scritta OTA.

Da riga di comando esiste l’equivalente esphome logs nome-file.yaml, utile se usi ESPHome fuori da Home Assistant.

I messaggi hanno un livello di importanza: dal meno al più dettagliato sono NONE, ERROR, WARN, INFO, DEBUG, VERBOSE e VERY_VERBOSE. Il livello predefinito è DEBUG. Lo imposti nel blocco logger:

logger:
  level: DEBUG
  logs:
    wifi: DEBUG

Con logs puoi alzare o abbassare il dettaglio per un singolo componente (qui il Wi-Fi). Un componente non può essere più dettagliato del livello generale: se vuoi più dettagli sul Wi-Fi, il livello generale deve essere almeno uguale.

Attenzione: VERBOSE e VERY_VERBOSE servono solo per brevi prove: possono rallentare il dispositivo e renderlo meno stabile. Quando hai finito, torna a DEBUG, INFO o WARN. Per i dispositivi in uso quotidiano la documentazione consiglia INFO o WARN.

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.

  • ESPHome Device Builder e un dispositivo già configurato.
  • Le schede più recenti, come molte ESP32, hanno la porta USB integrata: si programmano e se ne leggono i log collegandole direttamente alla porta USB del computer, senza adattatore.
  • Per i casi in cui il Wi-Fi non c’è più: un cavo USB dati e, per schede senza porta USB, un adattatore USB-seriale a 3,3 V. Io uso il DSD TECH SH-U09G, un cavo seriale USB-TTL con chip FTDI FT232RL: prima di collegarlo alla scheda controlla che il livello sia impostato a 3,3 V, perché 5 V possono danneggiarla.
  • Pazienza e un po’ di metodo: cambia una cosa per volta.

Come leggere un log, in tre mosse

  1. Guarda le prime righe dopo il riavvio. Lì compaiono nome, versione e tentativo di connessione al Wi-Fi.
  2. Cerca le righe di tipo avviso o errore. Nel Device Builder gli avvisi sono gialli, gli errori rossi e i messaggi normali verdi.
  3. Copia la riga dell’errore e cercala con le parole del componente interessato (per esempio il nome del sensore) sul sito ufficiale ESPHome.

Quando chiedi aiuto sui forum, incolla il log ma ricordati di togliere nome e password della rete e chiavi se compaiono.

Problema 1: la configurazione non si compila

Prima di installare, usa dal menu con i tre puntini la voce Convalida (in inglese Validate): controlla la configurazione senza compilare, ed è molto più veloce. Poi procedi in questo ordine:

  • Indentazione. Il file YAML usa gli spazi (mai le tabulazioni). Un blocco spostato di due spazi dà errore. Il messaggio di solito indica la riga.
  • Segreto non definito. Ogni !secret nome deve avere una riga con lo stesso nome nel file secrets.yaml.
  • Opzione sconosciuta o deprecata. Se copi un file da un vecchio tutorial, ESPHome può segnalare opzioni non più valide. Un esempio comune è la sintassi di ota: oggi si scrive - platform: esphome come elemento di un elenco. Confronta sempre con la pagina ufficiale del componente.
  • Pin o scheda sbagliati. Verifica il modello nel blocco esp32 o esp8266.
  • Memoria insufficiente su ESP8266. Queste schede hanno poca memoria. La documentazione ufficiale dice che la situazione è migliorata, ma alcuni componenti grandi (display, sensori complessi) possono non funzionare bene. Se vedi riavvii continui dopo l’aggiunta di componenti, togline uno alla volta.
  • Compilazione bloccata dopo un aggiornamento. Dal menu con i tre puntini scegli Pulisci i file di compilazione (Clean build files) (pulisci i file di compilazione) e riprova: elimina i file temporanei che possono essere rimasti da una versione precedente.
Menu dei tre puntini del dispositivo con le voci Convalida e Pulisci i file di compilazione

Problema 2: il dispositivo non è raggiungibile

  1. È acceso? Controlla alimentazione e LED. Se il dispositivo è in un posto difficile, non aprire scatole sotto tensione: stacca la corrente prima, e se si tratta di 230 V fai intervenire un elettricista.
  2. È collegato al Wi-Fi? Guarda l’elenco dei dispositivi del router.
  3. Hai cambiato rete o password? Il dispositivo continua a cercare la vecchia rete. Dopo il tempo previsto (circa 90 secondi, valore predefinito) si attiva l’hotspot di emergenza, se configurato: collegati e inserisci i nuovi dati.
  4. Il nome .local non funziona. Prova con l’indirizzo IP. Se succede spesso, valuta un IP fisso: vedi la guida dedicata.
  5. Home Assistant dice “non disponibile” ma il dispositivo risponde. Controlla la chiave API: se è stata cambiata nel file ma non in Home Assistant, il collegamento viene rifiutato.
  6. Nessun risultato? Collega il cavo e leggi i log dalla porta USB: spesso mostrano il motivo (Wi-Fi non trovato, password sbagliata, riavvii in continuazione).

Problema 3: il Wi-Fi si disconnette o è instabile

Qui mi limito a ciò che è confermato dalla pagina ufficiale del componente Wi-Fi.

  • L’opzione power_save_mode ha tre valori (NONE, LIGHT, HIGH). Il risparmio energetico maggiore può causare disconnessioni frequenti, quindi in caso di problemi prova a lasciare l’impostazione più bassa.
  • Se il dispositivo resta senza Wi-Fi per troppo tempo, si riavvia da solo (il tempo predefinito è di 15 minuti, regolabile con reboot_timeout).
  • Potenza di trasmissione: sull’ESP8266 il valore massimo (20,5) può causare riavvii. Non alzare questo valore senza motivo.
  • Controlla la distanza dal router e la copertura: il segnale si vede anche in Home Assistant, con un sensore wifi_signal. Un consiglio personale: usa una rete Wi-Fi (un SSID) dedicata ai dispositivi IoT, con impostazioni compatibili con queste schede (per esempio solo banda 2,4 GHz). In questo modo, in futuro, potrai separarla dal resto della casa assegnandola a una VLAN dedicata.
sensor:
  - platform: wifi_signal
    name: "Segnale Wi-Fi"
    update_interval: 60s

Problemi comuni, in breve

  • I log sono vuoti. Controlla di avere il blocco logger: e che il livello non sia NONE.
  • I log sono troppo rumorosi. Abbassa il livello globale a INFO o limita un componente con logs.
  • Il dispositivo si riavvia in continuazione. Alimentazione insufficiente, pin sbagliati o memoria esaurita: i log dalla USB mostrano quasi sempre la causa.
  • Dopo un aggiornamento di ESPHome compare un avviso su un’opzione. Leggi l’avviso: indica quasi sempre cosa sostituire.

Riepilogo

Apri i log dal Device Builder, parti dalle righe di errore e cambia una sola cosa alla volta. Se la compilazione fallisce usa Validate e Clean build files; se il dispositivo sparisce, controlla alimentazione, Wi-Fi, chiave e indirizzo; per il Wi-Fi instabile guarda risparmio energetico, segnale e posizione.

Articoli correlati

Fonti

Lascia una risposta