ESPHome permette di trasformare una piccola scheda come un ESP32 in un dispositivo completamente integrato con Home Assistant, senza dover imparare a programmare in C++.

Con pochi euro si possono realizzare sensori di temperatura, rilevatori di presenza, Bluetooth Proxy, controller per LED, lettori di consumi, pulsanti, display e moltissimi altri dispositivi personalizzati.

In questa guida vedremo come configurare ESPHome con Home Assistant partendo completamente da zero, compresa la scelta della scheda ESP32, la prima installazione via USB, il collegamento Wi-Fi e l’integrazione finale in Home Assistant.

La procedura è pensata anche per chi non ha mai programmato un microcontrollore.

Cos’è ESPHome

ESPHome è un sistema che permette di creare firmware personalizzati per microcontrollori come ESP32.

Invece di scrivere un programma tradizionale, descriviamo ciò che vogliamo ottenere attraverso un file di configurazione YAML.

ESPHome prende quella configurazione, genera automaticamente il firmware e lo installa sulla scheda.

Per esempio possiamo indicare:

• quale ESP32 utilizziamo;
• quale rete Wi-Fi deve utilizzare;
• quali sensori sono collegati;
• quali pulsanti sono presenti;
• quali GPIO utilizzare;
• quali dati inviare a Home Assistant.

Gli elementi definiti nel dispositivo possono poi comparire direttamente in Home Assistant tramite l’integrazione ESPHome e la sua API nativa. ESPHome – Smart Home Made Simple

In altre parole, non dobbiamo scrivere il codice che gestisce Wi-Fi, API, sensori e Home Assistant: ESPHome svolge gran parte del lavoro per noi.

---

Cosa serve

Per seguire questa guida servono:

• Home Assistant;
• una scheda ESP32;
• un cavo USB che supporti anche il trasferimento dati;
• un computer;
• accesso alla rete Wi-Fi;
• circa 20-30 minuti per il primo dispositivo.

Quale ESP32 comprare

Per iniziare consiglio una normale scheda di sviluppo basata su:

ESP32-WROOM-32 / ESP32 DevKit

È una piattaforma molto diffusa e il supporto ESPHome per l’ESP32 classico è maturo e ben collaudato. ESPHome – Smart Home Made Simple

Su Amazon Italia ho verificato, per esempio, questa scheda ESP32-DevKitC basata su ESP-WROOM-32:

ESP32-DevKitC ESP-WROOM-32 su Amazon.it

Nota: il link è stato verificato, ma prezzo, disponibilità e venditore Amazon possono cambiare nel tempo. Per la guida conta soprattutto scegliere una normale scheda ESP32 / ESP-WROOM-32 dotata di connessione USB. Amazon

Se utilizzi il programma di affiliazione Amazon sul sito, sostituirei naturalmente questo collegamento con il tuo link affiliato, senza cambiare il prodotto consigliato.

---

ESPHome non è una scheda ESP32

Per chi comincia è utile chiarire una cosa.

Un ESP32 è il microcontrollore, cioè l’hardware.

ESPHome è il software che installeremo sull’ESP32.

Quindi non dobbiamo acquistare un fantomatico “ESPHome”: acquistiamo una scheda ESP32 e successivamente installiamo ESPHome al suo interno.

Una volta configurata, la scheda diventerà a tutti gli effetti un dispositivo della nostra smart home.

---

Primo passaggio: installare ESPHome in Home Assistant

Per chi utilizza Home Assistant, il metodo più semplice consiste nell’installare ESPHome Device Builder.

Nelle versioni attuali ESPHome lo descrive come l’interfaccia utilizzata per creare configurazioni, compilare il firmware e installarlo sui dispositivi. ESPHome – Smart Home Made Simple

Da Home Assistant apriamo:

Impostazioni → Apps

e cerchiamo:

ESPHome Device Builder

Quindi selezioniamo:

Installa

Attendiamo la conclusione dell’installazione e premiamo:

Avvia

