Programari HALO Smart Sensor API Programari bàsic
Endavant
Aquest document descriu el grup d'instal·lacions del sensor intel·ligent Halo conegudes col·lectivament com a API BASIC, o interfície de programació d'aplicacions. Aquesta discussió està pensada per a programadors o integradors que estiguin interessats a integrar un o més sensors intel·ligents HALO (HALO) amb components o sistemes de programari de tercers (no IPVideo). En general, l'API HALO està pensada per transferir informació de manera eficient des d'HALO a través d'una xarxa Ethernet convencional al programa extern. Per assolir aquest objectiu, l'API es divideix en tres seccions: Connexió de socket impulsada per esdeveniments, Connexió de socket Heartbeat i Dades d'esdeveniments. URL. La interfície BACnet també està present i es tracta en un document separat.
Disseny API
L'API està dissenyada utilitzant formats estàndard de la indústria com ara TCP/IP. HTTP, HTTPS i JSON. El disseny no requereix que s'utilitzi cap tècnica o biblioteca especial o propietaria en el desenvolupament del programa o aplicació externa. L'API és flexible i es pot configurar i programar per oferir exactament les dades necessàries i de la manera més eficient. Els detalls del funcionament de cadascuna de les seccions anteriors es tracten a les seccions següents d'aquesta guia.
Missatgeria externa
Aquesta instal·lació s'utilitza per enviar alertes o alarmes i dades d'esdeveniment a un programa extern, sistema VMS, servidor, etc. quan s'activa (està configurat) un esdeveniment. Els missatges opcionals també es poden activar per indicar quan s'esborra un esdeveniment (es restableix). Aquest lliurament es pot fer a un sòcol TCP/IP o un servidor HTTP/S en temps real. Hi ha una varietat de protocols configurables amb continguts personalitzables. L'autenticació i el xifratge estan disponibles.
Batec del cor
Els missatges de batec del cor s'envien a un interval configurable (en lloc de quan s'activen els esdeveniments) per proporcionar una prova de la disponibilitat/de la disponibilitat. Tenen una gamma de capacitats similar a la de missatgeria externa, però normalment es configurarien per contenir informació general de l'estat en lloc de detalls sobre un esdeveniment concret.
Dades d'esdeveniments URL
Aquesta instal·lació només està disponible sota una NDA i només s'ha d'utilitzar quan el programa extern requereix accés a tots els valors, llindars i senyals d'estat d'esdeveniments. Aquestes dades generalment són recuperades sota demanda pel programa extern, però no amb una freqüència molt alta. Aquest mètode generalment incorre en una certa latència quan s'utilitza una taxa d'enquesta modesta. Les taxes d'enquesta típiques oscil·len entre una vegada per minut i una per cada 5 segons, amb una velocitat màxima absoluta d'una vegada per segon. Aquest mètode també es pot utilitzar per recuperar dades de suport addicionals quan es rep un esdeveniment (alerta).
Detalls de missatgeria externa
Una secció de l'HALO web La finestra emergent d'integració de la interfície ofereix la configuració d'una única connexió de tercers on es poden enviar diversos valors a un sòcol TCP remot o a un servidor HTTP/HTTPS. Els marcadors de posició (fitxes) s'utilitzen per inserir valors en directe al text transmès. Tot i que està etiquetat com a "Missatgeria externa", aquest canal es pot utilitzar per a gairebé qualsevol propòsit que requereixi activadors d'esdeveniments en temps real, lliurats activament per HALO. Aquesta disposició és bastant flexible perquè les seleccions a les "Accions" determinen quins esdeveniments HALO transmeten a través d'aquest canal.
En el mode HTTP, les cadenes Establir i Restablir són URLs que s'han d'introduir i formatar segons ho requereixi el servidor de destinació desitjat. Es pot utilitzar un camp Usuari i Contrasenya per a l'autenticació. Vegeu el mode HTTP a continuació.
En el mode TCP, les cadenes Set i Reset són només les dades d'un sol missatge que s'envia al sòcol TCP receptor. Es poden formatar segons les necessitats de la destinació. La destinació s'especifica als camps Adreça i Port. Vegeu el mode TCP a continuació.
Per a qualsevol dels dos modes, es mostra l'estat del missatge més recent que pot ajudar a solucionar problemes de connexió o altres. Podeu utilitzar els botons TEST d'esdeveniments a la finestra emergent Accions per forçar un missatge:
L'activació/desactivació global per establir o restablir ha d'estar activada per habilitar aquest tipus de missatges. Sovint, el restabliment no s'utilitza perquè només interessa l'inici d'un esdeveniment, però això pot variar. Cada esdeveniment pot especificar de manera independent si utilitzarà el missatge Establir o Restablir a la finestra emergent Accions. Els botons del globus ocular mostraran una representació aproximada del que s'envia després de les substitucions i el format de paraules clau. Es pot utilitzar Repeat Holdoff per accelerar els missatges freqüents retardant-se abans que se'n pugui enviar un altre. Això es fa de manera independent per esdeveniment. HALO té un temps de retenció integrat per a esdeveniments de 15 segons per evitar que es tornin a disparar ràpidament. Si voleu assegurar-vos que no s'enviï més d'1 esdeveniment d'un tipus per minut, podeu establir Repetició de retenció a 60 (segons).
Detalls del batec del cor
Les transmissions Heartbeat funcionen de manera similar a l'anterior, excepte que no hi ha interacció amb la pàgina Accions. En comptes d'això, la transmissió de batecs cardíacs es produeix de manera regular tal com es configura amb el camp Interval. En mode HTTP, les cadenes Establir i Restablir són les URLs que s'han d'introduir i formatar segons ho requereixi el servidor de destinació desitjat. Es pot utilitzar un camp Usuari i Contrasenya per a l'autenticació. Vegeu el mode HTTP a continuació.
Tot i que l'objectiu principal de Heartbeat és proporcionar una prova de vida d'un sensor intel·ligent HALO a una aplicació remota, aquest missatge també es pot utilitzar per transmetre els sensors seleccionats o la informació de l'estat de l'esdeveniment actual. L'exampel fitxer anterior envia un paràmetre de cadena llarga amb el URL que inclouen el nom de Halo, la majoria dels valors del sensor i, finalment, Triggered=%ACTIVE% que podria estar buit o una llista d'esdeveniments activats actualment.
Mode HTTP (i HTTPS).
Les cadenes de missatgeria externa i Heartbeat poden ser http: o https: URLs segons sigui necessari. El servidor de destinació pot introduir el camí i els paràmetres segons ho necessiti. Les paraules clau com %NAME% (nom del dispositiu HALO) o %EID% (identificador d'esdeveniment) es poden inserir segons sigui necessari i es substituiran per les dades corresponents quan s'enviï el missatge. Es mostra una llista de paraules clau d'ús habitual per a una referència ràpida.
El URL path pot contenir paraules clau així com els paràmetres del URL. Els paràmetres poden ser parells NAME=VALUE o un objecte JSON, o un format personalitzat en funció del servidor de destinació. ExampEls fitxers de missatgeria externa inclourien %EID% per indicar l'esdeveniment que s'ha activat:
- https://server.com/event/%NAME%/%EID%
- https://server.com/event?location=%NAME%&event=%EID%
- https://server.com/event?{“location”:”:%NAME%”,”event”:”%EID%”}
ExampEls fitxers de Heartbeat poden afegir %ACTIVE% (esdeveniments activats actualment) o un valor de sensor:
- https://server.com/alive?location=%NAME%&Triggered=%ACTIVE%
- https://server.com/event?{“location”:”:%NAME%”,”NH3”:%SENSOR:NH3%}
Els valors %SENSOR:...% utilitzen els noms que es troben als encapçalaments de columna del sensor de la dreta al registre evtYYYYMMDD.csv files. Normalment són:
Si el servidor de destinació prefereix HTTP PUT o POST en lloc de sol·licituds GET, podeu prefixar el URL amb PUT: o POST:. De manera independent, podeu afegir una càrrega útil JSON que sigui popular entre molts servidors afegint la paraula clau [JSONBODY] seguida d'un objecte amb format JSON. ExampLI:
PUT:https://server.com/event[JSONBODY]{“location”:”%NAME%”,”event”:”%EID%”}
El URL Admet l'adreça IP típica (i IPv6) i les opcions de port i contrasenya d'usuari, o podeu utilitzar els camps Usuari i Contrasenya si cal ser el servidor de destinació per a mètodes d'autenticació com Basic o Digest:
https://username:password@123.321.123.321:9876/event…
Mode TCP
Les cadenes de missatgeria externa i Heartbeat són només per a dades, ja que els camps Adreça i Port especifiquen la destinació. L'adreça admet noms, IPv4 i IPv6.
La cadena es pot formatar com les parts de dades dels missatges HTTP descrites anteriorment, o segons ho requereixi el servidor de destinació.
ExampEls fitxers de missatgeria externa inclourien %EID% per indicar l'esdeveniment que s'ha activat:
ubicació=%NAME%, esdeveniment=%EID%
{“location”:”:%NAME%”,”event”:”%EID%”}
ExampEls fitxers de Heartbeat poden afegir %ACTIVE% (esdeveniments activats actualment) o un valor de sensor:
ubicació=%NAME%&Activada=%ACTIVE%
{“location”:”:%NAME%”,”NH3”:%SENSOR:NH3%}
Les caselles de selecció de les columnes "Conjunt d'integració" i "Restabliment d'integració" determinen quins esdeveniments desencadenen l'enviament. Trobareu més informació sobre la configuració d'esdeveniments i accions a la Guia de l'administrador d'HALO.
Lliurament de missatges d'esdeveniment JSON
Alguns desenvolupadors prefereixen rebre dades d'esdeveniments amb format JSON autoetiquetat estàndard de la indústria en lloc de text ASCII senzill, ja que el primer s'analitza de manera més fiable i fàcil. A l'HALO web a la pestanya "Missatgeria", podeu proporcionar missatges JSON a la configuració de "Missatgeria externa" "Estableix la cadena" i "Restableix la cadena" i al "Missatatge" de "Batec del cor".
Examples:
Configuració de "Missatgeria externa" Configura la cadena:
{ “dispositiu”:”%NAME%”, “esdeveniment”:”%EID%”, “alarma”:”sí” }
Això enviarà un únic missatge TCP o UDP JSON al servidor especificat informant del nom del dispositiu amigable, el nom de l'esdeveniment i que s'acaba d'iniciar.
Cadena de restabliment de la configuració de "Missatgeria externa":
{ “dispositiu”:”%NAME%”, “esdeveniment”:”%EID%”, “alarma”:”no” }
Això enviarà un únic missatge TCP o UDP JSON al servidor especificat informant del nom del dispositiu amigable, el nom de l'esdeveniment i que la condició s'ha aturat.
Missatge "Bateig del cor":
{ “device”:”%NAME%”, “alive”:”%DATE% %TIME%” }
Això enviarà periòdicament un missatge JSON TCP o UDP al servidor especificat informant que l'HALO està viu a l'hora indicada.
Documents/Recursos
 |
Programari HALO Smart Sensor API Programari bàsic [pdfGuia de l'usuari Programari bàsic HALO Smart Sensor API |
