Questa guida accompagna i laboratori 3 – La piattaforma IoT ThingsBoard e 4 – Progetta il tuo dispositivo IoT. Non serve leggerla tutta: quando nella lezione trovate un passaggio che non vi è chiaro, venite qui e cercate la sezione giusta.
Come si leggono le immagini:
- i riquadri rossi mostrano dove cliccare o che cosa guardare;
- i numeri nei cerchi rossi sono l'ordine dei clic (1, poi 2, poi 3…);
- cliccate un'immagine per vederla a grandezza piena.
Le schermate vengono dalla stessa versione di ThingsBoard di ServerLab (4.3), con un account di prova: "Giulia Rossi" e i token che vedete sono solo esempi. Nel vostro spazio ci saranno il vostro nome e i vostri dispositivi.
In questa guida
- Entrare in ThingsBoard
- Creare un dispositivo
- Il pannello del dispositivo: token, telemetria, attributi
- Creare una dashboard e il primo widget
- Altri widget: grafico, tabella allarmi, terminale dei comandi
- Usare la dashboard: finestra temporale e modifiche
- Le regole di allarme
- Gli allarmi: dove compaiono e cosa farne
- Mandare un comando al dispositivo (RPC)
- Le parole di ThingsBoard
- Per il docente
1. Entrare in ThingsBoard
Dai PC del laboratorio di robotica aprite il browser all'indirizzo http://192.168.104.117:8080.
giulia.rossi@5a.lab), 2 la password che vi ha dato il docente, 3 Accedi.Password dimenticata? Il collegamento sotto il pulsante non funziona: ThingsBoard proverebbe a mandarvi un'email, ma a scuola le email non partono. Chiedete al docente: vi dà una password nuova in un minuto, e i vostri dispositivi e dashboard restano.
Dopo l'accesso si apre la Home. Le parti che userete sono solo tre, nel menu a sinistra:
Che cosa c'è nella Home
Nella Home non si costruisce niente, ma è un buon riassunto del vostro lavoro:
- Inizia (a destra): la lista dei passi base, crea dispositivo, connetti dispositivo, crea dashboard, configura regole di allarme, crea allarme. Ogni passo fatto riceve la spunta: è un modo veloce per vedere a che punto siete. L'ultimo passo, crea cliente e condividi dashboard, nei laboratori non serve.
- Dispositivi e Allarmi: i contatori. Un dispositivo Inattivo vuol dire che lo script non sta mandando dati.
- Dashboard → Ultima visualizzazione: riapre con un clic l'ultima dashboard usata.
- Attività: il grafico di quello che è successo negli ultimi 30 giorni.
Il resto (i modelli dell'IoT Hub, i link alla documentazione in inglese, Utilizzo con i limiti dello spazio, il QR per l'app mobile) si può ignorare.
Ognuno ha uno spazio tutto suo (in ThingsBoard si chiama tenant): i compagni non vedono i vostri dispositivi e voi non vedete i loro. Potete quindi provare tutto senza paura di rompere il lavoro di qualcun altro.
Qualche scritta resta in inglese anche con l'interfaccia in italiano (i nomi dei widget, alcune notifiche, i titoli delle colonne di certe tabelle): è normale.
2. Creare un dispositivo
Un dispositivo è il "gemello" in ThingsBoard di un oggetto vero (o del vostro script Python): riceve le sue misure e gli manda i comandi. Menu Entità → Dispositivi.
cisterna o sensore-aula): è l'unico campo obbligatorio. Etichetta è facoltativa: è un nome più leggibile che compare nelle dashboard. Il profilo lasciatelo default. Poi 2 Aggiungi.Subito dopo, ThingsBoard apre una finestra per "verificare la connettività":
curl, già con il token del dispositivo. Non serve: chiudetela con Chiudi. Lo Stato resta Inattivo finché il dispositivo non manda il primo dato.
3. Il pannello del dispositivo
Cliccate sul nome del dispositivo: a destra si apre il suo pannello, con diverse schede in alto (Dettagli, Attributi, Ultima telemetria, Campi calcolati, Regole allarme… con le frecce < > si vedono le altre).
Il token
TOKEN dello script Python. 2 Gestisci credenziali mostra il token e permette di cambiarlo.Il token è la "password" del dispositivo: chi lo conosce può mandare dati a nome suo. Per questo ogni dispositivo ha il suo, e non va condiviso.
Ultima telemetria: i dati che arrivano
livello) e il valore. La tabella si aggiorna da sola.È il primo posto da guardare quando "non funziona niente":
- se la tabella è vuota, il dispositivo non sta mandando dati (lo script è fermo, o il token è sbagliato);
- se c'è un dato ma con un nome diverso da quello che vi aspettate (
Livelloinvece dilivello), è quello il nome da usare nei widget e negli allarmi: ThingsBoard distingue maiuscole e minuscole.
Le chiavi non si creano a mano: compaiono da sole appena lo script manda un dato nuovo. Il cestino a destra cancella una chiave (con tutti i suoi valori).
Attributi: le informazioni "fisse"
Differenza tra i due tipi di dati:
| Telemetria | Attributi | |
|---|---|---|
| Che cosa sono | misure che cambiano nel tempo | informazioni che cambiano poco o mai |
| Esempi | temperatura, livello, CO₂ | aula, piano, modello del sensore |
| Storico | ThingsBoard tiene tutti i valori (servono per i grafici) | conta solo l'ultimo valore |
| Topic MQTT | v1/devices/me/telemetry |
v1/devices/me/attributes |
4. Creare una dashboard e il primo widget
Una dashboard è una pagina con dei widget: indicatori, grafici, tabelle, pulsanti. Ogni widget legge i dati di un dispositivo. Menu Dashboard.
Cisterna del cortile), poi 4 Aggiungi. Gli altri campi non servono.La dashboard nuova si apre già in modalità modifica, vuota:
I widget sono divisi in raccolte (in inglese bundles). Si può scorrere l'elenco o cercare per nome:
Si apre la configurazione del widget. Questo è il passaggio più importante:
cisterna). 9 La chiave dati: il widget propone una chiave di esempio (qui fuelLevel) che il nostro dispositivo non manda.Il widget mostra N/A? È quasi sempre questo: è rimasta la chiave di esempio. Cliccate la x sulla chiave per toglierla, poi cliccate nel campo vuoto: compare l'elenco delle chiavi che il dispositivo manda davvero (le stesse di Ultima telemetria). Sceglietene una.
livello. 11 Il Titolo della scheda è il testo che compare in alto nel widget: scriveteci qualcosa di chiaro. Poi 12 Aggiungi.
5. Altri widget
Per aggiungerne altri: Modalità modifica → Aggiungi widget.
I widget più utili nei laboratori:
| Per… | Raccolta | Widget |
|---|---|---|
| un numero grande, con il suo nome | Cards | Value card |
| una lancetta (temperatura, velocità) | Analogue gauges o Digital gauges | un indicatore a scelta |
| un serbatoio che si riempie | Liquid level | un tank a scelta |
| l'andamento nel tempo | Charts | Time series chart |
| l'elenco degli allarmi | Alarm widgets | Alarms table |
| mandare comandi al dispositivo | Control widgets | RPC debug terminal (o un interruttore) |
Il grafico nel tempo
Livello, unità %), altrimenti il grafico del livello dirà "Temperature °C".In alto, Usa la finestra temporale della dashboard: il grafico mostra il periodo scelto per tutta la dashboard (vedi la sezione 6).
La tabella degli allarmi
Il terminale dei comandi
6. Usare la dashboard
La finestra temporale
Se il grafico è vuoto ma i dati arrivano, spesso la finestra è troppo corta (o troppo lunga e i punti sono schiacciati): provate con ultimi 15 minuti o ultima ora.
Modificare un widget già fatto
7. Le regole di allarme
Un allarme scatta quando un dato supera una soglia: per esempio quando il livello della cisterna scende sotto il 20 %. A decidere non è lo script, ma una regola su ThingsBoard: così la soglia si cambia senza toccare il dispositivo.
Una regola ha tre parti:
1. ARGOMENTI quali dati guardare
livello
│
▼
2. ATTIVAZIONE quando scatta, e quanto è grave
livello < 20 → Avviso
│
▼
3. CANCELLAZIONE quando si chiude da sola
livello > 20Sul pannello del dispositivo, scheda Regole allarme:
Il nome e gli argomenti
Cisterna quasi vuota). 2 Aggiungi argomento: l'argomento è il dato su cui si basa la regola.
La condizione di attivazione
livello è nella lista. Ora 5 Aggiungi condizione di attivazione.
livello), 10 il tipo di valore (Numerico), 11 l'operazione (minore di) e 12 il valore della soglia (20). Fonte del valore resta Statico. Poi Aggiungi.
La condizione di cancellazione
È facoltativa, ma comoda: senza, l'allarme resta "attivo" anche dopo che il problema è risolto.
L'allarme non scatta mai? Controllate in Ultima telemetria che il valore abbia superato davvero la soglia, e che la chiave dell'argomento sia scritta identica. La regola guarda solo i dati che arrivano dopo il salvataggio.
8. Gli allarmi
Quando la condizione è vera, l'allarme compare in tre posti.
Con i tre puntini ··· nella colonna Dettagli si apre la scheda dell'allarme:
Un allarme ha quindi due "interruttori", e lo stato li dice tutti e due:
| Stato | Cosa vuol dire |
|---|---|
| Attivo non confermato | il problema c'è e nessuno l'ha ancora visto |
| Attivo confermato | il problema c'è, qualcuno se ne sta occupando |
| Ripristinato non confermato | il problema è passato (da solo o chiuso a mano), ma nessuno l'aveva confermato |
| Ripristinato confermato | tutto risolto |
9. Mandare un comando al dispositivo (RPC)
RPC (Remote Procedure Call) vuol dire chiedere al dispositivo di fare qualcosa: accendere la ventola, riempire la cisterna. Lo script deve essere in ascolto sul topic v1/devices/me/rpc/request/+ (come nei kit dei laboratori 3 e 4).
riempi) e premete Invio.
{"pompa":"accesa"}. Se dopo qualche secondo compare un errore di timeout, lo script non è in ascolto (è fermo, o non ha fatto subscribe).
Scrivete help nel terminale per vedere come si usa.
10. Le parole di ThingsBoard
| Parola | Cosa vuol dire |
|---|---|
| Tenant | lo spazio di ognuno: i suoi dispositivi, dashboard e allarmi. Voi ne siete l'amministratore |
| Entità | qualsiasi "cosa" in ThingsBoard: dispositivi, asset (es. un edificio), clienti… |
| Dispositivo | l'oggetto che manda i dati (il vostro script) |
| Token di accesso | la password del dispositivo, da mettere nello script |
| Telemetria | le misure che cambiano nel tempo (con lo storico) |
| Attributi | le informazioni fisse (solo l'ultimo valore) |
| Chiave | il nome di un dato: livello, co2 |
| Dashboard / widget | la pagina / un riquadro della pagina |
| Regola allarme | quando far scattare un allarme e quando chiuderlo |
| Gravità | quanto è grave un allarme: da Critico ad Avviso |
| RPC | un comando mandato dalla piattaforma al dispositivo |
11. Per il docente
Il docente entra con l'account di amministratore di sistema, che vede gli spazi di tutti gli studenti (ma non i loro dati, finché non "entra" nello spazio).
Gli account si creano, si eliminano e si reimpostano con lo script crea_account.py dei materiali del docente (istruzioni in ISTRUZIONI.md):
sudo python3 crea_account.py --da-serverlab 5B_2026 --con-dispositivo # account di una classe
python3 crea_account.py --classe 5B --nuova-password abcd@5b.lab # password dimenticata
python3 crea_account.py --classe 5B --elimina # fine anno