Infine scegliamo:

Open Web UI / Apri interfaccia Web

A seconda della traduzione e della versione di Home Assistant, alcuni nomi dell’interfaccia potrebbero essere leggermente differenti.

La documentazione ESPHome corrente indica proprio la sequenza Install → Start → Open Web UI. ESPHome – Smart Home Made Simple

Se ESPHome Device Builder non compare

La documentazione ufficiale indica che, se l’app non fosse presente, può essere necessario aggiungere il repository ufficiale ESPHome.

Per la maggior parte delle installazioni Home Assistant OS recenti non dovrebbe essere necessario.

---

Secondo passaggio: collegare l’ESP32 al computer

Per la prima installazione il dispositivo deve normalmente essere collegato tramite USB.

Questa è una distinzione importante.

La prima volta utilizziamo:

computer → USB → ESP32

Dopo aver installato ESPHome potremo invece effettuare quasi tutti gli aggiornamenti successivi direttamente attraverso il Wi-Fi.

Questo sistema viene chiamato OTA, cioè Over The Air. ESPHome

Attenzione al cavo USB

Uno dei problemi più comuni dei principianti non riguarda ESPHome.

Riguarda il cavo.

Esistono cavi USB che permettono soltanto l’alimentazione e non trasportano dati.

Con uno di questi:

• l’ESP32 si accende;
• i LED potrebbero illuminarsi;
• il computer però non rileva nessun dispositivo.

Se ESPHome non riconosce la scheda, la prima prova da fare è quindi cambiare cavo USB.

---

Terzo passaggio: creare il primo dispositivo ESPHome

Apriamo ESPHome Device Builder.

Creiamo un nuovo dispositivo e assegniamogli un nome semplice.

Per esempio:

esp32-soggiorno

Evitiamo nomi complicati, caratteri strani e soprattutto nomi duplicati.

Home Assistant ed ESPHome utilizzano infatti il nome del dispositivo anche per identificarlo sulla rete. La documentazione Home Assistant raccomanda che ogni dispositivo ESPHome abbia un nome univoco. Home Assistant

Come friendly name possiamo invece utilizzare:

ESP32 Soggiorno

La differenza è questa:

• esp32-soggiorno → nome tecnico;
• ESP32 Soggiorno → nome leggibile mostrato all’utente.

---

Scegliere il tipo corretto di ESP32

Questo passaggio è importante.

ESPHome supporta numerose famiglie:

• ESP32;
• ESP32-S2;
• ESP32-S3;
• ESP32-C3;
• ESP32-C6;
• altre varianti.

Se abbiamo acquistato il classico ESP32-WROOM-32, utilizzeremo la variante:

esp32:
  variant: esp32

Nella documentazione corrente ESPHome consiglia di specificare variant, mentre l’utilizzo di board non è più la scelta consigliata nei nuovi progetti. ESPHome – Smart Home Made Simple

È importante selezionare la variante realmente presente sulla scheda.

Un ESP32-C3, per esempio, non deve essere configurato come un ESP32 classico.

---

Quarto passaggio: configurare il Wi-Fi

Il nostro ESP32 deve potersi collegare alla rete di casa.

ESPHome può conservare nome e password del Wi-Fi nel file:

secrets.yaml

È preferibile rispetto a scrivere password e chiavi direttamente nel file principale.

Nel file secrets.yaml possiamo avere:

wifi_ssid: "NomeDellaTuaRete"
wifi_password: "LaTuaPasswordWiFi"

E nella configurazione dell’ESP32:

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

La documentazione ufficiale raccomanda proprio l’utilizzo dei secrets per le credenziali Wi-Fi. ESPHome – Smart Home Made Simple

Una cosa importante sul Wi-Fi

Il classico ESP32 utilizza Wi-Fi 2,4 GHz.

Se la rete domestica utilizza lo stesso SSID per 2,4 e 5 GHz normalmente il router gestirà la situazione.

