ESPHome: collegare un ESP32 a Home Assistant con il sensore DHT22

Con ESPHome una scheda ESP32 diventa un dispositivo per la casa intelligente senza scrivere C++. L’hardware si descrive in un file YAML e ESPHome costruisce il firmware. Alla fine avrete un ESP32 collegato al Wi-Fi, con un sensore DHT22 che misura temperatura e umidità. Il dispositivo comparirà in Home Assistant e gli aggiornamenti successivi arriveranno via rete. Le strade sono tre: il componente aggiuntivo di Home Assistant, l’app desktop per Windows, macOS e Linux, oppure la riga di comando. I comandi sono quelli della documentazione ufficiale, elencata in fondo.

Cosa serve

• Una scheda di sviluppo ESP32 con porta USB. Secondo la FAQ di ESPHome, l’ESP32 originale è la piattaforma con il supporto più maturo.
• Un cavo USB per i dati. Molti cavi servono solo alla ricarica e non trasmettono dati.
• Un sensore DHT22, una resistenza da circa 4,7 kΩ (se il modulo non ce l’ha già), qualche cavetto jumper e una breadboard.
• Per l’app desktop serve Windows 10 o 11, macOS 10.15 Catalina o successivo, oppure Linux. Per l’installazione con pip va bene qualsiasi sistema con Python 3.12 o successivo.
• Per caricare il firmware dal browser serve un browser che supporti WebSerial. La FAQ cita Firefox, Google Chrome e Microsoft Edge.
• Home Assistant già installato. Per questo c’è la nostra guida dedicata.

Installare ESPHome Device Builder o la riga di comando

ESPHome ha due parti: il firmware che gira sulla scheda e gli strumenti sul computer che lo compilano e lo installano. Quasi tutti usano ESPHome Device Builder, un pannello web per creare le configurazioni, compilarle e caricarle. Il componente aggiuntivo e l’app desktop hanno già il loro ambiente Python. Tutte le varianti sono descritte nella pagina Install ESPHome.

Dentro Home Assistant

Il pulsante della pagina di installazione apre il componente nella vostra istanza: premete Install, poi Start e infine Open Web UI. Questa procedura richiede Home Assistant OS. Se il pulsante non funziona, aprite in Home Assistant Settings → Apps → Install App. Con Home Assistant Container questo menu non c’è: avviate ESPHome Device Builder come container Docker, oppure usate l’app desktop o l’installazione con pip, descritte più avanti. Cercate ESPHome Device Builder nell’elenco e ripetete Install, Start e Open Web UI. Se il componente non compare, aprite il menu ⋮ in alto a destra e scegliete Repositories. Incollate https://github.com/esphome/home-assistant-addon e premete Add, poi chiudete la finestra e cercate di nuovo.

Windows e macOS

Su Windows si scarica l’installer .exe e lo si apre. Quando Windows chiede se consentire all’app di apportare modifiche, rispondete Yes. Seguite le istruzioni e avviate ESPHome Device Builder dal menu Start. Se compare l’avviso «Windows protected your PC», premete More info → Run anyway.

Su macOS si scarica l’immagine .dmg, la si apre e si trascina ESPHome Device Builder nella cartella Applicazioni. Al primo avvio macOS può chiedere una conferma: premete Open. Ci sono versioni per Apple Silicon e per Intel, ma il supporto ai Mac Intel sarà tolto a breve.

Al primo avvio l’app prepara il suo ambiente Python in background e apre il pannello nel browser predefinito. L’icona di ESPHome compare nella barra dei menu di macOS o nell’area di notifica di Windows.

Linux

Per Debian e Ubuntu c’è un pacchetto .deb, per x86_64 e per arm64. Basta un doppio clic nel gestore file. In alternativa, dalla cartella in cui l’avete scaricato si usa il terminale:

sudo apt install ./ESPHome.Device.Builder_*.deb

La stessa pagina offre anche il pacchetto .rpm per Fedora e openSUSE, il pacchetto AUR per Arch e un AppImage. Se le porte seriali non compaiono, aggiungete il vostro utente al gruppo dialout. Il comando cambia solo i gruppi del vostro account. $USER contiene già il vostro nome utente: non va sostituito. Poi chiudete la sessione e rientrate.

sudo usermod -a -G dialout $USER

Solo riga di comando, con pip

Chi preferisce gestire Python da sé può installare lo strumento a riga di comando su qualsiasi sistema con Python 3.12 o successivo:

pip install esphome

