Software Software di base dell'API HALO Smart Sensor
Inoltrare
Questo documento descrive il gruppo di funzioni dell'Halo Smart Sensor noto collettivamente come API BASIC o Application Programming Interface. Questa discussione è destinata all'uso da parte di programmatori o integratori interessati all'integrazione di uno o più HALO Smart Sensor (HALO) con componenti o sistemi software di terze parti (non IPVideo). In generale, l'API HALO ha lo scopo di trasferire le informazioni in modo efficiente da HALO su una rete Ethernet convenzionale al programma esterno. Per raggiungere questo obiettivo, l'API è suddivisa in tre sezioni: connessione socket guidata da eventi, connessione socket heartbeat e dati evento URL. Anche l'interfaccia BACnet è presente e trattata in un documento separato.
Progettazione API
L'API è progettata utilizzando formati standard del settore come TCP/IP. HTTP, HTTPS e JSON. Il design non richiede tecniche o librerie speciali o proprietarie da utilizzare nello sviluppo del programma o dell'applicazione esterna. L'API è flessibile e può essere configurata e programmata per fornire esattamente i dati richiesti e nel modo più efficiente. I dettagli del funzionamento di ciascuna delle sezioni precedenti sono trattati nelle sezioni seguenti di questa guida.
Messaggistica esterna
Questa funzione viene utilizzata per inviare avvisi o allarmi e dati di eventi a un programma esterno, sistema VMS, server, ecc. quando un evento viene attivato (è impostato). I messaggi opzionali possono anche essere abilitati per segnalare quando un evento viene cancellato (viene ripristinato). Questa consegna può essere effettuata in tempo reale su un socket TCP/IP o su un server HTTP/S. Esiste una gamma di protocolli configurabili con contenuti personalizzabili. Autenticazione e crittografia sono disponibili.
Battito del cuore
I messaggi Heartbeat vengono inviati a un intervallo configurabile (invece di quando vengono attivati gli eventi) per fornire una prova di disponibilità/disponibilità. Hanno una gamma di funzionalità simile alla messaggistica esterna, ma in genere sarebbero configurati per contenere informazioni sullo stato generale anziché dettagli su un evento particolare.
Dati degli eventi URL
Questa funzione è disponibile solo nell'ambito di un NDA e deve essere utilizzata solo quando il programma esterno richiede l'accesso a tutti i valori di evento, le soglie e i flag di stato. Questi dati vengono generalmente recuperati su richiesta dal programma esterno ma non a una frequenza molto elevata. Questo metodo generalmente comporta una certa latenza quando viene utilizzata una velocità di polling modesta. Le velocità di polling tipiche vanno da una volta al minuto a una volta ogni 5 secondi con una frequenza massima assoluta di una volta al secondo. Questo metodo può essere utilizzato anche per recuperare dati di supporto aggiuntivi quando viene ricevuto un evento (avviso).
Dettagli della messaggistica esterna
Una sezione dell'HALO web Il popup di integrazione dell'interfaccia fornisce la configurazione di una singola connessione di terze parti in cui vari valori possono essere inviati a un socket TCP remoto oa un server HTTP/HTTPS. I segnaposto (token) vengono utilizzati per inserire valori in tempo reale nel testo trasmesso. Sebbene sia etichettato come "Messaggistica esterna", questo canale può essere utilizzato per quasi tutti gli scopi che richiedono trigger di eventi in tempo reale, forniti attivamente da HALO. Questa disposizione è abbastanza flessibile perché le selezioni sulle “Azioni” determinano quali Eventi HALO trasmettono attraverso questo canale.
In modalità HTTP, le stringhe Set e Reset sono le URLs che devono essere immessi e formattati come richiesto dal server di destinazione desiderato. È possibile utilizzare un campo Utente e Password per l'autenticazione. Vedere la modalità HTTP di seguito.
In modalità TCP, le stringhe Set e Reset sono solo i dati di un singolo messaggio che viene inviato al socket TCP ricevente. Possono essere formattati secondo necessità dalla destinazione. La destinazione è specificata nei campi Indirizzo e Porta. Vedere Modalità TCP di seguito.
Per entrambe le modalità, viene visualizzato lo stato del messaggio più recente che può aiutare a risolvere la connessione o altri problemi. Puoi usare i pulsanti Event TEST sul popup Azioni per forzare un messaggio:
Global On/Off per Set o Reset deve essere On per abilitare questi tipi di messaggi. Il ripristino spesso non viene utilizzato perché interessa solo l'inizio di un evento, ma può variare. Ciascun evento può specificare indipendentemente se utilizzerà il messaggio Imposta o Ripristina nel popup Azioni. I pulsanti del bulbo oculare visualizzeranno una rappresentazione approssimativa di ciò che viene inviato dopo la sostituzione e la formattazione delle parole chiave. Repeat Holdoff può essere utilizzato per limitare i messaggi frequenti ritardando prima che ne possa essere inviato un altro. Questo viene fatto in modo indipendente per Evento. HALO ha un tempo di attesa integrato per gli eventi di 15 secondi per impedire un rapido riavvio degli eventi. Se si desidera assicurarsi che non venga inviato più di 1 evento di un tipo al minuto, è possibile impostare Repeat Holdoff su 60 (secondi).
Dettagli sul battito cardiaco
Le trasmissioni Heartbeat funzionano in modo simile a quanto sopra, tranne per il fatto che non c'è interazione con la pagina Azioni. Invece, la trasmissione Heartbeat avviene regolarmente come configurato con il campo Intervallo, In modalità HTTP, le stringhe Set e Reset sono le URLs che devono essere immessi e formattati come richiesto dal server di destinazione desiderato. È possibile utilizzare un campo Utente e Password per l'autenticazione. Vedere la modalità HTTP di seguito.
Sebbene lo scopo principale di Heartbeat sia fornire la prova della vita di un HALO Smart Sensor a un'applicazione remota, questo messaggio può essere utilizzato anche per trasmettere sensori selezionati o informazioni sullo stato dell'evento corrente. L'example sopra invia un parametro di stringa lunga con il URL che includono il nome Halo, la maggior parte dei valori del sensore e infine Triggered=%ACTIVE% che potrebbe essere vuoto o un elenco di eventi attualmente attivati.
Modalità HTTP (e HTTPS).
Le stringhe di messaggistica esterna e Heartbeat possono essere http: o https: URLse necessario. Il percorso e i parametri possono essere inseriti secondo necessità dal server di destinazione. Parole chiave come %NAME% (nome dispositivo HALO) o %EID% (ID evento) possono essere inserite in base alle esigenze e verranno sostituite con i rispettivi dati quando viene inviato il messaggio. Viene visualizzato un elenco di parole chiave di uso comune per una rapida consultazione.
IL URL percorso può contenere parole chiave così come i parametri per il URL. I parametri potrebbero essere coppie NAME=VALUE o un oggetto JSON o un formato personalizzato a seconda del server di destinazione. Exampi file per la messaggistica esterna includerebbero %EID% per indicare l'evento che ha attivato:
- https://server.com/event/%NAME%/%EID%
- https://server.com/event?location=%NAME%&event=%EID%
- https://server.com/event?{“location”:”:%NAME%”,”event”:”%EID%”}
Exampi le per Heartbeat potrebbero aggiungere %ACTIVE% (eventi attualmente attivati) o un valore del sensore:
- https://server.com/alive?location=%NAME%&Triggered=%ACTIVE%
- https://server.com/event?{“location”:”:%NAME%”,”NH3”:%SENSOR:NH3%}
I valori %SENSOR:…% utilizzano i nomi che si trovano nelle intestazioni della colonna del sensore di destra nel registro evtYYYYMMDD.csv fileS. Sono tipicamente:
Se il server di destinazione preferisce HTTP PUT o POST invece delle richieste GET, puoi anteporre a URL con PUT: o POST:. Indipendentemente, puoi aggiungere un payload JSON che è popolare con molti server aggiungendo la parola chiave [JSONBODY] seguita da un oggetto formattato JSON. Exampon:
PUT:https://server.com/event[JSONBODY]{"location":"%NAME%","event":"%EID%"}
IL URL supporta l'indirizzo IP tipico (e IPv6) e le opzioni di porta e password utente, oppure puoi utilizzare i campi Utente e Password, se necessario, come server di destinazione per metodi di autenticazione come Basic o Digest:
https://username:password@123.321.123.321:9876/event…
Modalità TCP
Le stringhe di messaggistica esterna e Heartbeat sono solo per i dati poiché i campi Indirizzo e Porta specificano la destinazione. L'indirizzo supporta nomi, IPv4 e IPv6.
La stringa può essere formattata come le porzioni di dati dei messaggi HTTP descritti sopra o come richiesto dal server di destinazione.
Exampi file per la messaggistica esterna includerebbero %EID% per indicare l'evento che ha attivato:
posizione=%NAME%,evento=%EID%
{“località”:”:%NAME%”,”evento”:”%EID%”}
Exampi le per Heartbeat potrebbero aggiungere %ACTIVE% (eventi attualmente attivati) o un valore del sensore:
posizione=%NAME%&Triggered=%ATTIVO%
{“posizione”:”:%NOME%”,”NH3”:%SENSORE:NH3%}
Le caselle di controllo nelle colonne "Set integrazione" e "Reimpostazione integrazione" determinano quali eventi attivano l'invio. Maggiori informazioni sull'impostazione di eventi e azioni sono disponibili nella Guida dell'amministratore di HALO.
Consegna di messaggi di eventi JSON
Alcuni sviluppatori preferiscono ricevere i dati degli eventi formattati come JSON autoetichettato standard del settore piuttosto che un semplice testo ASCII poiché il primo è più affidabile e più facile da analizzare. Su HALO web nella scheda "Messaggistica", puoi fornire messaggi JSON nelle impostazioni "Messaggistica esterna" "Imposta stringa" e "Reimposta stringa" e nel "Messaggio" "Heartbeat".
Examples:
Impostazioni "Messaggistica esterna" Imposta stringa:
{ “dispositivo”:”%NAME%”, “evento”:”%EID%”, “allarme”:”sì” }
Questo invierà un singolo messaggio JSON TCP o UDP al server specificato riportando il nome del dispositivo descrittivo, il nome dell'evento e che è appena iniziato.
Impostazioni "Messaggistica esterna" Ripristina stringa:
{ “dispositivo”:”%NAME%”, “evento”:”%EID%”, “allarme”:”no” }
Questo invierà un singolo messaggio JSON TCP o UDP al server specificato riportando il nome del dispositivo descrittivo, il nome dell'evento e che la condizione è stata interrotta.
Messaggio "battito cardiaco":
{ “dispositivo”:”%NAME%”, “vivo”:”%DATE% %TIME%” }
Questo invierà periodicamente un messaggio JSON TCP o UDP al server specificato segnalando che HALO è attivo all'ora indicata.
Documenti / Risorse
 |
Software Software di base dell'API HALO Smart Sensor [pdf] Guida utente Software di base dell'API HALO Smart Sensor |