In caso di problemi di connessione, però, vale la pena verificare che la rete 2,4 GHz sia effettivamente attiva.

---

Quinta fase: configurazione ESPHome completa

Una configurazione di base potrebbe essere simile a questa:

esphome:
  name: esp32-soggiorno
  friendly_name: ESP32 Soggiorno

esp32:
  variant: esp32

logger:

api:
  encryption:
    key: !secret esp32_soggiorno_api_key

ota:
  - platform: esphome

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

sensor:
  - platform: wifi_signal
    name: "Segnale WiFi"
    update_interval: 60s

button:
  - platform: restart
    name: "Riavvia ESP32"

Vediamo cosa significa, riga per riga.

---

esphome

esphome:
  name: esp32-soggiorno
  friendly_name: ESP32 Soggiorno

Definisce l’identità del dispositivo.

name è il nome tecnico.

friendly_name è il nome che vogliamo vedere nell’interfaccia.

---

esp32

esp32:
  variant: esp32

Indica a ESPHome quale famiglia di microcontrollore deve utilizzare.

Nel nostro esempio stiamo utilizzando l’ESP32 classico.

---

logger

logger:

Attiva i log.

Per un principiante sono estremamente utili perché permettono di capire cosa sta facendo l’ESP32 e individuare rapidamente eventuali errori.

Quando qualcosa non funziona, i log sono spesso il primo posto da controllare.

---

api

api:
  encryption:
    key: !secret esp32_soggiorno_api_key

Abilita la comunicazione diretta fra ESPHome e Home Assistant.

Questa comunicazione utilizza la Native API ESPHome.

La documentazione ufficiale supporta la cifratura della connessione attraverso una chiave dedicata e raccomanda l’utilizzo di una chiave differente per ogni dispositivo. ESPHome

Nel nostro secrets.yaml inseriremo quindi qualcosa come:

esp32_soggiorno_api_key: "CHIAVE_GENERATA_DA_ESPHOME"

Non inventiamo manualmente una stringa casuale breve.

Lasciamo che ESPHome Device Builder generi la chiave appropriata.

---

ota

ota:
  - platform: esphome

OTA significa:

Over The Air.

Dopo il primo flash USB potremo aggiornare la configurazione e il firmware attraverso la rete.

Quindi non sarà più necessario andare fisicamente vicino all’ESP32 ogni volta che modifichiamo qualcosa. ESPHome supporta gli aggiornamenti OTA tramite la propria piattaforma nativa. ESPHome

---

Il nostro primo sensore ESPHome

Per verificare immediatamente che tutto funzioni possiamo aggiungere un sensore che non richiede nessun componente esterno.

sensor:
  - platform: wifi_signal
    name: "Segnale WiFi"
    update_interval: 60s

ESPHome leggerà la potenza del segnale Wi-Fi ricevuto dall’ESP32.

In Home Assistant comparirà quindi una nuova entità relativa alla qualità del collegamento wireless.

È un ottimo primo test perché non richiede:

• saldature;
• sensori;
• breadboard;
• resistenze;
• collegamenti GPIO.

---

Aggiungiamo un pulsante di riavvio

Possiamo aggiungere anche:

button:
  - platform: restart
    name: "Riavvia ESP32"

Home Assistant mostrerà un pulsante che permette di riavviare l’ESP32.

Anche questa funzione non richiede componenti esterni.

Il nostro primo progetto ESPHome diventa quindi già utilizzabile senza aver collegato nulla ai GPIO.

---

Sesto passaggio: installare ESPHome sull’ESP32

A questo punto dobbiamo effettuare il primo flash.

Colleghiamo l’ESP32 al computer con USB.

Dal Device Builder scegliamo:

Install

Per la prima installazione seguiamo il percorso relativo al collegamento USB.

ESPHome indica che il primo flash di una scheda nuova deve normalmente essere eseguito tramite collegamento fisico e che successivamente è possibile usare OTA. ESPHome – Smart Home Made Simple

