Primi passi con ESPHome

Cos’è ESPHome

Descrivi il dispositivo in un file YAML: quale scheda, quali sensori su quali pin, come si collega alla tua rete. ESPHome trasforma questa descrizione in un firmware, lo compila e lo installa sulla scheda. Home Assistant poi comunica con il dispositivo attraverso l’API nativa di ESPHome, un collegamento diretto sulla porta TCP 6053 che si può cifrare con una chiave da 32 byte.

Per le parti più comuni non c’è codice da scrivere. Quando modifichi lo YAML, reinstalli e il dispositivo usa il nuovo firmware.

Installare ESPHome

Lo strumento in cui lavori si chiama ESPHome Device Builder: una dashboard web che conserva i tuoi file YAML, li compila e installa il firmware. Scegli come farla girare:

• In Home Assistant. Vai in Impostazioni → App, installa ESPHome Device Builder, avvialo e apri la sua interfaccia web. Home Assistant oggi chiama “app” i suoi componenti aggiuntivi; se l’app non compare, aggiungi il repository https://github.com/esphome/home-assistant-addon dal menu ⋮.
• Come app desktop. La pagina di installazione offre ESPHome Device Builder per macOS (un .dmg), per Windows e per Linux (un .deb o un AppImage). Su Linux, se le porte seriali non compaiono, aggiungi il tuo utente al gruppo dialout.
• In Docker. La stessa dashboard risponde sulla porta 6052. Avvia il container con la rete dell’host (--net=host), così può trovare i dispositivi via mDNS; con Docker Desktop pubblica invece la porta 6052.
• Da riga di comando. pip install esphome (se puoi, in un ambiente virtuale), poi esphome run soggiorno.yaml controlla, compila, installa e mostra i log in un solo passaggio.

Per il primissimo flash puoi usare anche ESPHome Web, su web.esphome.io, che scrive il firmware sulla scheda direttamente dal browser. Serve un browser con Web Serial: Chrome, Edge e, secondo la documentazione di ESP Web Tools, Firefox; su iOS non funziona.

Scegliere la scheda

Va bene qualsiasi scheda di sviluppo con ESP32 o ESP8266. Queste quattro sono diffuse, economiche e ben supportate; l’ID della scheda è quello che va nello YAML.

ID delle schede verificati con esphome config su ESPHome 2026.10.2. Il nostro confronto ESP32 elenca le differenze tra i chip.

Se sei indeciso, parti da un ESP32 DevKit: è quello di questa guida, e la maggior parte delle risposte che troverai online lo dà per scontato.

Una prima configurazione, riga per riga

Nel Device Builder, Create device avvia una procedura guidata che scrive quasi tutto per te. Ecco il file completo di un dispositivo chiamato soggiorno, prima di aggiungere sensori:

esphome:
  name: soggiorno              # nome host: minuscole, cifre, trattini
  friendly_name: Soggiorno     # il nome che mostra Home Assistant

esp32:
  board: esp32dev              # la tua scheda
  framework:
    type: esp-idf              # il predefinito dalla 2026.1

logger:                        # log via USB e Wi-Fi

api:                           # il collegamento a Home Assistant
  encryption:
    key: !secret api_key

ota:
  - platform: esphome          # aggiornamenti via Wi-Fi
    encryption:                # riusa la chiave dell’API

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
  ap:                          # hotspot di riserva
    password: !secret ap_password

captive_portal:                # pagina di configurazione dell’hotspot

• esphome: → name è il nome host in rete, soggiorno.local: al massimo 31 caratteri, lettere minuscole, cifre e trattini. friendly_name è quello che mostra Home Assistant.
• esp32: → board dice a ESPHome il chip e la dimensione della flash. Da ESPHome 2026.1 il framework predefinito sull’ESP32 è ESP-IDF; indicarlo esplicitamente rende il file più chiaro. Arduino resta supportato con type: arduino.
• logger: → i log via USB e via rete, di default a livello DEBUG e a 115200 baud.
• api: → l’API nativa che usa Home Assistant, con la sua chiave di crittografia. Senza chiave il collegamento non è cifrato.
• ota: → gli aggiornamenti via Wi-Fi. Da ESPHome 2026.9 un encryption: vuoto li cifra con la chiave dell’API.
• wifi: → la tua rete, letta da secrets.yaml. ap: attiva un hotspot di riserva, con il nome del dispositivo, se per 90 secondi la scheda non riesce a collegarsi.
• captive_portal: → una pagina su quell’hotspot in cui inserire le nuove credenziali del Wi-Fi.

I valori !secret vengono da un secondo file, secrets.yaml, nella stessa cartella:

wifi_ssid: "MyNetwork"
wifi_password: "MyWiFiPassword"
api_key: "…"                   # openssl rand -base64 32
ap_password: "…"

La chiave dell’API è composta da 32 byte casuali codificati in base64: la genera la procedura guidata, oppure il comando nel commento. Non pubblicare mai secrets.yaml.

Un primo sensore: BME280 su I²C

Il BME280 misura temperatura, umidità e pressione e comunica su I²C, quindi gli bastano due fili di segnale. Su un ESP32 DevKit i pin I²C che ESPHome usa di solito sono GPIO21 per SDA e GPIO22 per SCL.

Aggiungi questo in fondo al file:

i2c:
  sda: GPIO21
  scl: GPIO22
  scan: true                   # elenca gli indirizzi trovati

sensor:
  - platform: bme280_i2c
    address: 0x76              # o 0x77, guarda il log
    temperature:
      name: Temperatura
    pressure:
      name: Pressione
    humidity:
      name: Umidità
    update_interval: 60s