Conviene farlo in un ambiente virtuale, perché molte distribuzioni Linux rifiutano l’installazione nel Python di sistema con l’errore externally-managed-environment. Il pannello web per pip è un pacchetto a parte, descritto nella scheda pip della pagina di installazione. Come la versione Docker, risponde all’indirizzo http://localhost:6052.

Creare la configurazione con il Wi-Fi

La configurazione è il file YAML che descrive la scheda. Nel Device Builder premete Create device e scegliete New Device Setup. La procedura guidata chiede la piattaforma, la scheda e i dati del Wi-Fi. Le altre due opzioni sono Import from File, per ripristinare un file esistente, ed Empty Configuration, per partire da un file minimo.

Nel nome del dispositivo usate il trattino e non il trattino basso. Il nome diventa il nome host in rete e la FAQ spiega che nei nomi host il trattino basso non è valido. Da riga di comando la procedura guidata si avvia così:

esphome wizard livingroom.yaml

Secondo la guida Getting Started, il file creato collega la scheda al Wi-Fi e fa poco altro, ma basta per la prima installazione. Se non avete inserito le credenziali Wi-Fi, aggiungetele subito. Senza, la scheda non entra in rete, non comunica con Home Assistant e non riceve gli aggiornamenti via rete. Con il componente di Home Assistant i file finiscono in /config/esphome/.

Togliere le password dal file con secrets.yaml

ESPHome supporta la direttiva !secret di Home Assistant. Le password del Wi-Fi e le chiavi possono quindi stare in un file chiamato secrets.yaml, purché si trovi nella stessa cartella della configurazione. Nel file del dispositivo, al posto del valore, si scrive !secret seguito dal nome della voce definita in secrets.yaml. Così potete condividere o salvare la configurazione senza mostrare la password.

Per tenere tutti i segreti in un solo posto, la FAQ suggerisce di creare nella cartella di ESPHome un secrets.yaml con la sola riga <<: !include ../secrets.yaml. La riga importa il file dei segreti di Home Assistant, che si trova nella cartella superiore.

Controllare la configurazione

Prima di compilare conviene verificare che il file YAML sia corretto. Nel Device Builder aprite il menu ⋮ sulla scheda del dispositivo e scegliete Validate: il controllo non compila niente. Da terminale si usa:

esphome config livingroom.yaml

Il comando mostra come ESPHome interpreta la configurazione e segnala gli errori.

Caricare il firmware la prima volta via USB

La prima installazione deve passare dal cavo USB, quelle successive possono avvenire senza fili. Collegate la scheda con un cavo dati e controllate che il computer la riconosca come porta seriale. Su Windows compare come COM seguito da un numero, su Linux con nomi come /dev/ttyUSB0 o /dev/ttyACM1.

Attenzione: il caricamento sostituisce il firmware presente sulla scheda. La scelta della porta conta soprattutto con ESPHome Web e con esptool, dove il dispositivo seriale si indica a mano. Se avete più dispositivi seriali collegati, staccate e ricollegate la scheda e guardate quale porta compare. Su Windows si controlla in Gestione dispositivi, su Linux con dmesg, come spiegato più avanti.

Ci sono tre strade:

1. Device Builder: premete Install sulla scheda del dispositivo e seguite le istruzioni. Il primo caricamento con questo metodo richiede un browser che supporti WebSerial.
2. ESPHome Web: è l’installer nel browser e secondo la FAQ è la strada più facile. Prima scaricate il firmware: nel Device Builder aprite il menu a tre puntini del dispositivo e scegliete Install, poi Manual download. In ESPHome Web premete Connect, concedete al browser il permesso richiesto e selezionate la porta seriale della scheda. Infine premete Install e scegliete il file scaricato. Il file viene elaborato in locale e non viene caricato su nessun servizio cloud.
3. Riga di comando: esphome run convalida la configurazione e segnala gli eventuali problemi, poi compila e carica il firmware. La prima volta la scheda deve essere collegata via USB.

esphome run livingroom.yaml

Il comando crea anche una cartella con il nome del dispositivo, con il progetto PlatformIO generato.

Alcune schede vanno messe a mano in modalità di programmazione: sulla maggior parte delle schede moderne non serve, ma vale la pena provare se il caricamento non parte. Secondo la pagina Physically Connecting to your Device si collega GPIO0 a GND mentre la scheda si accende. Su molte schede basta tenere premuto il pulsante di boot mentre si collega il cavo, e dopo qualche secondo lo si può rilasciare. Se invece usate un cavetto, potete lasciarlo per tutto il caricamento.

Finito il caricamento, togliete il collegamento fra GPIO0 e GND (o rilasciate il pulsante) e riavviate la scheda togliendo e ridando alimentazione. Con il ponte ancora al suo posto la scheda resta in modalità di programmazione, non entra nel Wi-Fi e non compare in Home Assistant.