Per il metodo tramite browser, Chrome o Microsoft Edge sono le scelte più semplici.

Il browser ci chiederà quale porta seriale utilizzare.

Se compare un solo dispositivo, generalmente è il nostro ESP32.

Se non compare nulla controlliamo:

1. il cavo USB;
2. la porta USB;
3. eventuali driver;
4. che la scheda sia effettivamente accesa.

---

Cosa succede durante il flash

ESPHome esegue diverse operazioni.

Prima controlla la configurazione YAML.

Poi compila il firmware.

Successivamente carica il firmware sull’ESP32.

Infine il dispositivo si riavvia.

Dopo il riavvio tenterà di collegarsi al Wi-Fi configurato.

La prima compilazione può richiedere più tempo delle successive.

Su macchine poco potenti può richiedere anche diversi minuti. ESPHome segnala infatti che la compilazione è la parte più lenta del processo, soprattutto su host piccoli come Raspberry Pi o Home Assistant Green. ESPHome – Smart Home Made Simple

---

Se ESP32 rimane su “Connecting”

Con alcune schede può essere necessario entrare manualmente nella modalità di programmazione.

La scheda potrebbe avere due pulsanti:

BOOT

e

EN / RESET

Se la scrittura non parte, una procedura comune consiste nel tenere premuto BOOT mentre inizia il collegamento e rilasciarlo quando il caricamento parte.

Non è necessario su tutte le schede.

La documentazione ESPHome sottolinea infatti che sui dispositivi moderni l’ingresso manuale nella modalità di programmazione spesso non serve, ma può essere utile durante il troubleshooting. ESPHome – Smart Home Made Simple

---

Settimo passaggio: controllare i log

Terminata l’installazione, apriamo i log ESPHome.

Dovremmo vedere il dispositivo:

• avviarsi;
• inizializzare il Wi-Fi;
• collegarsi al router;
• ottenere un indirizzo IP;
• avviare l’API ESPHome.

Se tutto funziona, troveremo anche l’indirizzo IP assegnato.

Per esempio:

192.168.1.73

Non utilizzate naturalmente questo indirizzo nel vostro impianto: è soltanto un esempio.

---

Ottavo passaggio: aggiungere ESPHome a Home Assistant

Quando ESPHome è online, Home Assistant normalmente lo rileva automaticamente tramite discovery.

Apriamo:

Impostazioni → Dispositivi e servizi

Potrebbe apparire una notifica relativa a un nuovo dispositivo ESPHome.

Selezioniamo:

Configura

e completiamo la procedura.

Home Assistant utilizzerà la Native API per comunicare direttamente con il dispositivo. Home Assistant

---

Se Home Assistant non trova automaticamente l’ESP32

Nessun problema.

Andiamo su:

Impostazioni → Dispositivi e servizi → Aggiungi integrazione

Cerchiamo:

ESPHome

A questo punto possiamo inserire:

esp32-soggiorno.local

oppure l’indirizzo IP.

Home Assistant documenta entrambe le possibilità; la porta standard dell’API ESPHome è 6053. Home Assistant

Se abbiamo configurato l’encryption key verrà utilizzata anche quella.

---

Cosa vedremo in Home Assistant

Una volta completata l’integrazione dovrebbe comparire:

ESP32 Soggiorno

All’interno troveremo almeno le entità aggiunte nel nostro esempio:

• Segnale WiFi;
• Riavvia ESP32.

Ovviamente questo progetto è soltanto il punto di partenza.

Il vero potenziale di ESPHome arriva quando colleghiamo sensori e attuatori.

---

Aggiornare l’ESP32 senza USB

Da questo momento arriva una delle comodità principali di ESPHome.

Possiamo scollegare l’ESP32 dal computer e alimentarlo, per esempio, tramite un normale alimentatore USB adeguato.

Se successivamente modifichiamo il file YAML, possiamo premere nuovamente:

Install

e scegliere l’aggiornamento attraverso la rete.

