Inviare misure con l'API HTTP

Qualsiasi sistema in grado di inviare una richiesta HTTP con un corpo JSON può alimentare FreeMaint Connect: Node-RED, Home Assistant, un gateway che legge Modbus, un PLC o uno script scritto da te. Crea una connessione di tipo API HTTP (Node-RED, script…) per ottenere il suo URL e la sua chiave di accesso.

La richiesta

Metodo: POST, all'URL mostrato alla creazione della connessione (termina con /connect/ingest/generic).
Header Authorization: Bearer seguito dalla chiave di accesso.
Header Content-Type: application/json.
FreeMaint risponde 202 quando i dati vengono accettati; sono memorizzati in pochi secondi.

Il corpo

Il corpo elenca i dispositivi sotto items. Ogni dispositivo ha un identificatore (device), un nome visualizzato facoltativo, un orario facoltativo (ts, ISO 8601) e i suoi punti. Ogni punto ha una chiave (key), un valore (value) e, idealmente, un'unità di misura (unit) e una grandezza (quantity). La schermata di creazione mostra un esempio completo da copiare.

Campi di un punto

key

Il nome del canale su questo dispositivo, ad esempio power o energy_total. La stessa chiave finisce sempre sullo stesso canale.

value

Un numero.

unit

Ad esempio W, kWh, °C o mm/s. L'energia in Wh o MWh viene convertita in kWh, le temperature in °C, la velocità di vibrazione in mm/s. Le pressioni in Pa, hPa, kPa, mbar, psi, inH2O, inWC o mmH2O vengono convertite in bar. Per leggere un canale in un'altra unità, scegli la sua Unità di visualizzazione in FreeMaint. La pagina del canale mostra l'unità dell'ultima lettura in «Unità ricevuta». Maiuscole e minuscole contano per milli e mega: mW e mWh sono milli, MW e MWh mega. Sono accettati anche i nomi delle unità BACnet, in maiuscolo o minuscolo: «PASCALS», «inches-of-water», «kilowatt-hours»…

quantity

La grandezza misurata, ad esempio power, energy, temperature o vibration_velocity. Permette a FreeMaint di scegliere l'unità e il grafico corretti.

kind

CUMULATIVE per un contatore che può solo aumentare (un totale di energia, ore di funzionamento). FreeMaint calcola quindi il consumo tra due letture. Omettilo per un semplice valore misurato.

Limiti

Fino a 500 dispositivi e 5.000 punti per richiesta.
Fino a 120 richieste al minuto per connessione; oltre, FreeMaint risponde 429 e il tuo sistema deve riprovare più tardi.
Una richiesta malformata riceve una risposta 400 che indica il problema, così un gateway configurato male si corregge facilmente.
Ogni nuovo canale conta ai fini del limite di canali attivi del tuo piano.

Suggerimento

Configurazioni tipiche: un flusso Node-RED che legge un contatore di energia Modbus ogni minuto e ne invia i valori; un'automazione di Home Assistant che inoltra un sensore; un router Teltonika la cui funzione Data to Server invia le letture.

Attenzione

Tieni segreta la chiave di accesso: chiunque la possieda può inviare dati a questa connessione. Se potrebbe essere trapelata, genera una nuova chiave e scegli Revocala subito.