Software s HALO Smart Sensor API Basic Software
Forward
Dette dokument beskriver gruppen af faciliteter i Halo Smart Sensor, der tilsammen er kendt som BASIC API eller Application Programming Interface. Denne diskussion er beregnet til brug af programmører eller integratorer, der er interesserede i at integrere en eller flere HALO Smart Sensors (HALO'er) med tredjeparts (ikke-IPVideo) softwarekomponenter eller -systemer. Generelt er HALO API beregnet til at overføre information effektivt fra HALO over et konventionelt Ethernet-netværk til det eksterne program. For at nå dette mål er API'et opdelt i tre sektioner: Event-drevet socket-forbindelse, Heartbeat-socket-forbindelse og hændelsesdata URL. BACnet-grænsefladen er også til stede og dækket i et separat dokument.
API design
API'en er designet ved hjælp af industristandardformater såsom TCP/IP. HTTP, HTTPS og JSON. Designet kræver ingen specielle eller proprietære teknikker eller biblioteker, der skal bruges i udviklingen af det eksterne program eller applikation. API'et er fleksibelt og kan konfigureres og programmeres til at levere præcis de nødvendige data og på den mest effektive måde. Detaljerne om betjeningen af hvert af ovenstående afsnit er dækket i de følgende afsnit i denne vejledning.
Ekstern beskeder
Denne facilitet bruges til at levere alarmer eller alarmer og hændelsesdata til et eksternt program, VMS-system, server osv., når en hændelse udløses (er indstillet). Valgfri meddelelser kan også aktiveres for at signalere, når en hændelse slettes (nulstilles). Denne levering kan ske til en TCP/IP-socket eller HTTP/S-server i realtid. Der er en række konfigurerbare protokoller med tilpasset indhold. Godkendelse og kryptering er tilgængelig.
Hjerteslag
Heartbeat-beskeder sendes med et konfigurerbart interval (i stedet for når hændelser udløses) for at bevise live/tilgængelighed. De har en lignende række af muligheder som ekstern meddelelse, men vil typisk være konfigureret til at indeholde generelle tilstandsoplysninger snarere end detaljer om en bestemt hændelse.
Hændelsesdata URL
Denne funktion er kun tilgængelig under en NDA og bør kun bruges, når det eksterne program kræver adgang til alle hændelsesværdier, tærskler og tilstandsflag. Disse data hentes generelt efter behov af det eksterne program, men ikke med en særlig høj frekvens. Denne metode medfører generelt en vis forsinkelse, når der anvendes en beskeden pollinghastighed. Typiske afstemningshastigheder varierer fra én gang pr. minut til én gang pr. 5 sekunder med en absolut maksimumhastighed på én gang pr. sekund. Denne metode kan også bruges til at hente yderligere understøttende data, når en hændelse (alarm) modtages.
Detaljer om eksterne meddelelser
En del af HALO web interface Integration popup giver mulighed for konfiguration af en enkelt 3. parts forbindelse, hvor forskellige værdier kan sendes til en fjern TCP socket eller en HTTP/HTTPS server. Pladsholdere (tokens) bruges til at indsætte live-værdier i den transmitterede tekst. Selvom den er mærket "Ekstern beskeder", kan denne kanal bruges til næsten ethvert formål, der kræver hændelsesudløsere i realtid, aktivt leveret af HALO. Dette arrangement er ret fleksibelt, fordi valg på "Actions" bestemmer, hvilke HALO-begivenheder der transmitterer gennem denne kanal.
I HTTP-tilstand er Indstil- og Nulstil-strengene URLs, der skal indtastes og formateres som krævet af den ønskede destinationsserver. Et bruger- og adgangskodefelt kan bruges til godkendelse. Se HTTP-tilstand nedenfor.
I TCP-tilstand er Indstil- og Nulstil-strengene kun data fra en enkelt besked, der sendes til den modtagende TCP-socket. De kan formateres efter behov af destinationen. Destinationen er angivet i felterne Adresse og Port. Se TCP-tilstand nedenfor.
For begge tilstande vises status fra den seneste meddelelse, som kan hjælpe med at løse forbindelsen eller andre problemer. Du kan bruge Event TEST-knapperne på popup-vinduet Handlinger til at fremtvinge en besked:
Global On/Off for Set eller Reset skal være On for at aktivere disse typer meddelelser. Nulstilling bruges ofte ikke, fordi det kun er begyndelsen af en begivenhed, der er af interesse, men det kan variere. Hver hændelse kan uafhængigt angive, om den vil bruge enten Sæt- eller Nulstil-meddelelsen på popup-vinduet Handlinger. Øjeæbleknapperne vil vise en grov repræsentation af, hvad der sendes efter søgeordsudskiftninger og formatering. Repeat Holdoff kan bruges til at drosle hyppige beskeder ved at forsinke, før en anden kan sendes. Dette gøres uafhængigt pr. arrangement. HALO har en indbygget holdetid for hændelser på 15 sekunder for at forhindre hurtig genudløsning af hændelser. Hvis du ville sikre dig, at der ikke sendes mere end 1 hændelse af en type pr. minut, kunne du indstille Repeat Holdoff til 60 (sekunder).
Hjerteslag detaljer
Heartbeat-transmissionerne fungerer på samme måde som ovenstående, bortset fra at der ikke er nogen interaktion med siden Handlinger. I stedet for sker Heartbeat-transmissionen regelmæssigt som konfigureret med Interval-feltet. I HTTP-tilstand er Set- og Reset-strengene URLs, der skal indtastes og formateres som krævet af den ønskede destinationsserver. Et bruger- og adgangskodefelt kan bruges til godkendelse. Se HTTP-tilstand nedenfor.
Mens det primære formål med Heartbeat er at give bevis på levetiden af en HALO Smart Sensor til en fjernapplikation, kan denne meddelelse også bruges til at sende udvalgte sensorer eller aktuelle hændelsestilstandsoplysninger. Eksample ovenfor sender en lang streng parameter med URL som inkluderer Halo-navnet, et flertal af sensorværdier og til sidst Triggered=%ACTIVE%, som kan være tom eller en liste over aktuelt udløste hændelser.
HTTP (og HTTPS) tilstand
Eksterne meddelelser og hjerteslag-strenge kan være http: eller https: URLefter behov. Sti og parametre kan indtastes efter behov af destinationsserveren. Nøgleord som %NAME% (HALO enhedsnavn) eller %EID% (Begivenheds-id) kan indsættes efter behov og vil blive erstattet med respektive data, når beskeden sendes. En liste over ofte brugte søgeord vises til hurtig reference.
De URL sti kan indeholde nøgleord såvel som parametrene til URL. Parametrene kan være NAME=VALUE-par eller et JSON-objekt eller et brugerdefineret format afhængigt af destinationsserveren. Eksamples til ekstern meddelelse ville inkludere %EID% for at angive den hændelse, der udløste:
- https://server.com/event/%NAME%/%EID%
- https://server.com/event?location=%NAME%&event=%EID%
- https://server.com/event?{“location”:”:%NAME%”,”event”:”%EID%”}
Examples for Heartbeat kan tilføje %ACTIVE% (aktuelt udløste hændelser) eller en sensorværdi:
- https://server.com/alive?location=%NAME%&Triggered=%ACTIVE%
- https://server.com/event?{“location”:”:%NAME%”,”NH3”:%SENSOR:NH3%}
%SENSOR:...%-værdierne bruger navnene, der findes i højre sensorkolonneoverskrifter i evt.ÅÅÅÅMMDD.csv-log files. De er typisk:
Hvis destinationsserveren foretrækker HTTP PUT eller POST i stedet for GET-anmodninger, kan du præfikse URL med PUT: eller POST:. Uafhængigt kan du tilføje en JSON-nyttelast, som er populær på mange servere, ved at tilføje nøgleordet [JSONBODY] efterfulgt af et JSON-formateret objekt. Eksampdet:
PUT:https://server.com/event[JSONBODY]{"location":"%NAME%","event":"%EID%"}
De URL understøtter typisk IP-adresse (og IPv6) og port- og brugeradgangskodeindstillinger, eller du kan bruge felterne Bruger og Adgangskode, hvis det er nødvendigt, som destinationsserveren til godkendelsesmetoder som Basic eller Digest:
https://username:password@123.321.123.321:9876/event…
TCP-tilstand
Eksterne meddelelser og hjerteslag-strenge er kun til data, da felterne Adresse og Port angiver destinationen. Adressen understøtter navne, IPv4 og IPv6.
Strengen kan formateres som datadelene af HTTP-meddelelser beskrevet ovenfor eller som krævet af destinationsserveren.
Examples til ekstern meddelelse ville inkludere %EID% for at angive den hændelse, der udløste:
location=%NAME%,hændelse=%EID%
{"location":":%NAME%","event":"%EID%"}
Examples for Heartbeat kan tilføje %ACTIVE% (aktuelt udløste hændelser) eller en sensorværdi:
location=%NAME%&Triggered=%ACTIVE%
{"placering":":%NAME%","NH3":%SENSOR:NH3%}
Afkrydsningsfelter i kolonnerne "Integrationssæt" og "Integrationsnulstilling" bestemmer, hvilke hændelser, der udløser afsendelse. Mere om opsætningen af hændelser og handlinger er tilgængelig i HALO Administrator's Guide.
Levering af JSON Event Messages
Nogle udviklere foretrækker at modtage hændelsesdata formateret som industristandard selvmærket JSON frem for almindelig ASCII-tekst, da førstnævnte er mere pålideligt og lettere at analysere. På HALO web side "Messaging"-fanen, kan du levere JSON-meddelelser i "External Messaging"-indstillingerne "Set String" og "Reset String" og i "Heartbeat" "Message".
Examples:
Indstillinger for "Ekstern beskeder" Indstil streng:
{ "device":"%NAME%", "event":"%EID%", "alarm":"yes" }
Dette vil sende en enkelt TCP- eller UDP JSON-meddelelse til den angivne server, der rapporterer det venlige enhedsnavn, hændelsesnavnet, og at det lige er startet.
"Eksterne meddelelser" Indstillinger Nulstil streng:
{ "device":"%NAME%", "event":"%EID%", "alarm":"no" }
Dette vil sende en enkelt TCP- eller UDP JSON-meddelelse til den angivne server, der rapporterer det venlige enhedsnavn, hændelsesnavnet, og at tilstanden nu er stoppet.
"Hjerteslag"-meddelelse:
{ "device":"%NAME%", "alive":"%DATE% %TIME%" }
Dette vil med jævne mellemrum sende en TCP- eller UDP JSON-meddelelse til den angivne server, der rapporterer, at HALO'en er i live på det angivne tidspunkt.
Dokumenter/ressourcer
 |
Software s HALO Smart Sensor API Basic Software [pdfBrugervejledning HALO Smart Sensor API grundlæggende software |