Il nuovo firmware verrà trasferito via Wi-Fi tramite OTA.

Non è quindi necessario collegare nuovamente l’USB per ogni modifica. ESPHome

---

Un esempio: trasformare l’ESP32 in un sensore di temperatura

Il passo successivo potrebbe essere collegare un sensore ambientale.

Per esempio:

• BME280;
• DHT22;
• SHT3x.

Con un BME280 possiamo leggere, a seconda del modulo utilizzato:

• temperatura;
• umidità;
• pressione atmosferica.

ESPHome trasforma poi automaticamente questi valori in entità Home Assistant.

È questo il concetto fondamentale da capire:

ESP32 + ESPHome + sensore = dispositivo smart completamente personalizzabile.

---

Altri progetti interessanti con ESPHome

Una volta configurato il primo ESP32 possiamo riutilizzare lo stesso metodo per realizzare moltissimi progetti.

Bluetooth Proxy

Un ESP32 può estendere la copertura Bluetooth di Home Assistant.

È particolarmente utile in case grandi oppure quando Home Assistant si trova lontano dai dispositivi Bluetooth.

Home Assistant supporta ESPHome anche come adattatore remoto o proxy Bluetooth. Home Assistant

Sensore temperatura e umidità

Uno dei progetti più semplici ed economici.

Possiamo visualizzare i valori in Home Assistant e utilizzarli nelle automazioni.

Per esempio:

se umidità bagno > 70%, accendi la ventilazione.

Sensore presenza

Con ESPHome è possibile utilizzare diversi sensori PIR o radar mmWave.

Possiamo quindi creare automazioni molto più intelligenti rispetto al semplice rilevamento di movimento.

Controllo LED

Possiamo controllare:

• LED singoli;
• strip LED;
• LED addressable.

Home Assistant potrà gestire colore, luminosità, effetti e automazioni.

Contatori ed energia

ESPHome viene utilizzato anche per acquisire dati provenienti da:

• contatori;
• sensori di corrente;
• Modbus;
• impulsi;
• sistemi energetici.

Questi dati possono poi alimentare dashboard e automazioni Home Assistant.

---

Perché usare ESPHome invece del cloud

Una delle caratteristiche più interessanti di ESPHome è che l’integrazione con Home Assistant può funzionare localmente.

La Native API mette in comunicazione Home Assistant e il dispositivo direttamente sulla rete domestica. Home Assistant

Questo significa che, per il funzionamento ordinario del dispositivo, non dobbiamo necessariamente dipendere da:

• account esterni;
• server del produttore;
• API cloud;
• servizi in abbonamento.

Naturalmente il funzionamento effettivo dipende sempre dal progetto che realizziamo e dai componenti eventualmente collegati.

---

Sicurezza: non ignorare encryption e secrets

Un ESP32 costa pochi euro, ma può diventare un componente importante della casa.

Se controlla luci, relè, porte o automazioni non dovremmo trattarlo come un semplice giocattolo.

ESPHome raccomanda di utilizzare:

• API encryption;
• una chiave differente per ciascun dispositivo;
• secrets.yaml per conservare credenziali e chiavi.

Senza cifratura della Native API, un dispositivo sulla rete locale potrebbe essere più esposto ad accessi non desiderati. ESPHome – Smart Home Made Simple

Evitiamo inoltre di pubblicare online il nostro secrets.yaml.

---

Errori comuni con ESPHome

ESP32 non viene rilevato dal computer

Provare nell’ordine:

1. altro cavo USB;
2. altra porta USB;
3. altro computer;
4. controllare eventuali driver USB-seriale;
5. utilizzare il pulsante BOOT.

Il cavo è il sospettato numero uno.

---

ESP32 viene programmato ma non compare online

Controllare:

• SSID;
• password;
• Wi-Fi 2,4 GHz;
• qualità del segnale;
• log ESPHome.

Un errore nella password Wi-Fi impedirà naturalmente al dispositivo di collegarsi.

---

Home Assistant non rileva ESPHome

