Accesso alla API

Indirizzo e formato

Tutte le rotte stanno sotto <indirizzo-dell-app>/api/v1, dove <indirizzo-dell-app> è l'indirizzo a cui l'app è pubblicata (schema, host ed eventuale porta, es. https://sensu.esempio.it). Negli esempi compare come variabile $SENSU: impostala una volta nella shell e i comandi si copiano così come sono.

export SENSU=https://<indirizzo-dell-app>

Non è prevista autenticazione: chiunque raggiunga l'indirizzo può leggere e modificare dispositivi, guasti e simulazione. Le richieste con body usano Content-Type: application/json; i campi sconosciuti vengono rifiutati.

Ogni risposta JSON è racchiusa in un envelope:

{"data": ...}                      // successo
{"error": {"message": "..."}}      // errore

Primi passi

# il server risponde?
curl $SENSU/api/v1/healthz

# avvia la simulazione (factor facoltativo: secondi simulati per secondo reale)
curl -X POST $SENSU/api/v1/simulation/start -d '{"factor": 3600}'

# stato della run: state, sim_time, factor, total_readings, active_faults
curl $SENSU/api/v1/simulation

# ultime rilevazioni di una stazione
curl "$SENSU/api/v1/readings?station=st-001&limit=20"

Dispositivi

curl -X POST $SENSU/api/v1/stations -d '{
  "id": "st-100", "name": "Stazione di prova",
  "position": {"lat": 45.05, "lon": 9.69},
  "coverage_radius_km": 2, "capacity": 10
}'

curl -X POST $SENSU/api/v1/sensors -d '{
  "id": "sn-9000", "name": "Termometro di prova",
  "quantity": "temperature", "sampling_period": "5m",
  "station_id": "st-100"
}'

Il sensore non ha coordinate proprie: la posizione è quella della stazione. station_id è facoltativo; sampling_period è una durata (30s, 5m, 1h).

Rilevazioni ed eventi

from e to sono timestamp RFC 3339 sul tempo simulato (es. 2026-01-01T12:00:00Z). Ogni rilevazione riporta collected e collected_at: una misura di un sensore orfano, di una stazione offline o persa dalla rete è generata ma non raccolta.

Stream in tempo reale (SSE)

Per i sistemi a valle, due flussi Server-Sent Events fuori dal prefisso /api/v1. Ogni messaggio ha event: reading o event: event e il JSON nel campo data; un commento : ping ogni 15 s tiene viva la connessione.

# solo ciò che una rete reale consegnerebbe (filtri: sensor, station)
curl -N "$SENSU/stream/readings?station=st-001"

# anche le rilevazioni non raccolte, utile in collaudo
curl -N "$SENSU/stream/readings?all=true"

# guasti e ripristini (filtro: target)
curl -N $SENSU/stream/events

Guasti

curl -X POST $SENSU/api/v1/faults -d '{
  "target_kind": "sensor", "target_id": "sn-0001",
  "fault_kind": "drift", "duration": "2h"
}'

curl $SENSU/api/v1/faults                              # guasti attivi
curl -X DELETE $SENSU/api/v1/faults/sensor/sn-0001     # ripristino

duration è sul tempo simulato ed è facoltativa: senza, il guasto resta finché non lo si rimuove. L'iniezione richiede la simulazione avviata.

Simulazione e scenario

Uso del pannello di gestione

Il pannello governa i dispositivi e la simulazione; i valori misurati si consultano con l'API o con strumenti esterni.

Barra della simulazione

In alto a destra, su ogni pagina: stato della run e tempo simulato, aggiornati ogni 2 secondi. Il campo numerico è il fattore di accelerazione (1 = tempo reale, 3600 = un'ora simulata al secondo) e vale al momento di Start. Pausa sospende, Stop termina la run.

Stazioni

• Nuova stazione apre la finestra di registrazione: codice, nome, coordinate, raggio di copertura, capacità.
• Modifica ed Elimina su ogni riga. Prima di eliminare, la conferma mostra quanti sensori resteranno senza stazione.
• La colonna Sensori indica occupazione e capacità: superarla dà lo stato overloaded, non un blocco.

Sensori

• Il riepilogo in testa conta sensori totali, attivi, in guasto e non assegnati.
• I filtri per stato, stazione e grandezza si applicano subito e restano validi dopo ogni operazione.
• Il pallino accanto alla stazione dice se il sensore sta davvero consegnando dati: sì, no (guasto, disconnessione o stazione offline).
• Da ogni riga si inietta o si rimuove un guasto sul singolo sensore, oltre a modificarlo o eliminarlo.

Associazioni

• Scegli una stazione dalla tendina: l'esito della validazione compare subito, senza applicare nulla.
• Applica conferma. Scegliendo «— nessuna —» il sensore viene dissociato: un sensore non assegnato è una configurazione valida.
• Il superamento della capacità della stazione (over_capacity) è una segnalazione, non impedisce l'associazione.

Operazioni massive

Nelle pagine Stazioni e Sensori seleziona le righe con le caselle (quella in intestazione le seleziona tutte), poi usa la barra sopra la tabella:

• Sensori: Guasta con tipo e durata facoltativa, Ripristina, Associa alla stazione scelta (o dissocia), Elimina selezionati.
• Stazioni: Metti offline con durata facoltativa, Ripristina, Elimina selezionate.

Le operazioni proseguono anche se alcuni elementi falliscono; l'esito riporta per intero cosa è riuscito e cosa no. Guasti e messa offline richiedono la simulazione avviata. Le durate sono sul tempo simulato (30m, 2h); lasciate vuote, il guasto resta fino al ripristino.

Apri Stazioni Apri Sensori Apri Associazioni