U software di u software HALO Smart Sensor API Basic Software
Avanti
Stu documentu descrive u gruppu di facilità di u Halo Smart Sensor cunnisciutu cullettivamente cum'è l'API BASIC, o l'interfaccia di prugrammazione di l'applicazioni. Questa discussione hè destinata à l'usu da i programatori o integratori chì anu interessatu à integrà unu o più HALO Smart Sensors (HALO) cù cumpunenti o sistemi di software di terzu parti (non-IPVideo). In generale, l'API HALO hè destinata à trasfiriri l'infurmazioni in modu efficiente da HALO nantu à una rete Ethernet convenzionale à u prugramma esternu. Per rializà stu scopu, l'API hè divisa in trè sezioni: Cunnessione Socket Driven Eventu, Cunnessione Socket Heartbeat, è Dati Event. URL. L'interfaccia BACnet hè ancu presente è coperta in un documentu separatu.
Design API
L'API hè cuncepitu cù formati standard di l'industria cum'è TCP / IP. HTTP, HTTPS è JSON. U disignu ùn hà micca bisognu di tecniche o biblioteche speciali o privati per esse aduprate in u sviluppu di u prugramma o applicazione esterni. L'API hè flessibile è pò esse cunfigurata è programata per furnisce esattamente i dati necessarii è in u modu più efficiente. I ditaglii di u funziunamentu di ognuna di e rùbbriche sopra sò cuparti in e seguenti sezzioni di sta guida.
Messageria Esterna
Questa facilità hè aduprata per trasmette avvisi o allarmi è dati di l'Evenimentu à un prugramma esternu, sistema VMS, servitore, etc. quandu un Avvenimentu hè attivatu (hè stabilitu). I missaghji opzionali ponu ancu esse attivati per signalà quandu un Eventu sguassate (hè resettatu). Questa consegna pò esse fatta à un socket TCP / IP o un servitore HTTP / S in tempu reale. Ci hè una gamma di protokolli configurabili cù cuntenutu persunalizabile. L'autentificazione è a criptografia sò dispunibili.
Battitu di core
I missaghji Heartbeat sò mandati à un intervallu configurabile (invece di quandu l'Eventi sò attivati) per furnisce una prova di live / dispunibilità. Hanu una gamma simile di capacità cum'è a Messaging Esternu, ma sò tipicamente cunfigurati per cuntene infurmazione generale di u statu piuttostu cà i dettagli nantu à un avvenimentu particulare.
Dati Event URL
Questa facilità hè solu dispunibile sottu un NDA è deve esse aduprata solu quandu u prugramma esternu richiede l'accessu à tutti i valori di l'eventi, i soglia è i bandieri statali. Queste dati sò generalmente recuperati nantu à a dumanda da u prugramma esternu, ma micca à una freccia assai alta. Stu metudu generalmente incorre una certa latenza quandu si usa una modesta rata di votazione. I tassi di votazione tipici varienu da una volta per minutu à una volta per 5 seconde cù una tarifa massima assoluta di una volta per seconda. Stu metudu pò ancu esse usatu per ricuperà dati di supportu supplementari quandu un Eventu (alerta) hè ricevutu.
Detaglii di i missaghji esterni
Una sezione di l'HALO web U popup di integrazione di l'interfaccia prevede a cunfigurazione di una sola cunnessione di terzu partitu induve parechji valori ponu esse mandati à un socket TCP remoto o un servitore HTTP / HTTPS. I posti (tokens) sò usati per inserisce valori in diretta in u testu trasmessu. Ancu s'ellu hè marcatu "Messaggiamentu Esternu", stu canale pò esse usatu per quasi ogni scopu chì richiede attivatori di Eventi in tempu reale, attivamente consegnati da HALO. Stu arrangiamentu hè abbastanza flessibile perchè e selezioni nantu à l'"Azioni" determinanu quale Eventi HALO trasmettenu attraversu stu canale.
In u modu HTTP, i Strings Set and Reset sò i URLs chì deve esse inseritu è furmatu cum'è necessariu da u servitore di destinazione desideratu. Un campu User è Password pò esse usatu per l'autentificazione. Vede u modu HTTP sottu.
In u modu TCP, u Set and Reset Strings sò solu i dati di un missaghju unicu chì hè mandatu à u socket TCP di ricivutu. Puderanu esse furmatu cum'è necessariu da u destinazione. A destinazione hè specificata in i campi Indirizzu è Port. Vede u Modu TCP quì sottu.
Per ogni modu, u statutu da u messagiu più recente hè visualizatu chì pò aiutà à risolve a cunnessione o altre prublemi. Puderete aduprà i buttoni TEST di Eventu nantu à u popup Actions per furzà un missaghju:
Global On/Off per Set o Reset deve esse On per attivà quelli tipi di messagi. Reset ùn hè spessu usatu perchè solu l'iniziu di un Eventu hè di interessu, ma chì pò varià. Ogni Avvenimentu pò indipindendu indipindentamente s'ellu utilizerà u messagiu Set o Reset in u popup Azioni. I buttuni di u globu oculare mostraranu una rapprisintazioni approssimativa di ciò chì hè mandatu dopu à sustituzzioni di keyword è furmatu. Repeat Holdoff pò esse usatu per throttle i missaghji frequenti ritardandu prima chì un altru pò esse mandatu. Questu hè fattu indipindentamente per Eventu. HALO hà un tempu di mantenimentu integratu per l'avvenimenti di 15 seconde per prevene a riattivazione rapida di l'Eventi. Se vulete assicurà micca più di 1 Eventu di un tipu hè mandatu per minutu, pudete stabilisce Repeat Holdoff à 60 (secondi).
Dettagli di u battitu di u core
I trasmissioni Heartbeat funzionanu in modu simili à quelli sopra, salvu chì ùn ci hè micca interazzione cù a pagina Azioni. Invece, a trasmissione Heartbeat si trova in una basa regulare cum'è cunfigurata cù u campu Interval, In u modu HTTP, u Set è Reset Strings sò i URLs chì deve esse inseritu è furmatu cum'è necessariu da u servitore di destinazione desideratu. Un campu User è Password pò esse usatu per l'autentificazione. Vede u modu HTTP sottu.
Mentre chì u scopu primariu di u Heartbeat hè di furnisce una prova di vita di un HALO Smart Sensor à una applicazione remota, stu missaghju pò ancu esse usatu per trasmette sensori selezziunati o infurmazione attuale di u Statu Event. L'example sopra manda un paràmetru di stringa longa cù u URL chì includenu u nome Halo, a maiuranza di i valori di sensori, è infine Triggered=%ACTIVE% chì puderia esse viotu o una lista di Eventi attualmente attivati.
Modu HTTP (è HTTPS).
E stringhe di messageria esterna è Heartbeat ponu esse http: o https: URLs quantu bisognu. U percorsu è i paràmetri ponu esse inseriti cumu necessariu da u servitore di destinazione. Parolle chjave cum'è %NAME% (nome di u dispositivu HALO) o %EID% (Event id) ponu esse inserite cum'è necessariu è seranu rimpiazzate cù dati rispettivi quandu u messagiu hè mandatu. Una lista di e parolle chjave cumunimenti usate hè mostrata per riferimentu rapidu.
U URL a strada pò cuntene e parolle chjave è ancu i paràmetri à u URL. I paràmetri puderanu esse NAME = VALUE coppie o un ughjettu JSON, o un furmatu persunalizatu secondu u servitore di destinazione. Esampi le per a Messageria Esterna includenu %EID% per indicà l'Evenimentu chì hà attivatu:
- 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 puderanu aghjunghje %ACTIVE% (eventi attivati attualmente) o un valore di sensore:
- https://server.com/alive?location=%NAME%&Triggered=%ACTIVE%
- https://server.com/event?{“location”:”:%NAME%”,”NH3”:%SENSOR:NH3%}
I valori %SENSOR:...% usanu i nomi truvati in l'intestazione di a colonna di u sensoru di a diritta in u log evtYYYYMMDD.csv files. Sò tipicamente:
Se u servitore di destinazione preferisce HTTP PUT o POST invece di richieste GET, pudete prefissà u URL cù PUT: o POST:. Indipendentemente, pudete aghjunghje una carica JSON chì hè populari cù parechji servitori aghjunghjendu a chjave [JSONBODY] seguita da un oggettu furmatu JSON. EsampLe:
PUT:https://server.com/event[JSONBODY]{"location":"%NAME%","event":"%EID%"}
U URL supporta l'indirizzu IP tipicu (è IPv6) è l'opzioni di portu è password d'utilizatore, o pudete aduprà i campi User è Password se necessariu esse u servitore di destinazione per metudi di autentificazione cum'è Basic o Digest:
https://username:password@123.321.123.321:9876/event…
Modu TCP
E stringhe di messageria esterna è Heartbeat sò solu per i dati postu chì i campi Indirizzu è Port specificanu a destinazione. L'indirizzu supporta i nomi, IPv4 è IPv6.
A stringa pò esse furmatu cum'è e porzioni di dati di i missaghji HTTP descritti sopra, o cum'è necessariu da u servitore di destinazione.
Exampi le per a Messageria Esterna includenu %EID% per indicà l'Evenimentu chì hà attivatu:
locu=%NAME%, event=%EID%
{“location”:”:%NAME%”,”event”:”%EID%”}
Exampi le per Heartbeat puderanu aghjunghje %ACTIVE% (eventi attivati attualmente) o un valore di sensore:
location=%NAME%&Triggered=%ACTIVE%
{“location”:”:%NAME%”,”NH3”:%SENSOR:NH3%}
I checkboxes in e colonne "Integrazione Set" è "Integrazione Reset" determinanu quale Avvenimenti attivanu l'invio. Più nantu à a cunfigurazione di Eventi è Azioni hè dispunibule in a Guida di l'Amministratore HALO.
Consegna di Missaghji di Event JSON
Certi sviluppatori preferanu riceve i dati di l'eventi furmatu cum'è JSON auto-etichettatu standard di l'industria piuttostu cà u testu ASCII chjaru postu chì u primu hè più affidabile è più facilmente analizatu. À u HALO web pagina "Messaging", pudete furnisce i missaghji JSON in i paràmetri di "Messaging Estern" "Set String" è "Reset String" è in u "Heartbeat" "Message".
Examples:
Impostazioni di "Messaging Esterni" Set String:
{"dispositivu":"%NAME%", "event":"%EID%", "alarm":"iè"}
Questu mandarà un missaghju unicu TCP o UDP JSON à u servitore specificatu chì informa u nome di u dispositivu amichevule, u nome di l'avvenimentu è chì hè ghjustu cuminciatu.
Impostazioni "Messaging Esterni" Reset String:
{"dispositivu":"%NAME%", "event":"%EID%", "alarm":"no" }
Questu mandarà un missaghju unicu TCP o UDP JSON à u servitore specificatu chì informa u nome di u dispositivu amichevule, u nome di l'avvenimentu è chì a cundizione hè stata fermata.
Messaghju "Heartbeat":
{ "device":"%NAME%", "alive":"%DATE% %TIME%" }
Questu mandarà periodicamente un missaghju TCP o UDP JSON à u servitore specificatu chì informa chì l'HALO hè vivu à u tempu indicatu.
Documenti / Risorse
 |
U software di u software HALO Smart Sensor API Basic Software [pdfGuida di l'utente HALO Smart Sensor API Software Basic |
