06. Il primo device

Questo è il capitolo in cui il chip smette di essere un concetto e diventa un sensore che vedi in Home Assistant. Costruiamo un sensore di temperatura, umidità e pressione: una ESP32-C3, un BME280, quattro fili, e alla fine tre entità nuove nella dashboard.

Il percorso ha un punto di attrito e uno solo, il primo flash via USB, che è anche l’unica volta in cui toccherai un cavo. Da lì in poi tutto avviene via Wi-Fi. In questo capitolo vediamo il wizard di creazione, il primo caricamento, cosa succede al primo avvio, l’adozione in Home Assistant, e il ciclo di lavoro quotidiano che userai per tutti i device successivi.

Prima di cominciare

Materiale sul tavolo:

• Una board ESP32-C3 (Super Mini o XIAO, vanno bene entrambe)
• Un sensore BME280 in versione I²C, con i pin già saldati
• Una breadboard e quattro jumper, oppure il saldatore se preferisci
• Un cavo USB dati, non uno solo-carica

Il cablaggio è quello già visto in 3 Pin bus e alimentazione: 3V3 → VIN, GND → GND, GPIO8 → SDA, GPIO9 → SCL. Fallo adesso, prima di aprire il Device Builder, così quando il firmware sarà pronto il sensore risponde già.

E ovviamente il Device Builder deve essere installato e raggiungibile: se non l’hai ancora fatto, il capitolo è 5 Installare ESPHome Device Builder.

Creare il device

Apri il Device Builder e premi New device. Il wizard chiede tre cose.

Il nome. Minuscolo, con trattini: sensore-cucina. Diventa l’hostname sulla rete e il prefisso di tutte le entità, quindi vale la pena decidere una convenzione adesso invece che al dodicesimo device. Io uso <tipo>-<stanza>, quindi sensore-cucina, sensore-camera, relay-caldaia.

Le credenziali Wi-Fi. Al primo device te le chiede e le salva in secrets.yaml; dal secondo in poi le riusa senza domandare. Se hai una rete separata per l’IoT, è qui che va indicata, non quella principale.

La board. Il Device Builder ha un catalogo sincronizzato con l’upstream ESPHome: cerchi il modello e lo selezioni, invece di dover indovinare la stringa esatta da mettere in board:. Per una C3 generica va bene esp32-c3-devkitm-1; se hai una XIAO, cerca “XIAO” e trovi la voce dedicata.

Alla fine ti propone di installare subito: salta, per ora. Il device è stato creato ma non ha ancora il sensore dentro, e non ha senso fare due compilazioni quando ne basta una.

Quello che hai ottenuto è lo scheletro già visto in 4 Come funziona ESPHome: esphome:, esp32:, logger:, api:, ota:, wifi:, captive_portal:. La chiave di cifratura dell’API e la password OTA sono state generate automaticamente. Non toccarle e non perderle: la chiave dell’API è quella che Home Assistant userà per parlare col chip.

Aggiungere il sensore

Apri il device appena creato e vai in Edit. In fondo al file aggiungi due blocchi: il bus I²C e il sensore.

i2c:
  sda: GPIO8
  scl: GPIO9
  scan: true
 
sensor:
  - platform: bme280_i2c
    address: 0x76
    temperature:
      name: "Temperatura"
    humidity:
      name: "Umidità"
    pressure:
      name: "Pressione"
    update_interval: 60s

Tre cose da notare.

L’indirizzo 0x76 è quello di fabbrica della maggior parte dei moduli BME280, ma alcuni escono con 0x77. Se il sensore non risponde, prova l’altro: il scan: true te lo dirà con certezza al primo avvio.

I nomi delle entità sono corti ("Temperatura", non "Temperatura Cucina") perché ESPHome antepone automaticamente il friendly_name del device. Il risultato in Home Assistant sarà sensore_cucina_temperatura. Scrivere "Temperatura Cucina" produrrebbe sensore_cucina_temperatura_cucina, che è il tipo di cosa che poi non hai voglia di rinominare.

L’update_interval: 60s è già generoso per la temperatura di una stanza. Metterlo a 10 secondi non ti dà nessuna informazione in più, riempie il database di Home Assistant e tiene la radio accesa più del necessario. Sul tema, 17 Pratiche di buon uso ha già detto tutto quello che serve sul recorder.

Salva. Il Device Builder valida la configurazione in un paio di secondi: se c’è un errore di indentazione o un pin non valido, lo dice adesso, prima di sprecare dieci minuti di compilazione.

Il primo flash: l’unica volta col cavo

Collega la board al computer da cui stai usando il browser. Poi Install → Plug into this computer.

Il Device Builder compila (questo è il build lungo, cinque-dieci minuti la prima volta) e poi ti chiede di selezionare la porta seriale. Il browser apre una finestrella con l’elenco dei dispositivi: scegli il tuo e conferma.

Qui possono succedere due cose fastidiose, entrambe normali.

Il browser non vede nessuna porta. Nell’ordine: il cavo è solo-carica (provane un altro, è la causa più frequente in assoluto); il browser non supporta la Web Serial API (serve Chrome, Edge o un browser Chromium, Firefox e Safari non vanno); manca il driver del convertitore seriale (solo sulle board vecchie con CH340 o CP2102, le C3/S3/C6 hanno l’USB nativo e non ne hanno bisogno).

