Software Základní software HALO Smart Sensor API
Vpřed
Tento dokument popisuje skupinu zařízení Halo Smart Sensor, která je souhrnně známá jako BASIC API neboli aplikační programovací rozhraní. Tato diskuse je určena pro použití programátory nebo integrátory, kteří mají zájem o integraci jednoho nebo více inteligentních senzorů HALO (HALO) se softwarovými komponentami nebo systémy třetích stran (bez IP videa). Obecně je HALO API určeno k efektivnímu přenosu informací z HALO přes konvenční ethernetovou síť do externího programu. K dosažení tohoto cíle je API rozděleno do tří sekcí: Event Driven Socket Connection, Heartbeat Socket Connection a Event Data. URL. Rozhraní BACnet je také přítomno a je popsáno v samostatném dokumentu.
Návrh API
Rozhraní API je navrženo pomocí standardních průmyslových formátů, jako je TCP/IP. HTTP, HTTPS a JSON. Návrh nevyžaduje žádné speciální nebo proprietární techniky nebo knihovny pro použití při vývoji externího programu nebo aplikace. API je flexibilní a lze jej nakonfigurovat a naprogramovat tak, aby poskytovalo přesně požadovaná data a tím nejefektivnějším způsobem. Podrobnosti o ovládání každé z výše uvedených částí jsou popsány v následujících částech této příručky.
Externí zasílání zpráv
Tato funkce se používá k doručování výstrah nebo poplachů a dat o událostech do externího programu, systému VMS, serveru atd., když je událost spuštěna (je nastavena). Volitelné zprávy mohou být také povoleny pro signalizaci, když se událost vymaže (je resetována). Toto doručení lze provést na TCP/IP soket nebo HTTP/S server v reálném čase. Existuje řada konfigurovatelných protokolů s přizpůsobitelným obsahem. K dispozici je ověřování a šifrování.
Tlukot srdce
Zprávy prezenčního signálu se odesílají v konfigurovatelném intervalu (namísto toho, kdy jsou spuštěny Události), aby poskytly důkaz o aktuálním stavu/dostupnosti. Mají podobný rozsah možností jako External Messaging, ale obvykle by byly nakonfigurovány tak, aby obsahovaly obecné informace o stavu spíše než podrobnosti o konkrétní události.
Data události URL
Tato funkce je k dispozici pouze v rámci NDA a měla by být použita pouze v případě, že externí program vyžaduje přístup ke všem hodnotám událostí, prahovým hodnotám a příznakům stavu. Tato data jsou obecně získávána na vyžádání externím programem, ale ne s příliš vysokou frekvencí. Tato metoda obecně vyvolává určitou latenci, když se používá mírná rychlost dotazování. Typické rychlosti dotazování se pohybují od jedné za minutu do jednou za 5 sekund s absolutní maximální rychlostí jednou za sekundu. Tuto metodu lze také použít k načtení dalších podpůrných dat, když je přijata událost (výstraha).
Podrobnosti o externích zprávách
Část HALO web interface Integration popup umožňuje konfiguraci jediného připojení třetí strany, kde lze odesílat různé hodnoty na vzdálený TCP soket nebo HTTP/HTTPS server. Pro vkládání živých hodnot do přenášeného textu se používají zástupné symboly (tokeny). I když je tento kanál označen jako „External Messaging“, lze jej použít téměř pro jakýkoli účel vyžadující spouštěče událostí v reálném čase, které aktivně poskytuje HALO. Toto uspořádání je poměrně flexibilní, protože výběr na „Akcích“ určuje, které HALO události se vysílají tímto kanálem.
V režimu HTTP jsou řetězce Set a Reset URLs, které je nutné zadat a naformátovat podle požadavků požadovaného cílového serveru. Pro ověření lze použít pole Uživatel a heslo. Viz režim HTTP níže.
V režimu TCP jsou řetězce Set a Reset pouze daty jedné zprávy, která je odeslána do přijímajícího soketu TCP. Lze je formátovat podle potřeby podle cíle. Cíl je specifikován v polích Adresa a Port. Viz Režim TCP níže.
V obou režimech se zobrazí stav z nejnovější zprávy, což může pomoci při opravě připojení nebo jiných problémech. K vynucení zprávy můžete použít tlačítka TEST událostí ve vyskakovacím okně Akce:
Globální zapnutí/vypnutí pro nastavení nebo resetování musí být zapnuto, aby byly povoleny tyto typy zpráv. Reset se často nepoužívá, protože je zajímavý pouze začátek události, ale to se může lišit. Každá událost může nezávisle určit, zda bude používat buď zprávu Set nebo Reset ve vyskakovacím okně Actions. Tlačítka oka zobrazí hrubou reprezentaci toho, co je odesláno po nahrazení klíčových slov a formátování. Repeat Holdoff lze použít k omezení častých zpráv zpožděním před odesláním další. To se provádí nezávisle na události. HALO má vestavěnou dobu zdržení pro události 15 sekund, aby se zabránilo rychlému opětovnému spouštění událostí. Pokud chcete zajistit, aby za minutu nebyla odeslána více než 1 událost určitého typu, můžete nastavit Repeat Holdoff na 60 (sekund).
Podrobnosti srdečního tepu
Přenosy Heartbeat fungují podobným způsobem jako výše s tím rozdílem, že nedochází k žádné interakci se stránkou Akce. Místo toho dochází k přenosu Heartbeat pravidelně, jak je nakonfigurováno v poli Interval. V režimu HTTP jsou řetězce Set a Reset URLs, které je nutné zadat a naformátovat podle požadavků požadovaného cílového serveru. Pro ověření lze použít pole Uživatel a heslo. Viz režim HTTP níže.
Zatímco primárním účelem Heartbeat je poskytnout důkaz o životnosti HALO Smart Sensor vzdálené aplikaci, tuto zprávu lze také použít k přenosu vybraných senzorů nebo informací o aktuálním stavu události. Bývalýample výše odešle parametr dlouhého řetězce s URL které zahrnují název Halo, většinu hodnot senzoru a nakonec Triggered=%ACTIVE%, což může být prázdné nebo seznam aktuálně spouštěných událostí.
Režim HTTP (a HTTPS).
Řetězce externích zpráv a prezenčního signálu mohou být http: nebo https: URLs podle potřeby. Cestu a parametry lze zadat podle potřeby cílového serveru. Klíčová slova jako %NAME% (název zařízení HALO) nebo %EID% (ID události) lze vložit podle potřeby a při odeslání zprávy budou nahrazena příslušnými daty. Pro rychlou orientaci je zobrazen seznam běžně používaných klíčových slov.
The URL cesta může obsahovat klíčová slova i parametry k URL. Parametry mohou být páry NAME=VALUE nebo objekt JSON nebo vlastní formát v závislosti na cílovém serveru. Přampsoubory pro externí zasílání zpráv by zahrnovaly %EID% k označení události, která spustila:
- https://server.com/event/%NAME%/%EID%
- https://server.com/event?location=%NAME%&event=%EID%
- https://server.com/event?{“location”:”:%NAME%”,”event”:”%EID%”}
Examphodnoty pro Heartbeat mohou přidat %ACTIVE% (aktuálně spuštěné události) nebo hodnotu senzoru:
- 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 záhlaví sloupců pravého senzoru v protokolu evtYYYYMMDD.csv files. Obvykle jsou:
Pokud cílový server preferuje HTTP PUT nebo POST namísto požadavků GET, můžete předponu URL pomocí PUT: nebo POST:. Nezávisle na tom můžete přidat datovou část JSON, která je oblíbená na mnoha serverech, přidáním klíčového slova [JSONBODY] následovaného objektem ve formátu JSON. Přampten:
PUT:https://server.com/event[JSONBODY]{“location“:”%NAME%”,”event”:”%EID%”}
The URL podporuje typickou IP adresu (a IPv6) a možnosti portu a uživatelského hesla, nebo můžete v případě potřeby použít pole Uživatel a Heslo jako cílový server pro metody ověřování, jako je Basic nebo Digest:
https://username:password@123.321.123.321:9876/event…
Režim TCP
Řetězce External Messaging a Heartbeat jsou pouze pro data, protože pole Address a Port určují cíl. Adresa podporuje jména, IPv4 a IPv6.
Řetězec může být formátován jako datové části zpráv HTTP popsané výše nebo podle požadavků cílového serveru.
Exampsoubory pro externí zasílání zpráv by zahrnovaly %EID% k označení události, která spustila:
location=%NAME%,event=%EID%
{“location“:”:%NAME%”,”event”:”%EID%”}
Examphodnoty pro Heartbeat mohou přidat %ACTIVE% (aktuálně spuštěné události) nebo hodnotu senzoru:
location=%NAME%&Triggered=%ACTIVE%
{"location":":%NAME%","NH3":%SENSOR:NH3%}
Zaškrtávací políčka ve sloupcích „Integration Set“ a „Integration Reset“ určují, které události spouštějí odesílání. Více o nastavení událostí a akcí je k dispozici v HALO Administrator's Guide.
Doručování zpráv událostí JSON
Někteří vývojáři dávají přednost přijímání dat událostí formátovaných jako průmyslový standard samostatně označený JSON spíše než prostý text ASCII, protože první je spolehlivější a snadněji analyzován. Na HALO web na záložce „Zprávy“, můžete zadat zprávy JSON v nastavení „Externí zasílání zpráv“ „Nastavit řetězec“ a „Resetovat řetězec“ a v „Heartbeat“ „Zpráva“.
Examples:
Nastavení „Externí zasílání zpráv“ Nastavit řetězec:
{ “zařízení”:”%NAME%”, “událost”:”%EID%”, “alarm”:”yes” }
To odešle na zadaný server jedinou zprávu TCP nebo UDP JSON s popisem názvu zařízení, názvu události a toho, že právě začala.
Nastavení „Externí zasílání zpráv“ Resetovat řetězec:
{ “zařízení”:”%NAME%”, “událost”:”%EID%”, “alarm”:”ne” }
To odešle na zadaný server jedinou zprávu TCP nebo UDP JSON, která oznámí popisný název zařízení, název události a to, že stav již skončil.
Zpráva "Tlukot srdce":
{ “zařízení”:”%NAME%”, “živé”:”%DATE% %TIME%” }
To bude pravidelně odesílat zprávu TCP nebo UDP JSON na zadaný server oznamující, že HALO je v uvedeném čase aktivní.
Dokumenty / zdroje
 |
Software Základní software HALO Smart Sensor API [pdfUživatelská příručka Základní software HALO Smart Sensor API |