• i2c: → il bus e i suoi pin. scan: true, il valore predefinito, scrive nel log gli indirizzi che trova.
• platform: bme280_i2c → il driver del BME280. Il suo indirizzo predefinito è 0x77; molte schedine economiche rispondono a 0x76, come qui. La nostra pagina sull’indirizzo del BME280 spiega come il pin SDO sceglie tra i due.
• Ogni misura ha un name, che diventa un’entità in Home Assistant. update_interval: 60s legge il sensore una volta al minuto.

Preferisci cliccare? Il nostro generatore crea un file equivalente, con questo BME280 già aggiunto, e prepara le chiavi per te. Mette la chiave dell’API direttamente nel file invece che in secrets.yaml e aggiunge i sensori di segnale Wi-Fi e di tempo di attività.Apri il generatore ESPHome

Vuoi un sensore diverso? Il nostro confronto sensori mette fianco a fianco i più comuni, dal DHT22 agli SHT4x.

Il primo flash via USB, poi via Wi-Fi

La primissima installazione deve passare da un cavo USB. Nel Device Builder clicca Install nel riquadro del dispositivo e scegli il metodo:

• Plug into this computer scrive il firmware dal tuo browser. Usa Web Serial, che richiede una pagina sicura: la dashboard aperta in HTTPS, oppure su localhost, come con l’app desktop.
• Plug into the computer running ESPHome Device Builder lo scrive dalla macchina su cui gira la dashboard, per esempio il tuo server Home Assistant.
• Manual download, poi Factory format, ti dà un file .bin da scrivere con ESPHome Web: Connect, scegli la porta, Install.

Da riga di comando, esphome run soggiorno.yaml ti chiede quale porta seriale usare. Se non compare nessuna porta:

• Prova un altro cavo USB: quelli di sola ricarica non hanno i fili dei dati.
• Installa il driver del chip USB-seriale della scheda, di solito un CH34x o un CP2102.
• Tieni premuto il pulsante BOOT della scheda mentre la colleghi, poi rilascialo: così il chip parte in modalità download.

Una volta che il dispositivo si è collegato al tuo Wi-Fi, ogni Install successivo propone Wirelessly, ed esphome run carica il firmware via rete.

Aggiungerlo a Home Assistant

Se l’mDNS funziona sulla tua rete, Home Assistant trova da solo il nuovo dispositivo. Vai in Impostazioni → Dispositivi e servizi: tra i dispositivi Rilevati vedrai un riquadro ESPHome con il suo nome. Clicca Configura, inserisci la chiave di crittografia quando te la chiede (se il Device Builder gira come app di Home Assistant, spesso è già inserita) e scegli un’area.

Se non viene rilevato nulla, clicca Aggiungi integrazione, scegli ESPHome e inserisci soggiorno.local o l’indirizzo IP del dispositivo. Le tre misure del sensore compaiono come entità, pronte per la dashboard.

Tra le opzioni dell’integrazione c’è quella che permette al dispositivo di eseguire azioni di Home Assistant, disattivata di default. Attivala solo per dispositivi di cui ti fidi, e solo se il tuo YAML ne ha bisogno.

Leggere i log

Ogni problema si vede prima di tutto nel log. Nel Device Builder, Logs lo legge via USB se la scheda è collegata, altrimenti via rete; da riga di comando, esphome logs soggiorno.yaml. Quando ti colleghi, il dispositivo stampa la sua configurazione, compresa la scansione I²C:

[C][i2c:113]: Results from bus scan:
[C][i2c:119]: Found device at address 0x76

Il numero dopo i2c indica la riga del codice sorgente di ESPHome, quindi cambia da una versione all’altra. “Found no devices” indica un problema di collegamenti o di alimentazione, non di YAML. Una misura ogni minuto, nelle righe [D], vuol dire che il sensore funziona.

Errori comuni

I pin di strapping decidono come parte il chip: un sensore o un LED che ne tiene uno alto o basso può impedirne l’avvio.

Sicurezza

• Cifratura dell’API. Imposta sempre una chiave: senza, il collegamento non è né cifrato né autenticato, e qualsiasi dispositivo della tua rete può collegarsi.
• Aggiornamenti cifrati. Con encryption: sotto ota: (ESPHome 2026.9 e successivi) il dispositivo accetta solo firmware cifrato con la tua chiave. Le guide più vecchie usano password:; oggi ESPHome avverte che occupa flash e RAM e consiglia la cifratura; le due opzioni non si possono combinare.
• Una password sull’hotspot di riserva. La sua pagina permette a chi si collega di cambiare le impostazioni del Wi-Fi e di caricare un firmware.
• Custodisci i segreti. Non condividere secrets.yaml e fanne una copia di backup: senza la chiave non puoi aggiornare il dispositivo via Wi-Fi.

Tenerlo aggiornato

ESPHome pubblica una nuova versione ogni mese. Aggiornare il Device Builder (o pip install --upgrade esphome) non cambia i tuoi dispositivi: ognuno mantiene il firmware con cui è stato compilato finché non clicchi di nuovo Install. Leggi prima le modifiche incompatibili nelle note di rilascio, poi prova l’aggiornamento su un solo dispositivo prima di passare agli altri.

A batteria: il deep sleep

Un sensore che deve trasmettere solo a intervalli di qualche minuto può dormire nel frattempo con il componente deep_sleep:, regolato da run_duration e sleep_duration. Mentre dorme, Home Assistant lo mostra come non disponibile, e il dispositivo può ricevere aggiornamenti solo quando è sveglio. Scheda, batteria, regolatore e consumi reali sono trattati nella nostra guida per alimentare un ESP32 a batteria.