Il flash parte ma fallisce. Alcune board non entrano da sole in modalità programmazione. Il rimedio manuale è: tieni premuto BOOT, premi e rilascia RESET, poi rilascia BOOT. La board è ora in attesa e il flash riesce. È un gesto che si impara una volta e poi diventa automatico.

Finito il caricamento, la finestra passa allo streaming dei log e vedi il chip che si avvia.

POSSO FLASHARE DA UN COMPUTER DIVERSO DA QUELLO DOVE GIRA IL DEVICE BUILDER?

Sì, ed è la situazione normale se il Device Builder è un add-on su un server in un’altra stanza. La compilazione avviene sul server, ma il flash usa la Web Serial API del browser, quindi il chip va collegato al computer da cui stai navigando. In alternativa, dalla pagina del device puoi scaricare il file .bin e usare web.esphome.io per caricarlo da qualsiasi macchina.

Cosa succede al primo avvio

Nei log vedi la sequenza completa, ed è utile guardarla almeno una volta perché è la stessa che leggerai ogni volta che qualcosa non va.

Il chip si avvia, elenca i componenti che ha dentro, inizializza il bus I²C e (grazie al scan: true) stampa gli indirizzi che rispondono. Se leggi Found i2c device at address 0x76, il cablaggio è corretto. Se leggi Found 0 i2c devices, fermati qui: il problema è nei quattro fili, non altrove.

Poi tenta la connessione Wi-Fi, ottiene un indirizzo IP dal DHCP e registra il proprio nome via mDNS. Da questo momento è raggiungibile come sensore-cucina.local. Infine apre la porta dell’API e aspetta che qualcuno si connetta.

Poco dopo il chip compare nel Device Builder con il pallino ONLINE: la scoperta avviene via mDNS, quindi il Device Builder e il chip devono stare sulla stessa rete (o su reti che si passano il multicast, se hai separato l’IoT su una VLAN: il tema è in Bloccare gli indirizzi dei dispositivi sulla rete).

L’adozione in Home Assistant

Questa è la parte che non richiede quasi niente. Home Assistant scopre il device da solo e ti mostra una notifica in Impostazioni → Dispositivi e servizi, nella sezione “Rilevati”.

Impostazioni → Dispositivi e servizi → ESPHome → Configura.

L’unica cosa che chiede è la chiave di cifratura, quella generata nel blocco api: della configurazione. La copi dal Device Builder e la incolli. Fatto: il dispositivo è aggiunto e compaiono tre entità nuove.

• sensor.sensore_cucina_temperatura
• sensor.sensore_cucina_umidita
• sensor.sensore_cucina_pressione

A questo punto è un dispositivo Home Assistant a tutti gli effetti: lo assegni a un’area, lo metti in una dashboard, ci scrivi automazioni sopra. Tutto quello che sai da 6 Aree, dispositivi, entita e da 8 Automazioni con editor visuale vale identico.

Se non compare da solo, aggiungilo a mano con Aggiungi integrazione → ESPHome e l’indirizzo sensore-cucina.local (o l’IP, se l’mDNS non attraversa la tua rete).

Il ciclo di lavoro da qui in avanti

Da adesso il cavo USB torna nel cassetto. Il ciclo quotidiano è questo:

1. Apri la pagina del device nel Device Builder e premi Edit.
2. Modifichi il YAML: aggiungi un sensore, cambi un intervallo, aggiungi un’automazione locale.
3. Install → Wireless.
4. ESPHome compila (30-60 secondi con la cache calda), invia il binario via Wi-Fi, il chip si riavvia con la nuova configurazione.

Venti-quaranta secondi dal salvataggio al chip aggiornato. È questo che rende ESPHome piacevole da usare: puoi sperimentare senza che ogni tentativo costi una passeggiata fino al sensore.

Il Logs dalla pagina del device apre uno stream in tempo reale sulla stessa connessione Wi-Fi. Quando aggiungi un sensore nuovo, tienilo aperto: vedi le prime letture arrivare e capisci subito se qualcosa non va.

NON PERDERE L'ACCESSO OTA:

Se carichi una configurazione con un errore nel blocco wifi: (SSID sbagliato, password cambiata), il chip non si connette più e non puoi più aggiornarlo via OTA. L’unico rimedio è riprendere il cavo. Per questo la sezione ap: con il fallback hotspot vale la pena tenerla: il chip crea una rete propria e da lì puoi rimetterlo in sesto senza smontarlo dal muro.

Ricapitolando

• Il wizard New device chiede nome, Wi-Fi e board; salta l’installazione iniziale e aggiungi prima i sensori.
• Scegli subito una convenzione di naming (<tipo>-<stanza>): rinominare dopo significa rifare entità e automazioni.
• Nomi delle entità corti: ESPHome antepone già il friendly_name del device.
• Il primo flash è via USB ed è l’unica volta: serve un browser Chromium e un cavo dati vero.
• Se il flash fallisce: BOOT premuto, RESET, rilascia BOOT. Se non vede la porta: cambia cavo.
• scan: true sull’I²C ti dice al primo avvio se il cablaggio è giusto, prima di cercare il problema altrove.
• L’adozione in Home Assistant chiede solo la chiave di cifratura dell’API; il resto è automatico via mDNS.
• Da lì in poi tutto è OTA: modifica, Install → Wireless, 20-40 secondi.
• Tieni il fallback hotspot: è la tua assicurazione contro una configurazione Wi-Fi sbagliata su un chip già montato.