Softvér Základný softvér HALO Smart Sensor API
Vpred
Tento dokument popisuje skupinu zariadení Halo Smart Sensora, ktoré sú spoločne známe ako BASIC API alebo aplikačné programové rozhranie. Táto diskusia je určená pre programátorov alebo integrátorov, ktorí majú záujem o integráciu jedného alebo viacerých inteligentných senzorov HALO (HALO) so softvérovými komponentmi alebo systémami tretích strán (nie IPVideo). Vo všeobecnosti je HALO API určené na efektívny prenos informácií z HALO cez konvenčnú ethernetovú sieť do externého programu. Na dosiahnutie tohto cieľa je rozhranie API rozdelené do troch sekcií: Pripojenie soketu riadeného udalosťou, Pripojenie soketu Heartbeat a Údaje udalostí. URL. Rozhranie BACnet je tiež prítomné a popísané v samostatnom dokumente.
Dizajn API
API je navrhnuté pomocou štandardných priemyselných formátov, ako je TCP/IP. HTTP, HTTPS a JSON. Dizajn nevyžaduje žiadne špeciálne alebo proprietárne techniky alebo knižnice, ktoré sa majú použiť pri vývoji externého programu alebo aplikácie. Rozhranie API je flexibilné a možno ho nakonfigurovať a naprogramovať tak, aby poskytovalo presne požadované údaje a čo najefektívnejším spôsobom. Podrobnosti o prevádzke každej z vyššie uvedených častí sú uvedené v nasledujúcich častiach tejto príručky.
Externé správy
Toto zariadenie sa používa na doručovanie výstrah alebo alarmov a údajov o udalostiach do externého programu, systému VMS, servera atď., keď sa spustí (je nastavená) Udalosť. Voliteľné správy môžu byť tiež povolené na signalizáciu, keď sa udalosť vymaže (resetuje). Toto doručenie môže byť uskutočnené na TCP/IP socket alebo HTTP/S server v reálnom čase. Existuje celý rad konfigurovateľných protokolov s prispôsobiteľným obsahom. K dispozícii je autentifikácia a šifrovanie.
Tlkot srdca
Správy srdcového tepu sa odosielajú v konfigurovateľnom intervale (namiesto spustenia udalostí), aby poskytli dôkaz o aktuálnosti/dostupnosti. Majú podobný rozsah možností ako externé správy, ale zvyčajne by boli nakonfigurované tak, aby obsahovali všeobecné informácie o stave a nie podrobnosti o konkrétnej udalosti.
Údaje o udalosti URL
Táto funkcia je k dispozícii iba v rámci NDA a mala by sa používať len vtedy, keď externý program vyžaduje prístup ku všetkým hodnotám udalostí, prahom a príznakom stavu. Tieto údaje sa vo všeobecnosti získavajú na požiadanie externým programom, ale nie s veľmi vysokou frekvenciou. Táto metóda vo všeobecnosti spôsobuje určitú latenciu, keď sa používa mierna rýchlosť dotazovania. Typické rýchlosti dotazovania sa pohybujú od raz za minútu až raz za 5 sekúnd s absolútnou maximálnou rýchlosťou raz za sekundu. Túto metódu možno použiť aj na získanie ďalších podporných údajov pri prijatí udalosti (výstrahy).
Podrobnosti o externých správach
Časť HALO web interface Integration popup poskytuje konfiguráciu jedného pripojenia tretej strany, kde je možné posielať rôzne hodnoty na vzdialený TCP socket alebo HTTP/HTTPS server. Zástupné symboly (tokeny) slúžia na vkladanie živých hodnôt do prenášaného textu. Aj keď je tento kanál označený ako „External Messaging“, môže byť použitý takmer na akýkoľvek účel vyžadujúci spúšťače udalostí v reálnom čase, ktoré aktívne poskytuje HALO. Toto usporiadanie je dosť flexibilné, pretože výber na „Akciách“ určuje, ktoré HALO udalosti sa prenášajú cez tento kanál.
V režime HTTP sú reťazce Set a Reset URLs, ktoré je potrebné zadať a naformátovať podľa požiadaviek požadovaného cieľového servera. Na overenie možno použiť pole Používateľ a heslo. Pozrite si režim HTTP nižšie.
V režime TCP sú reťazce Set a Reset iba údajmi jednej správy, ktorá sa odošle do prijímajúceho soketu TCP. Môžu byť naformátované podľa potreby podľa cieľa. Cieľ je zadaný v poliach Adresa a Port. Pozrite si režim TCP nižšie.
V oboch režimoch sa zobrazí stav z najnovšej správy, čo môže pomôcť pri oprave pripojenia alebo iných problémov. Na vynútenie správy môžete použiť tlačidlá TEST udalostí vo vyskakovacom okne Akcie:
Globálne zapnutie/vypnutie pre nastavenie alebo resetovanie musí byť zapnuté, aby sa povolili tieto typy správ. Resetovanie sa často nepoužíva, pretože zaujímavý je iba začiatok udalosti, ale to sa môže líšiť. Každá udalosť môže nezávisle určiť, či použije buď správu Set alebo Reset vo vyskakovacom okne Actions. Tlačidlá očnej gule zobrazia približnú reprezentáciu toho, čo sa odošle po nahradení kľúčových slov a formátovaní. Repeat Holdoff možno použiť na obmedzenie častých správ oneskorením pred odoslaním ďalšej. Toto sa vykonáva nezávisle na udalosti. HALO má zabudovaný čas zdržania pre udalosti 15 sekúnd, aby sa zabránilo rýchlemu opätovnému spusteniu udalostí. Ak chcete zabezpečiť, aby sa za minútu neodoslala viac ako 1 udalosť určitého typu, môžete nastaviť Repeat Holdoff na 60 (sekúnd).
Podrobnosti srdcového tepu
Prenosy Heartbeat fungujú podobným spôsobom ako vyššie s tým rozdielom, že nedochádza k interakcii so stránkou Actions. Namiesto toho sa prenos Heartbeat vyskytuje pravidelne, ako je nakonfigurované v poli Interval. V režime HTTP sú reťazce Set a Reset URLs, ktoré je potrebné zadať a naformátovať podľa požiadaviek požadovaného cieľového servera. Na overenie možno použiť pole Používateľ a heslo. Pozrite si režim HTTP nižšie.
Zatiaľ čo primárnym účelom Heartbeat je poskytnúť dôkaz o životnosti HALO Smart Sensor vzdialenej aplikácii, túto správu možno použiť aj na prenos vybraných senzorov alebo informácií o aktuálnom stave udalosti. Bývalýample vyššie odošle parameter dlhého reťazca s URL ktoré zahŕňajú názov Halo, väčšinu hodnôt senzora a nakoniec Spustené=%AKTÍVNE%, čo môže byť prázdne alebo zoznam aktuálne spustených udalostí.
Režim HTTP (a HTTPS).
Reťazce Externé správy a Heartbeat môžu byť http: alebo https: URLs podľa potreby. Cestu a parametre je možné zadať podľa potreby cieľového servera. Kľúčové slová ako %NAME% (názov zariadenia HALO) alebo %EID% (ID udalosti) možno vložiť podľa potreby a pri odoslaní správy budú nahradené príslušnými údajmi. Pre rýchlu orientáciu je zobrazený zoznam bežne používaných kľúčových slov.
The URL cesta môže obsahovať kľúčové slová, ako aj parametre k URL. Parametrami môžu byť páry NAME=VALUE alebo objekt JSON alebo vlastný formát v závislosti od cieľového servera. Naprampsúbory pre externé správy budú zahŕňať %EID% na označenie udalosti, ktorá spustila:
- https://server.com/event/%NAME%/%EID%
- https://server.com/event?location=%NAME%&event=%EID%
- https://server.com/event?{“location”:”:%NAME%”,”event”:”%EID%”}
Examplesy pre Heartbeat môžu pridať %ACTIVE% (aktuálne spustené udalosti) alebo hodnotu senzora:
- https://server.com/alive?location=%NAME%&Triggered=%ACTIVE%
- https://server.com/event?{“location”:”:%NAME%”,”NH3”:%SENSOR:NH3%}
Hodnoty %SENSOR:…% používajú názvy uvedené v hlavičkách stĺpcov pravého senzora v denníku evtRRRRMMDD.csv files. Zvyčajne sú:
Ak cieľový server uprednostňuje HTTP PUT alebo POST namiesto požiadaviek GET, môžete predponu URL s PUT: alebo POST:. Nezávisle môžete pridať užitočné zaťaženie JSON, ktoré je obľúbené na mnohých serveroch, pridaním kľúčového slova [JSONBODY], za ktorým nasleduje objekt vo formáte JSON. Naprample:
PUT:https://server.com/event[JSONBODY]{“location“:”%NAME%”,”event”:”%EID%”}
The URL podporuje typickú IP adresu (a IPv6) a možnosti portu a používateľského hesla, prípadne môžete použiť polia Používateľ a Heslo, ak je to potrebné, ako cieľový server pre metódy autentifikácie, ako je Basic alebo Digest:
https://username:password@123.321.123.321:9876/event…
Režim TCP
Reťazce External Messaging a Heartbeat sú len pre dáta, pretože polia Address a Port špecifikujú cieľ. Adresa podporuje názvy, IPv4 a IPv6.
Reťazec môže byť naformátovaný ako dátové časti správ HTTP popísané vyššie alebo ako to vyžaduje cieľový server.
Exampsúbory pre externé správy budú zahŕňať %EID% na označenie udalosti, ktorá spustila:
location=%NAME%,event=%EID%
{“location“:”:%NAME%”,”event”:”%EID%”}
Examplesy pre Heartbeat môžu pridať %ACTIVE% (aktuálne spustené udalosti) alebo hodnotu senzora:
location=%NAME%&Triggered=%ACTIVE%
{“location“:”:%NAME%”,”NH3”:%SENSOR:NH3%}
Začiarkavacie políčka v stĺpcoch „Integration Set“ a „Integration Reset“ určujú, ktoré udalosti spúšťajú odosielanie. Viac o nastavení udalostí a akcií je k dispozícii v príručke správcu HALO.
Doručovanie správ udalostí JSON
Niektorí vývojári uprednostňujú prijímanie údajov o udalostiach vo formáte odvetvového štandardu s vlastným označením JSON pred obyčajným textom ASCII, pretože prvý je spoľahlivejšie a ľahšie analyzovaný. Na HALO web na karte „Správy“ môžete dodávať správy JSON v nastaveniach „Externé správy“ „Nastaviť reťazec“ a „Obnoviť reťazec“ a v časti „Srdce“ „Správa“.
Examples:
Nastavenia „Externé správy“ Nastaviť reťazec:
{ “device”:”%NAME%”, “event”:”%EID%”, “alarm”:”yes” }
Toto odošle jedinú správu TCP alebo UDP JSON na zadaný server s informáciou o priateľskom názve zariadenia, názve udalosti a o tom, že sa práve začala.
Nastavenia „Externé správy“ Resetovať reťazec:
{ “zariadenie”:”%NAME%”, “udalosť”:”%EID%”, “alarm”:”nie” }
Toto odošle jedinú správu TCP alebo UDP JSON na zadaný server, v ktorom bude uvedený priateľský názov zariadenia, názov udalosti a že stav sa teraz zastavil.
Správa „Tlukot srdca“:
{ “zariadenie”:”%NAME%”, “nažive”:”%DATE% %TIME%” }
Toto bude pravidelne odosielať správu TCP alebo UDP JSON určenému serveru, ktorá oznamuje, že HALO je v uvedenom čase nažive.
Dokumenty / zdroje
 |
Softvér Základný softvér HALO Smart Sensor API [pdf] Používateľská príručka Základný softvér HALO Smart Sensor API |
