Programvara s HALO Smart Sensor API Basic Software
Fram
Detta dokument beskriver gruppen av faciliteter för Halo Smart Sensor, gemensamt känd som BASIC API, eller Application Programming Interface. Den här diskussionen är avsedd att användas av programmerare eller integratörer som är intresserade av att integrera en eller flera HALO Smart Sensors (HALO) med tredje parts (icke-IPVideo) programvarukomponenter eller system. I allmänhet är HALO API avsett att överföra information effektivt från HALO över ett konventionellt Ethernet-nätverk till det externa programmet. För att uppnå detta mål är API:et uppdelat i tre sektioner: Event Driven Socket Connection, Heartbeat Socket Connection och Event Data URL. BACnet-gränssnittet finns också och täcks i ett separat dokument.
API-design
API:et är utformat med branschstandardformat som TCP/IP. HTTP, HTTPS och JSON. Designen kräver inga speciella eller patentskyddade tekniker eller bibliotek som ska användas vid utvecklingen av det externa programmet eller applikationen. API:et är flexibelt och kan konfigureras och programmeras för att leverera exakt den data som krävs och på det mest effektiva sättet. Detaljerna för funktionen av vart och ett av ovanstående avsnitt behandlas i följande avsnitt i den här guiden.
Externa meddelanden
Denna funktion används för att leverera larm eller larm och händelsedata till ett externt program, VMS-system, server etc. när en händelse utlöses (ställs in). Valfria meddelanden kan också aktiveras för att signalera när en händelse raderas (återställs). Denna leverans kan göras till en TCP/IP-socket eller HTTP/S-server i realtid. Det finns en rad konfigurerbara protokoll med anpassningsbart innehåll. Autentisering och kryptering är tillgängliga.
Hjärtslag
Heartbeat-meddelanden skickas med ett konfigurerbart intervall (istället för när händelser utlöses) för att bevisa live/tillgänglighet. De har ett liknande utbud av möjligheter som External Messaging men skulle vanligtvis vara konfigurerade för att innehålla allmän statusinformation snarare än detaljer om en viss händelse.
Händelsedata URL
Denna funktion är endast tillgänglig under en NDA och bör endast användas när det externa programmet kräver åtkomst till alla händelsevärden, trösklar och tillståndsflaggor. Dessa data hämtas vanligtvis på begäran av det externa programmet men inte med en mycket hög frekvens. Denna metod ådrar sig i allmänhet viss latens när en blygsam avfrågningsfrekvens används. Typiska pollinghastigheter sträcker sig från en gång per minut till en gång per 5 sekunder med en absolut maximal hastighet på en gång per sekund. Denna metod kan också användas för att hämta ytterligare stöddata när en händelse (varning) tas emot.
Externa meddelanden detaljer
En del av HALO web gränssnitt Integration popup ger för konfiguration av en enda 3:e parts anslutning där olika värden kan skickas till en fjärransluten TCP-socket eller en HTTP/HTTPS-server. Platshållare (tokens) används för att infoga levande värden i den överförda texten. Även om den är märkt "External Messaging", kan denna kanal användas för nästan alla ändamål som kräver händelseutlösare i realtid, aktivt levererade av HALO. Detta arrangemang är ganska flexibelt eftersom val på "Actions" avgör vilka HALO-händelser som sänder genom denna kanal.
I HTTP-läge är Set- och Reset-strängarna URLs som måste anges och formateras som krävs av den önskade destinationsservern. Fältet Användare och Lösenord kan användas för autentisering. Se HTTP-läge nedan.
I TCP-läge är Set- och Reset-strängarna endast data för ett enda meddelande som skickas till den mottagande TCP-socket. De kan formateras efter behov av destinationen. Destinationen anges i fälten Adress och Port. Se TCP-läge nedan.
För båda lägena visas status från det senaste meddelandet, vilket kan hjälpa till att åtgärda anslutningen eller andra problem. Du kan använda knapparna Event TEST på popup-fönstret Actions för att tvinga fram ett meddelande:
Global On/Off för Set eller Reset måste vara På för att aktivera dessa typer av meddelanden. Återställning används ofta inte eftersom endast början av en händelse är av intresse, men det kan variera. Varje händelse kan självständigt ange om den kommer att använda antingen Set- eller Reset-meddelandet på popup-fönstret Actions. Ögonglobsknapparna kommer att visa en grov representation av vad som skickas efter nyckelordsersättningar och formatering. Repeat Holdoff kan användas för att strypa frekventa meddelanden genom att fördröja innan ett annat kan skickas. Detta görs självständigt per evenemang. HALO har en inbyggd hålltid för händelser på 15 sekunder för att förhindra snabb återutlösning av händelser. Om du vill säkerställa att inte mer än 1 händelse av en typ skickas per minut, kan du ställa in Repeat Holdoff till 60 (sekunder).
Hjärtslagsdetaljer
Heartbeat-överföringarna fungerar på liknande sätt som ovan, förutom att det inte finns någon interaktion med sidan Åtgärder. Istället sker hjärtslagsöverföringen regelbundet enligt konfigurering med intervallfältet. I HTTP-läge är Set- och Reset-strängarna URLs som måste anges och formateras som krävs av den önskade destinationsservern. Fältet Användare och Lösenord kan användas för autentisering. Se HTTP-läge nedan.
Även om det primära syftet med Heartbeat är att ge ett bevis på en HALO Smart Sensors livslängd till en fjärrapplikation, kan detta meddelande också användas för att överföra utvalda sensorer eller aktuell information om händelsetillstånd. Exetample ovan skickar en lång strängparameter med URL som inkluderar Halo-namnet, en majoritet av sensorvärden och slutligen Triggered=%ACTIVE% som kan vara tom eller en lista över för närvarande utlösta händelser.
HTTP (och HTTPS) läge
Externa meddelanden och Heartbeat-strängar kan vara http: eller https: URLefter behov. Sökväg och parametrar kan anges efter behov av destinationsservern. Nyckelord som %NAME% (HALO enhetsnamn) eller %EID% (Händelse-id) kan infogas efter behov och kommer att ersättas med respektive data när meddelandet skickas. En lista över vanliga sökord visas för snabb referens.
De URL sökväg kan innehålla nyckelord såväl som parametrarna till URL. Parametrarna kan vara NAME=VALUE-par eller ett JSON-objekt, eller ett anpassat format beroende på målservern. Exampfiler för externa meddelanden skulle innehålla %EID% för att indikera händelsen som utlöste:
- https://server.com/event/%NAME%/%EID%
- https://server.com/event?location=%NAME%&event=%EID%
- https://server.com/event?{“location”:”:%NAME%”,”event”:”%EID%”}
Examples för Heartbeat kan lägga till %ACTIVE% (för närvarande utlösta händelser) eller ett sensorvärde:
- https://server.com/alive?location=%NAME%&Triggered=%ACTIVE%
- https://server.com/event?{“location”:”:%NAME%”,”NH3”:%SENSOR:NH3%}
%SENSOR:...%-värdena använder namnen som finns i den högra sensorkolumnrubrikerna i evtYYYYMMDD.csv-loggen files. De är vanligtvis:
Om destinationsservern föredrar HTTP PUT eller POST istället för GET-förfrågningar, kan du prefixet URL med PUT: eller POST:. Oberoende kan du lägga till en JSON-nyttolast som är populär på många servrar genom att lägga till nyckelordet [JSONBODY] följt av ett JSON-formaterat objekt. Exampde:
PUT:https://server.com/event[JSONBODY]{"location":"%NAME%","event":"%EID%"}
De URL stöder typiska IP-adress (och IPv6) och port- och användarlösenordsalternativ, eller så kan du använda fälten Användare och Lösenord om det behövs som målserver för autentiseringsmetoder som Basic eller Digest:
https://username:password@123.321.123.321:9876/event…
TCP-läge
Externa meddelanden och Heartbeat-strängar är bara för data eftersom fälten Adress och Port anger destinationen. Adressen stöder namn, IPv4 och IPv6.
Strängen kan formateras som datadelarna av HTTP-meddelanden som beskrivs ovan, eller som krävs av destinationsservern.
Exampfiler för externa meddelanden skulle innehålla %EID% för att indikera händelsen som utlöste:
plats=%NAME%,event=%EID%
{"plats":":%NAME%","event":"%EID%"}
Examples för Heartbeat kan lägga till %ACTIVE% (för närvarande utlösta händelser) eller ett sensorvärde:
location=%NAME%&Triggered=%ACTIVE%
{"plats":":%NAME%","NH3":%SENSOR:NH3%}
Kryssrutorna i kolumnerna "Integrationsuppsättning" och "Integrationsåterställning" avgör vilka händelser som utlöser sändning. Mer om inställningen av händelser och åtgärder finns i HALO Administrator's Guide.
Leverans av JSON Event Messages
Vissa utvecklare föredrar att ta emot händelsedata formaterad som industristandard självmärkt JSON snarare än vanlig ASCII-text eftersom den förra är mer tillförlitlig och lättare att tolka. På HALO web sidan "Meddelanden" kan du skicka JSON-meddelanden i "External Messaging"-inställningarna "Set String" och "Reset String" och i "Heartbeat" "Message".
Examples:
"Externa meddelanden" Inställningar Ange sträng:
{ "device":"%NAME%", "event":"%EID%", "alarm":"yes" }
Detta kommer att skicka ett enda TCP- eller UDP-JSON-meddelande till den angivna servern som rapporterar det vänliga enhetens namn, händelsenamnet och att den precis har startat.
"Externa meddelanden" Inställningar Återställ sträng:
{ "device":"%NAME%", "event":"%EID%", "alarm":"no" }
Detta kommer att skicka ett enda TCP- eller UDP JSON-meddelande till den angivna servern som rapporterar det vänliga enhetens namn, händelsenamnet och att tillståndet nu har stoppats.
"Hjärtslag"-meddelande:
{ "device":"%NAME%", "alive":"%DATE% %TIME%" }
Detta kommer regelbundet att skicka ett TCP- eller UDP-JSON-meddelande till den angivna servern som rapporterar att HALO är vid den angivna tidpunkten.
Dokument/resurser
 |
Programvara s HALO Smart Sensor API Basic Software [pdf] Användarhandbok HALO Smart Sensor API grundläggande programvara |
