Dopo il successo del nostro progetto scolastico per BergamoScienza e l’esplorazione dell’AI su Raspberry Pi 5, facciamo un salto di qualità nella domotica scientifica. Passiamo dal semplice kit da laboratorio a una sentinella IoT sempre connessa, capace di monitorare il fondo radioattivo naturale 24 ore su 24, 7 giorni su 7.
In questa guida pratica vedremo come configurare un contatore Geiger (basato su hardware CAJOE) utilizzando la LilyGo T-Display e la potenza di ESPHome per realizzare un vero sensore IoT di radioattività ambientale, integrabile istantaneamente in Home Assistant.
Segnaliamo un approccio alternativo, basato sull’OPEN DATA, per integrare nel dashboard Home Assistant le misure della radioattività ambientale disponibili su EURDEP : Radioattività in Home Assistant senza hardware • Henrik Sozzi TECH
Che cos’è ESPHome?
Se hai mai programmato un ESP32 con l’IDE di Arduino, sai benissimo che gestire la connessione WiFi, i protocolli MQTT e le librerie per i display può diventare rapidamente un file complesso fatto di centinaia di righe di codice C(++).
ESPHome ribalta completamente questo paradigma. È un sistema open-source che permette di creare firmware personalizzati per ESP32/ESP8266 semplicemente scrivendo un file di configurazione YAML — un formato testuale leggibile e intuitivo. Non scrivi codice complesso: dichiari cosa hai collegato ai pin del tuo microcontrollore e il sistema genera il firmware per te.
I vantaggi di ESPHome per i Maker
- Velocità di sviluppo: Firmware pronti in pochi minuti, senza preoccuparsi delle dipendenze delle librerie.
- Integrazione nativa con Home Assistant: Il dispositivo viene riconosciuto automaticamente come nuova integrazione — zero configurazione manuale.
- Aggiornamenti OTA (Over-The-Air): Dopo il primo flash via USB, aggiorni il firmware del tuo Geiger direttamente via WiFi. Niente più cavi.
- Gestione WiFi robusta: ESPHome gestisce automaticamente riconnessioni e problemi di rete, rendendo il dispositivo affidabile per un monitoraggio continuo.
Sviluppo Assistito dall’AI: Il Ruolo di Claude Code
L’AI come “Compagno di Banco”: Esempi pratici con Claude Code
A differenza dei chatbot tradizionali, Claude Code opera direttamente nel terminale e ha accesso ai file del progetto. Ecco alcuni esempi di prompt che abbiamo utilizzato per raffinare il firmware del contatore Geiger e che puoi replicare per i tuoi progetti.
1. Configurazione del Pinout (Hardware Awareness)
Invece di cercare lo schema della LilyGo T-Display su Google, abbiamo chiesto a Claude:
“Configura i pin SPI per il display ST7789 su una LilyGo T-Display S3 all’interno del file geiger.yaml. Assicurati che i pin CS, DC e Reset corrispondano alla documentazione ufficiale.”
2. Logica di Filtraggio Dati
I dati di un contatore Geiger sono per natura “nervosi”. Per stabilizzare la lettura senza perdere precisione, abbiamo usato questo prompt:
“Modifica il sensore pulse_counter nel file YAML: aggiungi un filtro di media mobile (sliding window) su 10 campioni e crea un sensore ‘copy’ che converta il valore in µSv/h usando il fattore 151. Formatta il risultato con 3 decimali.”
3. Design dell’Interfaccia Grafica
Scrivere il codice C++ (lambda) per disegnare su un display può essere frustrante. Abbiamo risolto così:
“Scrivi la sezione ‘display’ per mostrare il valore in µSv/h al centro dello schermo con un font grande, e i CPM in basso a sinistra con un font piccolo. Aggiungi un titolo ‘RADIAZIONI’ in alto.”
4. Debugging e Validazione
Se ESPHome restituisce un errore di compilazione, basta passare l’errore a Claude:
“ESPHome restituisce un errore di validazione sulla riga 45 del file geiger.yaml riguardo a ‘unit_of_measurement’. Analizza il file e correggi la sintassi secondo lo schema aggiornato di ESPHome.”
Perché questo workflow cambia tutto?
L’uso di Claude Code trasforma il Maker in un “Direttore d’Orchestra”. Non perdi più ore a cercare una virgola fuori posto o il nome esatto di una variabile: descrivi l’intento logico e l’AI si occupa della sintassi specifica di ESPHome.
Questo permette di concentrarsi sulla parte più divertente: sperimentare con l’hardware e analizzare i dati scientifici.
Tutorial: Configurazione del Software con ESPHome
Il file di riferimento che utilizzeremo è esphome-lilygo-tdisplay-cajoe-geiger.yaml, disponibile nel repository ufficiale del FabLab Bergamo su GitHub.
1. Il Sensore: Configurazione del Pulse Counter
Il cuore del sistema è il componente pulse_counter. Il tubo Geiger genera un impulso elettrico per ogni particella ionizzante rilevata; ESPHome conta questi eventi e calcola i CPM (Counts Per Minute), ovvero la misura grezza della radioattività rilevata.
sensor:
- platform: pulse_counter
pin:
number: GPIO12 # Uscita "VIN" del kit Geiger CAJOE
inverted: true
mode: INPUT_PULLUP
unit_of_measurement: 'CPM'
name: "Radiazioni CPM"
update_interval: 60s
id: geiger_cpm2. Conversione Scientifica in µSv/h
Per rendere il dato comprensibile e confrontabile con gli standard internazionali, convertiamo i CPM nell’unità di misura della dose equivalente. Per i tubi cinesi J305/M401 montati sui kit CAJOE, il fattore di conversione standard è 151.
La formula applicata è:
µSv/h = CPM ÷ 151
- platform: copy
source_id: geiger_cpm
name: "Livello Radiazioni"
unit_of_measurement: "µSv/h"
accuracy_decimals: 3
filters:
# Calibrazione specifica per il tubo J305/M401
- lambda: return x / 151.0;
# Media mobile per stabilizzare il grafico ed eliminare i falsi picchi
- sliding_window_moving_average:
window_size: 10
send_every: 1
id: geiger_value3. Visualizzazione sul Display Integrato
Grazie al driver st7789v integrato in ESPHome, configurare la visualizzazione sullo schermo TFT della LilyGo T-Display è sorprendentemente semplice. Il codice seguente mostra i valori aggiornati in tempo reale:
display:
- platform: st7789v
backlight_pin: GPIO4
# Configurazione pin SPI della LilyGo T-Display
cs_pin: GPIO5
dc_pin: GPIO16
reset_pin: GPIO23
lambda: |-
it.printf(0, 0, id(font_title), "RADIAZIONI");
it.printf(0, 40, id(font_value), "%.3f uSv/h", id(geiger_value).state);
it.printf(0, 100, id(font_small), "CPM: %.0f", id(geiger_cpm).state);Integrazione in Home Assistant
Una volta completato il flash del firmware via USB, apri la dashboard di Home Assistant: riceverai automaticamente una notifica che ti invita a configurare il nuovo dispositivo. Da quel momento potrai sfruttare l’intero ecosistema di automazione:
- Grafici storici: Analizza come varia la radioattività di fondo nel tempo e individua eventuali anomalie con i grafici integrati di Home Assistant.
- Automazioni smart: Ad esempio, invia una notifica push sullo smartphone se il livello supera la soglia di attenzione di 0,5 µSv/h, o fai lampeggiare le luci di casa in rosso.
- Monitoraggio remoto: Controlla lo stato radiologico della tua zona ovunque tu sia, tramite l’app ufficiale di Home Assistant.
Conclusione: Dal Prototipo Didattico al Sensore IoT Permanente
Trasformare un progetto didattico in un dispositivo IoT sempre attivo è il modo migliore per testare sul campo le proprie competenze di elettronica e programmazione embedded. Grazie a strumenti come ESPHome e al supporto dell’intelligenza artificiale, la barriera tra idea e prototipo funzionante non è mai stata così sottile.
Vuoi costruire il tuo contatore Geiger IoT?
Ti aspettiamo al FabLab Bergamo per saldare i componenti, programmare il tuo ESP32 e discutere insieme dei prossimi sviluppi — come la realizzazione di un case stagno in stampa 3D per installazioni permanenti all’esterno.