Collegare il sensore DHT22 e aggiungerlo al file

Il DHT22 ha bisogno di una resistenza di pull-up sulla linea dati. I collegamenti sono questi:

• VCC del sensore al pin 3.3V dell’ESP32;
• GND del sensore a un pin GND;
• DATA a un pin GPIO libero, a vostra scelta;
• una resistenza da circa 4,7 kΩ fra DATA e 3.3V. Secondo la pagina del componente DHT, probabilmente va bene qualsiasi valore fra 1 e 10 kΩ. Se però avete problemi, tornate ai 4,7 kΩ consigliati dal produttore.

Alcuni moduli DHT22 hanno già la loro resistenza di pull-up. Se il modulo ha già una resistenza e nei log compaiono letture non valide, usate per esempio pin: {number: GPIO16, mode: {input: true, pullup: false}}, sostituendo GPIO16 con il GPIO collegato a DATA.

Per DATA evitate i pin di strapping come GPIO0, che la scheda legge all’avvio. La FAQ li sconsiglia se non sapete con certezza in che stato saranno durante il boot.

Poi premete Edit sul dispositivo e copiate in fondo al file il blocco sensor: con platform: dht. Prendetelo dalla versione attuale della pagina del componente DHT, perché la sintassi può cambiare da una versione all’altra. Nel blocco va adattato quanto segue:

• pin: nell’esempio vale D2, un nome che vale per altre schede. Su ESP32 scrivete il GPIO a cui avete collegato DATA;
• name: sotto temperature: e sotto humidity: sono i nomi che vedrete in Home Assistant;
• model: si può omettere, perché il valore predefinito è AUTO_DETECT, oppure si può impostare a DHT22;
• update_interval: è l’intervallo fra le letture. Se non lo indicate, è di 60 secondi;
• sotto humidity: conviene aggiungere accuracy_decimals: 1. Il valore predefinito è 0 decimali ed è pensato per il DHT11, mentre il DHT22 ha una risoluzione maggiore.

Premete Save. Il salvataggio da solo non cambia niente sulla scheda. Ogni volta che modificate la configurazione dovete premere Install per ricompilare il firmware e inviarlo al dispositivo.

Aggiornare via rete e leggere i log

Dopo il primo caricamento il cavo USB non serve più, perché ESPHome aggiorna i dispositivi via rete (OTA). Dal Device Builder basta premere di nuovo Install. Da terminale si usa lo stesso comando del primo caricamento, che adesso invia il firmware via rete:

esphome run livingroom.yaml

Per vedere cosa fa la scheda si aprono i log. Nel Device Builder c’è il pulsante Logs: se la scheda è collegata via USB usa la connessione seriale, altrimenti passa dalla rete. Da terminale, questo comando mostra i log senza caricare niente:

esphome logs livingroom.yaml

Anche il visualizzatore dei log apre una connessione verso la scheda, che si aggiunge a quella di Home Assistant.

Aggiungere il dispositivo a Home Assistant

Quando la scheda è entrata nel Wi-Fi, di solito Home Assistant la trova da sola e propone di configurarla, se la rete lascia passare mDNS. Se non succede, aprite la pagina Integrations e premete Add Integration. Cercate «ESPHome» e inserite il nome host del dispositivo, che deriva dal nome che gli avete dato. Un dispositivo chiamato living-room-lamp, per esempio, risponde a living-room-lamp.local. In alternativa si può usare l’indirizzo IP.

Secondo la FAQ, mDNS non funziona se ESPHome gira in Docker senza rete host, oppure se server e dispositivi stanno su sottoreti o VLAN diverse. In quei casi usate l’indirizzo IP. Per la cifratura delle API, le password OTA e la sicurezza in generale c’è la guida ufficiale Security Best Practices. Tutto il resto, dalle dashboard alle automazioni, riguarda Home Assistant ed è nella nostra guida dedicata.

Se qualcosa va storto

La scheda non compare come porta seriale

Fra le cause più comuni la FAQ indica un cavo solo da ricarica e i driver mancanti. Se installate da un container Docker, il dispositivo va montato nel container con --device=/dev/ttyUSB0. Il modello del chip USB-seriale è inciso sul chip collegato alla porta USB. Di solito è un CH34x, un CP2102 o un PL2303: la pagina Physically Connecting to your Device rimanda ai driver di ciascuno.

Su Windows aprite Gestione dispositivi, collegate la scheda e annotate il numero della nuova porta COM. Su Linux collegate la scheda e subito dopo lanciate:

