Software s HALO Smart Sensor API-basissoftware
Vooruit
Dit document beschrijft de groep faciliteiten van de Halo Smart Sensor, gezamenlijk bekend als de BASIC API of Application Programming Interface. Deze discussie is bedoeld voor gebruik door programmeurs of integrators die geïnteresseerd zijn in het integreren van een of meer HALO Smart Sensors (HALO's) met softwarecomponenten of -systemen van derden (niet-IPVideo). Over het algemeen is de HALO API bedoeld om informatie efficiënt over te dragen van HALO via een conventioneel Ethernet-netwerk naar het externe programma. Om dit doel te bereiken is de API verdeeld in drie secties: Event Driven Socket Connection, Heartbeat Socket Connection en Event Data URL. De BACnet-interface is ook aanwezig en wordt besproken in een apart document.
API-ontwerp
De API is ontworpen met behulp van industriestandaardformaten zoals TCP/IP. HTTP, HTTPS en JSON. Het ontwerp vereist geen speciale of gepatenteerde technieken of bibliotheken die moeten worden gebruikt bij de ontwikkeling van het externe programma of de externe applicatie. De API is flexibel en kan worden geconfigureerd en geprogrammeerd om precies de benodigde gegevens op de meest efficiënte manier te leveren. De details van de werking van elk van de bovenstaande secties worden behandeld in de volgende secties van deze handleiding.
Externe berichten
Deze faciliteit wordt gebruikt om waarschuwingen of alarmen en gebeurtenisgegevens te leveren aan een extern programma, VMS-systeem, server, enz. wanneer een gebeurtenis wordt geactiveerd (is ingesteld). Optionele berichten kunnen ook worden ingeschakeld om aan te geven wanneer een gebeurtenis wordt gewist (wordt gereset). Deze levering kan in realtime plaatsvinden op een TCP/IP-socket of HTTP/S-server. Er is een reeks configureerbare protocollen met aanpasbare inhoud. Authenticatie en encryptie zijn beschikbaar.
Hartslag
Heartbeat-berichten worden verzonden met een configureerbaar interval (in plaats van wanneer gebeurtenissen worden geactiveerd) om bewijs te leveren van live/beschikbaarheid. Ze hebben een vergelijkbare reeks mogelijkheden als Externe Berichten, maar zijn doorgaans geconfigureerd om algemene statusinformatie te bevatten in plaats van details over een bepaalde gebeurtenis.
Gebeurtenisgegevens URL
Deze faciliteit is alleen beschikbaar onder een geheimhoudingsverklaring en mag alleen worden gebruikt als het externe programma toegang vereist tot alle gebeurteniswaarden, drempels en statusvlaggen. Deze gegevens worden doorgaans op verzoek opgehaald door het externe programma, maar niet met een zeer hoge frequentie. Deze methode brengt doorgaans enige latentie met zich mee wanneer een bescheiden pollingsnelheid wordt gebruikt. Typische pollingsnelheden variëren van één keer per minuut tot één keer per 5 seconden, met een absoluut maximum van één keer per seconde. Deze methode kan ook worden gebruikt om aanvullende ondersteunende gegevens op te halen wanneer een gebeurtenis (waarschuwing) wordt ontvangen.
Gegevens over externe berichten
Een deel van de HALO web interface Integratiepop-up zorgt voor de configuratie van een enkele verbinding van derden, waarbij verschillende waarden naar een externe TCP-socket of een HTTP/HTTPS-server kunnen worden verzonden. Plaatshouders (tokens) worden gebruikt om live waarden in de verzonden tekst in te voegen. Hoewel het de naam 'Externe berichtenuitwisseling' heeft, kan dit kanaal voor vrijwel elk doel worden gebruikt waarvoor realtime gebeurtenistriggers nodig zijn, die actief worden geleverd door HALO. Deze opstelling is vrij flexibel omdat selecties op de “Acties” bepalen welke HALO-evenementen via dit kanaal worden verzonden.
In de HTTP-modus zijn de Set- en Reset-tekenreeksen de URLs die moeten worden ingevoerd en geformatteerd zoals vereist door de gewenste doelserver. Voor authenticatie kan een veld Gebruiker en Wachtwoord worden gebruikt. Zie HTTP-modus hieronder.
In de TCP-modus zijn de Set- en Reset-strings slechts de gegevens van één enkel bericht dat naar de ontvangende TCP-socket wordt verzonden. Ze kunnen naar behoefte worden opgemaakt voor de bestemming. De bestemming wordt opgegeven in de velden Adres en Poort. Zie TCP-modus hieronder.
Voor beide modi wordt de status van het meest recente bericht weergegeven, wat kan helpen bij het oplossen van verbindings- of andere problemen. U kunt de Event TEST-knoppen in de pop-up Acties gebruiken om een bericht te forceren:
Globaal Aan/Uit voor Instellen of Reset moet Aan zijn om dit soort berichten in te schakelen. Reset wordt vaak niet gebruikt omdat alleen het begin van een Event van belang is, maar dat kan variëren. Elke gebeurtenis kan onafhankelijk specificeren of het het Set- of Reset-bericht in de pop-up Acties zal gebruiken. De oogbolknoppen geven een ruwe weergave weer van wat er wordt verzonden na vervanging van trefwoorden en opmaak. Repeat Holdoff kan worden gebruikt om frequente berichten af te remmen door uit te stellen voordat een volgende kan worden verzonden. Dit gebeurt zelfstandig per Evenement. HALO heeft een ingebouwde houdtijd voor gebeurtenissen van 15 seconden om snelle hertriggering van gebeurtenissen te voorkomen. Als u er zeker van wilt zijn dat er niet meer dan 1 gebeurtenis van een bepaald type per minuut wordt verzonden, kunt u Repeat Holdoff instellen op 60 (seconden).
Hartslagdetails
De Heartbeat-transmissies werken op dezelfde manier als hierboven, behalve dat er geen interactie is met de pagina Acties. In plaats daarvan vindt de Heartbeat-transmissie regelmatig plaats, zoals geconfigureerd met het veld Interval. In de HTTP-modus zijn de Set- en Reset-strings de URLs die moeten worden ingevoerd en geformatteerd zoals vereist door de gewenste doelserver. Voor authenticatie kan een veld Gebruiker en Wachtwoord worden gebruikt. Zie HTTP-modus hieronder.
Hoewel het primaire doel van de Heartbeat het leveren van bewijs van levensduur van een HALO Smart Sensor aan een externe toepassing is, kan dit bericht ook worden gebruikt om geselecteerde sensoren of actuele informatie over de gebeurtenisstatus te verzenden. De example hierboven verzendt een lange tekenreeksparameter met de URL die de Halo-naam bevatten, een meerderheid van de sensorwaarden en ten slotte Triggered=%ACTIVE%, wat leeg kan zijn of een lijst met momenteel geactiveerde gebeurtenissen.
HTTP- (en HTTPS)-modus
Externe bericht- en hartslagreeksen kunnen http: of https zijn: URLs indien nodig. Pad en parameters kunnen indien nodig worden ingevoerd door de doelserver. Trefwoorden zoals %NAME% (HALO-apparaatnaam) of %EID% (gebeurtenis-ID) kunnen indien nodig worden ingevoegd en worden vervangen door de betreffende gegevens wanneer het bericht wordt verzonden. Voor snelle referentie wordt een lijst met veelgebruikte trefwoorden weergegeven.
De URL pad kan trefwoorden bevatten, evenals de parameters voor het URL. De parameters kunnen NAME=VALUE-paren of een JSON-object zijn, of een aangepaste indeling, afhankelijk van de doelserver. Exampbestanden voor externe berichten bevatten %EID% om de gebeurtenis aan te geven die het volgende heeft geactiveerd:
- https://server.com/event/%NAME%/%EID%
- https://server.com/event?location=%NAME%&event=%EID%
- https://server.com/event?{“location”:”:%NAME%”,”event”:”%EID%”}
Exampbestanden voor Heartbeat kunnen %ACTIVE% (momenteel geactiveerde gebeurtenissen) of een sensorwaarde toevoegen:
- https://server.com/alive?location=%NAME%&Triggered=%ACTIVE%
- https://server.com/event?{“location”:”:%NAME%”,”NH3”:%SENSOR:NH3%}
De %SENSOR:…%-waarden gebruiken de namen die te vinden zijn in de rechtersensorkolomkoppen in het evtJJJJMMDD.csv-logboek fileS. Dit zijn doorgaans:
Als de doelserver de voorkeur geeft aan HTTP PUT of POST in plaats van GET-verzoeken, kunt u de URL met PUT: of POST:. U kunt zelfstandig een JSON-payload toevoegen die populair is bij veel servers door het trefwoord [JSONBODY] toe te voegen, gevolgd door een JSON-geformatteerd object. Exampon:
PUT:https://server.com/event[JSONBODY]{“locatie”:”%NAME%”,”event”:”%EID%”}
De URL ondersteunt typische IP-adressen (en IPv6) en poort- en gebruikerswachtwoordopties, of u kunt indien nodig de velden Gebruiker en Wachtwoord gebruiken als de doelserver voor authenticatiemethoden zoals Basic of Digest:
https://username:password@123.321.123.321:9876/event…
TCP-modus
Externe berichten- en hartslagreeksen zijn alleen bedoeld voor gegevens, aangezien de velden Adres en Poort de bestemming specificeren. Het adres ondersteunt namen, IPv4 en IPv6.
De tekenreeks kan worden geformatteerd zoals de gegevensgedeelten van HTTP-berichten die hierboven zijn beschreven, of zoals vereist door de doelserver.
Exampbestanden voor externe berichten bevatten %EID% om de gebeurtenis aan te geven die het volgende heeft geactiveerd:
locatie=%NAME%,gebeurtenis=%EID%
{“locatie”:”:%NAME%”,”gebeurtenis”:”%EID%”}
Exampbestanden voor Heartbeat kunnen %ACTIVE% (momenteel geactiveerde gebeurtenissen) of een sensorwaarde toevoegen:
locatie=%NAME%&getriggerd=%ACTIEF%
{“locatie”:”:%NAME%”,NH3”:%SENSOR:NH3%}
Selectievakjes in de kolommen 'Integratieset' en 'Integratiereset' bepalen welke gebeurtenissen het verzenden activeren. Meer over het instellen van gebeurtenissen en acties is beschikbaar in de HALO Beheerdershandleiding.
Levering van JSON-gebeurtenisberichten
Sommige ontwikkelaars geven er de voorkeur aan gebeurtenisgegevens te ontvangen die zijn opgemaakt als industriestandaard zelfgelabelde JSON in plaats van gewone ASCII-tekst, omdat de eerste betrouwbaarder en gemakkelijker te parseren is. Op de HALO web Op het tabblad “Berichten” op de pagina kunt u JSON-berichten opgeven in de instellingen “Externe berichten” “Set String” en “Reset String” en in de “Heartbeat” “Bericht.”
Examples:
Instellingen voor “Externe berichten” Set String:
{ “apparaat”:”%NAME%”, “gebeurtenis”:”%EID%”, “alarm”:”ja” }
Hiermee wordt een enkel TCP- of UDP JSON-bericht naar de opgegeven server verzonden, waarin de gebruiksvriendelijke apparaatnaam en gebeurtenisnaam worden vermeld en dat het net is gestart.
Instellingen voor “Externe berichten” Tekenreeks opnieuw instellen:
{ “apparaat”:”%NAME%”, “gebeurtenis”:”%EID%”, “alarm”:”nee” }
Hierdoor wordt een enkel TCP- of UDP JSON-bericht naar de opgegeven server verzonden, waarin de gebruiksvriendelijke apparaatnaam en gebeurtenisnaam worden gerapporteerd en dat de voorwaarde nu is gestopt.
Bericht “Hartslag”:
{ “apparaat”:”%NAME%”, “levend”:”%DATE% %TIME%” }
Hierdoor wordt periodiek een TCP- of UDP JSON-bericht naar de opgegeven server verzonden met de melding dat de HALO op het aangegeven tijdstip in leven is.
Documenten / Bronnen
 |
Software s HALO Smart Sensor API-basissoftware [pdf] Gebruikershandleiding HALO Smart Sensor API-basissoftware |
