Contatori IoT: registrazione di un dispositivo e modalità di firma delle sue letture

Dispositivi IoT: registra un'AMI o un endpoint IoT, copia il suo segreto (mostrato una volta), ruotalo con il nuovo segreto e scopri come il dispositivo firma ogni richiesta a /api/public/utilities/iot/reads — con un esempio di richiesta, i limiti e tutte le risposte che può ricevere.

Un contatore AMI o IoT invia le proprie letture a TRANXACT tramite HTTPS. Ogni dispositivo ha una chiave generata dal server (utd_ seguito da 24 lettere e cifre) e un segreto. Il dispositivo dimostra la propria identità ad ogni richiesta, impedendo a chiunque altro di inviare letture per quel contatore.

Registrazione di un dispositivo

1. Apri CRM › Servizi › Contatori e letture dei servizi › Dispositivi IoT e fai clic su Nuovo.
2. Inserisci un'etichetta, scegli il misuratore che legge e scegli Firma con: hmac (una firma HMAC-SHA256 di ogni richiesta - consigliato), bearer (la chiave e il segreto inviati come token) o entrambi.
3. Imposta il numero massimo di letture al minuto per questo dispositivo e, se conosci la versione del firmware, specifica anche quest'ultima.
4. Salva. La risposta mostra la chiave e il segreto: "Copia il segreto ora, non verrà più mostrato". Inserisci entrambi nella configurazione del dispositivo.

Ruotando il segreto

Nella riga del dispositivo, premi "Nuova chiave segreta" e conferma. La nuova chiave segreta verrà visualizzata una sola volta e la vecchia smetterà di funzionare in quel momento, quindi inserisci subito la nuova chiave segreta nel dispositivo. Imposta lo stato su "Disabilitato" per arrestare un dispositivo senza ruotarlo, oppure su "Ritirato" quando viene messo fuori servizio.

Come un dispositivo registra una lettura

1. Costruisci il corpo JSON: un elenco di letture, ciascuna con read_at (tempo ISO 8601) e lettura. Batteria, segnale, firmware e allarmi sono opzionali.
2. Utilizza l'ora Unix corrente in secondi come timestamp.
3. Calcola l'HMAC-SHA256, utilizzando il segreto del dispositivo, del timestamp, del punto e dei byte esatti del corpo: "<timestamp>.<corpo>". Scrivilo come 64 caratteri esadecimali minuscoli.
4. Invia il corpo della richiesta POST a /api/public/utilities/iot/reads con le intestazioni X-Utility-Device (la chiave), X-Utility-Timestamp e X-Utility-Signature (l'esadecimale, eventualmente preceduto da sha256=).

POST https://<your-tranxact-host>/api/public/utilities/iot/reads
Content-Type: application/json
X-Utility-Device: <utd_DEVICE_KEY>
X-Utility-Timestamp: <1792252800>
X-Utility-Signature: sha256=<64 hex characters>

{"reads":[{"read_at":"<2026-10-17T09:30:00Z>","reading":<48213.4>}],
 "battery_pct":<87>,"signal_dbm":<-71>,"firmware":"<2.4.1>",
 "alarms":[{"type":"<leak>","detail":"<continuous flow 6 h>"}]}

La stessa firma ha funzionato in una shell, per testare un dispositivo prima dell'installazione:

BODY='{"reads":[{"read_at":"<2026-10-17T09:30:00Z>","reading":<48213.4>}]}'
TS=$(date +%s)
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "<DEVICE_SECRET>" | sed 's/^.* //')
curl -X POST "https://<your-tranxact-host>/api/public/utilities/iot/reads" \
  -H "Content-Type: application/json" \
  -H "X-Utility-Device: <utd_DEVICE_KEY>" \
  -H "X-Utility-Timestamp: $TS" \
  -H "X-Utility-Signature: sha256=$SIG" \
  --data-binary "$BODY"

Un dispositivo impostato su bearer (o entrambi) può invece inviare Authorization: Bearer <utd_DEVICE_KEY>.<DEVICE_SECRET> senza intestazioni di firma. HMAC è la scelta più sicura: il segreto non viene mai trasmesso e una richiesta intercettata non può essere riprodotta.

Limiti

• Il timestamp deve essere entro 5 minuti dall'orologio del server: mantieni l'orologio del dispositivo impostato tramite NTP.
• La stessa richiesta firmata due volte viene rifiutata in quanto considerata una ripetizione. Una lettura già presente nel file viene conteggiata come duplicato e memorizzata una sola volta.
• Al massimo 64 KB e 500 letture per richiesta, il dispositivo stesso consente al massimo letture al minuto e 600 richieste al minuto da un singolo indirizzo.
• Il dispositivo deve essere attivo e collegato a un contatore.

Ciò che il dispositivo riceve indietro

Salute e allarmi

• Ogni richiesta aggiorna l'ultimo accesso del dispositivo, la percentuale di batteria e il livello del segnale in dBm. Una batteria inferiore al 15% genera un allarme di batteria scarica.
• Tipi di allarme che un dispositivo può inviare: batteria scarica, manomissione, perdita, flusso inverso, nessun flusso, offline e altri. Un solo allarme aperto per tipo per dispositivo.
• La sezione Allarmi dispositivo li elenca; Cancella ne chiude uno con una nota. Una perdita genera automaticamente un ordine di servizio di indagine sulla perdita ad alta priorità; anche un allarme di manomissione o di flusso inverso genera un ordine di servizio.
• Il dato "IoT Meter Reporting (24h)" del pannello di controllo indica il numero di dispositivi attivi rilevati nelle ultime 24 ore.