dmesg

Nell’output compare il nome della nuova porta seriale, per esempio /dev/ttyUSB0.

Il caricamento resta su «Connecting….____….»

• Controllate che il nome della porta non sia cambiato, per esempio da /dev/ttyUSB0 a /dev/ttyUSB1. Succede se si stacca e si ricollega la scheda troppo in fretta.
• Tenete GPIO0 collegato a GND almeno finché il caricamento non è cominciato. Finito il caricamento, togliete il collegamento fra GPIO0 e GND (o rilasciate il pulsante) e riavviate la scheda togliendo e ridando alimentazione: solo così parte normalmente.
• Dopo aver cancellato la flash, togliete e ridate alimentazione: alcune schede non si riavviano da sole.
• Provate a premere due volte il pulsante RST.
• In ambienti con molti disturbi elettrici o con cavi lunghi il trasferimento può fallire. In quel caso basta riprovare.

Scrivere il firmware a mano con esptool

esptool è uno strumento a riga di comando per programmare i microcontrollori Espressif. Spesso è disponibile come pacchetto del sistema operativo, oppure si scarica dal repository GitHub. Su Linux si può installare con pip. Se la distribuzione risponde con externally-managed-environment, vale quanto detto per ESPHome: usate un ambiente virtuale.

pip install esptool

Nei comandi che seguono /dev/ttyUSB0 è solo un esempio. Sostituitelo con la porta della vostra scheda: su Linux quella trovata con dmesg, su Windows la porta COM vista in Gestione dispositivi. Se sbagliate porta, cancellate o sovrascrivete un altro dispositivo.

Attenzione: il prossimo comando cancella tutta la memoria flash del microcontrollore, con firmware, impostazioni e dati. Questa procedura presuppone una scheda senza Secure Boot o Flash Encryption attivi. Se esptool segnala queste protezioni durante la cancellazione o la scrittura, fermatevi e consultate la procedura specifica: non aggiratele con --force, perché si rischia di rendere inutilizzabile la scheda.

esptool --port /dev/ttyUSB0 erase_flash

Il comando successivo scrive il firmware sulla scheda al posto di quello presente. Per scrivere a 0x0 serve l’immagine completa firmware.factory.bin: in Manual download scegliete Factory format, non OTA format. Sostituite your_node_firmware.bin con il percorso del file factory scaricato; non usate il solo firmware.bin applicativo. Con la compilazione da terminale, la directory di progetto predefinita è .esphome/build/<nome-dispositivo>, nella cartella della configurazione. Individuate il percorso effettivo del firmware nell’output della compilazione, perché può cambiare con la toolchain o con build_path.

esptool --port /dev/ttyUSB0 write_flash 0x0 your_node_firmware.bin

Errori di compilazione

Cancellare i file di compilazione risolve spesso gli errori e si può fare in qualsiasi momento. Nel Device Builder c’è Clean build files nel menu ⋮. Da terminale si usa:

esphome clean livingroom.yaml

Letture non valide dal DHT22 o riavvii

Se i log mostrano molti avvisi di temperatura o umidità non valide, impostate il modello a mano con model: DHT22. Controllate anche il valore della resistenza di pull-up e la lunghezza dei cavi. Per i moduli che hanno già la resistenza, valgono le indicazioni su pullup: false nella sezione sul collegamento del sensore.

Se nei log compare «Brownout detector was triggered», la tensione è scesa troppo, di solito durante una trasmissione Wi-Fi. La FAQ consiglia anzitutto di ridurre la potenza di trasmissione del Wi-Fi. Un’altra soluzione è usare un alimentatore di qualità con un cavo USB corto e spesso.

Tenere aggiornato ESPHome

In Home Assistant compare una notifica quando c’è un aggiornamento, come per tutte le altre app. Nell’app desktop gli aggiornamenti si controllano dall’icona di ESPHome nella barra di sistema. Per le installazioni con pip, la FAQ indica questo comando:

pip3 install -U esphome

Con l’immagine Docker, invece, l’aggiornamento consiste nello scaricare di nuovo l’immagine stable di ESPHome, come indicato nella stessa risposta della FAQ.

I file YAML non vengono salvati sulla scheda e da lì non si possono recuperare. Tenetene sempre una copia di backup.

Documentazione di riferimento

Pagine ufficiali di ESPHome consultate il 15 ottobre 2026:

• Install ESPHome
• Getting Started with ESPHome
• Frequently Asked Questions
• DHT Temperature+Humidity Sensor
• Physically Connecting to your Device

Leggi anche

• Home Assistant OS su Raspberry Pi 4 o 5: guida all’installazione