Provare ad aggiungerlo manualmente utilizzando:

nome-dispositivo.local

oppure:

indirizzo-ip

Se il dispositivo funziona ma .local non viene risolto, utilizzare temporaneamente l’IP può aiutare a capire se il problema riguarda mDNS.

---

Dopo una modifica OTA non funziona più

Prima di tutto controlliamo i log.

Se l’ESP32 non riesce più a collegarsi alla rete, potrebbe essere necessario tornare al collegamento USB.

Per questo motivo consiglio, soprattutto ai principianti, di fare modifiche graduali:

1. configurazione base;
2. verifica;
3. aggiunta del primo sensore;
4. verifica;
5. aggiunta delle funzioni successive.

Evitare di modificare contemporaneamente cinquanta righe rende il troubleshooting molto più semplice.

---

Meglio ESP32 o ESP8266?

Per un nuovo progetto oggi sceglierei normalmente ESP32.

L’ESP8266 rimane utilizzabile in numerosi progetti semplici, ma l’ESP32 offre generalmente:

• maggiore potenza;
• più GPIO;
• Bluetooth;
• più possibilità per progetti futuri;
• una gamma molto ampia di varianti.

Per pochi euro di differenza, soprattutto per chi inizia, l’ESP32 offre più spazio per imparare e sperimentare.

---

Meglio ESP32 classico, C3, S3 o C6?

Per seguire questa guida senza complicarsi la vita:

ESP32 classico / ESP-WROOM-32.

È una scelta ottima per:

• sensori;
• GPIO;
• I²C;
• relè;
• Bluetooth Proxy;
• piccoli display;
• automazioni.

Le varianti C3, S3 e C6 sono interessanti per progetti specifici, ma introducono differenze hardware che un principiante non ha bisogno di affrontare nel primo progetto.

ESPHome supporta comunque numerose varianti ESP32 e richiede che quella configurata corrisponda all’hardware realmente utilizzato. ESPHome – Smart Home Made Simple

---

FAQ

Serve saper programmare per usare ESPHome?

No. Bisogna imparare qualche concetto di YAML e comprendere come collegare correttamente l’hardware, ma per moltissimi progetti non è necessario scrivere codice C++.

ESPHome funziona senza Home Assistant?

Sì, ESPHome può essere utilizzato anche in altri contesti, ma l’integrazione con Home Assistant rappresenta uno dei suoi utilizzi principali.

Devo lasciare l’ESP32 collegato al computer?

No. Il collegamento USB serve soprattutto per la prima installazione. In seguito il dispositivo può essere alimentato normalmente e aggiornato via OTA.

ESPHome necessita del cloud?

L’integrazione nativa con Home Assistant può funzionare localmente sulla rete domestica.

Posso usare ESPHome con qualsiasi ESP32?

ESPHome supporta molte varianti della famiglia ESP32, ma bisogna scegliere la configurazione corretta per il chip utilizzato. ESPHome – Smart Home Made Simple

Quanto costa iniziare?

Una semplice scheda ESP32 costa normalmente poche decine di euro o meno, a seconda del modello e della confezione. Prezzi e disponibilità cambiano frequentemente, quindi conviene controllarli al momento dell’acquisto.

---

Conclusioni

ESPHome è uno dei modi più interessanti per passare dall’utilizzo di dispositivi smart già pronti alla creazione di una domotica realmente personalizzata.

Con una semplice scheda ESP32 possiamo partire da un dispositivo che mostra soltanto il segnale Wi-Fi e trasformarlo successivamente in un sensore ambientale, Bluetooth Proxy, controller LED, sistema di presenza o nodo per monitorare energia e impianti.

Il consiglio per chi inizia è semplice: partire dal progetto minimo descritto in questa guida, verificare che ESP32 e Home Assistant comunichino correttamente e aggiungere un componente alla volta.

In questo modo si impara ESPHome senza trasformare il primo progetto in una lotta contro dieci problemi contemporaneamente.