Programvare s HALO Smart Sensor API Grunnleggende programvare
Framover
Dette dokumentet beskriver gruppen av fasiliteter til Halo Smart Sensor kjent som BASIC API, eller Application Programming Interface. Denne diskusjonen er ment for bruk av programmerere eller integratorer som er interessert i å integrere en eller flere HALO Smart Sensors (HALOer) med tredjeparts (ikke-IPVideo) programvarekomponenter eller -systemer. Generelt er HALO API ment å overføre informasjon effektivt fra HALO over et konvensjonelt Ethernet-nettverk til det eksterne programmet. For å oppnå dette målet er API-en delt inn i tre seksjoner: Hendelsesdrevet socket-tilkobling, Heartbeat Socket-tilkobling og hendelsesdata URL. BACnet-grensesnitt er også til stede og dekket i et eget dokument.
API-design
API-en er utformet ved bruk av industristandardformater som TCP/IP. HTTP, HTTPS og JSON. Designet krever ingen spesielle eller proprietære teknikker eller biblioteker som skal brukes i utviklingen av det eksterne programmet eller applikasjonen. API-en er fleksibel og kan konfigureres og programmeres for å levere nøyaktig de dataene som kreves og på den mest effektive måten. Detaljene om bruken av hver av de ovennevnte delene er dekket i de følgende delene av denne veiledningen.
Eksterne meldinger
Denne funksjonen brukes til å levere varsler eller alarmer og hendelsesdata til et eksternt program, VMS-system, server osv. når en hendelse utløses (er innstilt). Valgfrie meldinger kan også aktiveres for å signalisere når en hendelse slettes (tilbakestilles). Denne leveringen kan gjøres til en TCP/IP-socket eller HTTP/S-server i sanntid. Det finnes en rekke konfigurerbare protokoller med tilpassbart innhold. Autentisering og kryptering er tilgjengelig.
Hjerteslag
Heartbeat-meldinger sendes med et konfigurerbart intervall (i stedet for når hendelser utløses) for å bevise live/tilgjengelighet. De har en lignende rekke funksjoner som ekstern meldinger, men vil typisk være konfigurert til å inneholde generell tilstandsinformasjon i stedet for detaljer om en bestemt hendelse.
Hendelsesdata URL
Denne funksjonen er kun tilgjengelig under en NDA og skal bare brukes når det eksterne programmet krever tilgang til alle hendelsesverdier, terskler og tilstandsflagg. Disse dataene hentes vanligvis etter behov av det eksterne programmet, men ikke med en veldig høy frekvens. Denne metoden pådrar seg vanligvis en viss forsinkelse når en beskjeden pollingfrekvens brukes. Typiske pollingfrekvenser varierer fra én gang per minutt til én gang per 5 sekunder med en absolutt maksimal hastighet på én gang per sekund. Denne metoden kan også brukes til å hente ytterligere støttedata når en hendelse (varsel) mottas.
Detaljer om eksterne meldinger
En del av HALO web interface Integration popup sørger for konfigurasjon av en enkelt tredjepartsforbindelse der ulike verdier kan sendes til en ekstern TCP-socket eller en HTTP/HTTPS-server. Plassholdere (tokens) brukes til å sette inn levende verdier i den overførte teksten. Selv om den er merket med "Ekstern melding", kan denne kanalen brukes til nesten alle formål som krever sanntids hendelsestriggere, aktivt levert av HALO. Denne ordningen er ganske fleksibel fordi valg på "Handlinger" bestemmer hvilke HALO-hendelser som overfører gjennom denne kanalen.
I HTTP-modus er Set- og Reset-strengene URLs som må angis og formateres etter behov av ønsket målserver. Et bruker- og passordfelt kan brukes for autentisering. Se HTTP-modus nedenfor.
I TCP-modus er Set- og Reset-strengene bare dataene til en enkelt melding som sendes til den mottakende TCP-kontakten. De kan formateres etter behov av destinasjonen. Destinasjonen er spesifisert i feltene Adresse og Port. Se TCP-modus nedenfor.
For begge modusene vises status fra den siste meldingen som kan hjelpe med å fikse tilkoblingen eller andre problemer. Du kan bruke Event TEST-knappene på popup-vinduet Handlinger for å fremtvinge en melding:
Global On/Off for Set eller Reset må være På for å aktivere denne typen meldinger. Tilbakestilling brukes ofte ikke fordi bare starten av en hendelse er av interesse, men det kan variere. Hver hendelse kan uavhengig spesifisere om den vil bruke enten Set- eller Reset-meldingen på popup-vinduet Handlinger. Øyeeplet-knappene vil vise en grov representasjon av hva som sendes etter nøkkelorderstatninger og formatering. Repeat Holdoff kan brukes til å strupe hyppige meldinger ved å utsette før en annen kan sendes. Dette gjøres uavhengig per arrangement. HALO har en innebygd holdetid for hendelser på 15 sekunder for å forhindre rask gjenutløsning av hendelser. Hvis du ønsker å sikre at det ikke sendes mer enn 1 hendelse av en type per minutt, kan du sette Repeat Holdoff til 60 (sekunder).
Hjerteslag detaljer
Heartbeat-overføringene fungerer på samme måte som ovenfor, bortsett fra at det ikke er noen interaksjon med handlingssiden. I stedet skjer Heartbeat-overføringen regelmessig som konfigurert med Intervall-feltet. I HTTP-modus er Set- og Reset-strengene URLs som må angis og formateres etter behov av ønsket målserver. Et bruker- og passordfelt kan brukes for autentisering. Se HTTP-modus nedenfor.
Mens hovedformålet med Heartbeat er å gi bevis på levetiden til en HALO Smart Sensor til en ekstern applikasjon, kan denne meldingen også brukes til å overføre utvalgte sensorer eller gjeldende hendelsesstatusinformasjon. Eksample ovenfor sender en lang strengparameter med URL som inkluderer Halo-navnet, et flertall av sensorverdier, og til slutt Triggered=%ACTIVE% som kan være tom eller en liste over utløste hendelser.
HTTP (og HTTPS)-modus
Eksterne meldings- og hjerteslagstrenger kan være http: eller https: URLetter behov. Bane og parametere kan angis etter behov av destinasjonsserveren. Nøkkelord som %NAME% (HALO enhetsnavn) eller %EID% (Hendelses-ID) kan settes inn etter behov og vil bli erstattet med respektive data når meldingen sendes. En liste over ofte brukte søkeord vises for rask referanse.
De URL banen kan inneholde nøkkelord så vel som parametrene til URL. Parametrene kan være NAME=VALUE-par eller et JSON-objekt, eller et tilpasset format avhengig av målserveren. Eksamples for ekstern melding vil inkludere %EID% for å indikere hendelsen 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 for Heartbeat kan legge til %ACTIVE% (for øyeblikket utløste hendelser) eller en sensorverdi:
- https://server.com/alive?location=%NAME%&Triggered=%ACTIVE%
- https://server.com/event?{“location”:”:%NAME%”,”NH3”:%SENSOR:NH3%}
%SENSOR:...%-verdiene bruker navnene som finnes i sensorkolonneoverskriftene til høyre i evtYYYYMMDD.csv-loggen files. De er vanligvis:
Hvis målserveren foretrekker HTTP PUT eller POST i stedet for GET-forespørsler, kan du prefikse URL med PUT: eller POST:. Uavhengig kan du legge til en JSON-nyttelast som er populær på mange servere ved å legge til nøkkelordet [JSONBODY] etterfulgt av et JSON-formatert objekt. Eksampde:
PUT:https://server.com/event[JSONBODY]{“location”:”%NAME%”,”event”:”%EID%”}
De URL støtter typisk IP-adresse (og IPv6) og port- og brukerpassordalternativer, eller du kan bruke bruker- og passordfeltene om nødvendig som målserver for autentiseringsmetoder som Basic eller Digest:
https://username:password@123.321.123.321:9876/event…
TCP-modus
Eksterne meldings- og hjerteslag-strenger er kun for data, siden Adresse- og Port-feltene spesifiserer destinasjonen. Adressen støtter navn, IPv4 og IPv6.
Strengen kan formateres som datadelene av HTTP-meldinger beskrevet ovenfor, eller som kreves av målserveren.
Examples for ekstern melding vil inkludere %EID% for å indikere hendelsen som utløste:
location=%NAME%,event=%EID%
{“location”:”:%NAME%”,”event”:”%EID%”}
Examples for Heartbeat kan legge til %ACTIVE% (for øyeblikket utløste hendelser) eller en sensorverdi:
location=%NAME%&Triggered=%ACTIVE%
{“location”:”:%NAME%”,,”NH3”:%SENSOR:NH3%}
Avmerkingsbokser i kolonnene "Integration Set" og "Integration Reset" avgjør hvilke hendelser som utløser sending. Mer om oppsettet av hendelser og handlinger er tilgjengelig i HALO Administrator's Guide.
Levering av JSON-hendelsesmeldinger
Noen utviklere foretrekker å motta hendelsesdata formatert som industristandard selvmerket JSON i stedet for ren ASCII-tekst, da førstnevnte er mer pålitelig og lettere å analysere. På HALO web siden "Messaging"-fanen, kan du levere JSON-meldinger i "External Messaging"-innstillingene "Set String" og "Reset String" og i "Heartbeat" "Message".
Examples:
"Ekstern melding" Innstillinger Sett streng:
{ "device":"%NAME%", "event":"%EID%", "alarm":"yes" }
Dette vil sende en enkelt TCP- eller UDP JSON-melding til den spesifiserte serveren som rapporterer det vennlige enhetsnavnet, hendelsesnavnet og at det nettopp startet.
"Eksterne meldinger" Innstillinger Tilbakestill streng:
{ "device":"%NAME%", "event":"%EID%", "alarm":"no" }
Dette vil sende en enkelt TCP- eller UDP JSON-melding til den angitte serveren som rapporterer det vennlige enhetsnavnet, hendelsesnavnet og at tilstanden nå har stoppet.
"Hjerteslag"-melding:
{ "device":"%NAME%", "alive":"%DATE% %TIME%" }
Dette vil med jevne mellomrom sende en TCP- eller UDP JSON-melding til den spesifiserte serveren som rapporterer at HALO er i live på det angitte tidspunktet.
Dokumenter / Ressurser
 |
Programvare s HALO Smart Sensor API Grunnleggende programvare [pdfBrukerhåndbok Grunnleggende programvare for HALO Smart Sensor API |
