Ohjelmiston HALO Smart Sensor API -perusohjelmisto
Eteenpäin
Tässä asiakirjassa kuvataan Halo Smart Sensorin toimintoja, jotka tunnetaan yhdessä nimellä BASIC API tai Application Programming Interface. Tämä keskustelu on tarkoitettu ohjelmoijien tai integraattoreiden käyttöön, jotka ovat kiinnostuneita yhden tai useamman HALO-älysensorin (HALO) integroimisesta kolmannen osapuolen (ei-IPVideo) ohjelmistokomponentteihin tai -järjestelmiin. Yleisesti ottaen HALO API on tarkoitettu siirtämään tietoa tehokkaasti HALOsta perinteisen Ethernet-verkon kautta ulkoiseen ohjelmaan. Tämän tavoitteen saavuttamiseksi API on jaettu kolmeen osaan: Tapahtumalähtöinen Socket Connection, Heartbeat Socket Connection ja Event Data URL. Myös BACnet-liitäntä löytyy ja se käsitellään erillisessä asiakirjassa.
API-suunnittelu
API on suunniteltu käyttämällä alan standardimuotoja, kuten TCP/IP. HTTP, HTTPS ja JSON. Suunnittelu ei vaadi erityisiä tai patentoituja tekniikoita tai kirjastoja käytettäväksi ulkoisen ohjelman tai sovelluksen kehittämisessä. API on joustava, ja se voidaan konfiguroida ja ohjelmoida toimittamaan täsmälleen vaaditut tiedot ja tehokkaimmalla tavalla. Kunkin yllä olevan osion toiminnan yksityiskohdat käsitellään tämän oppaan seuraavissa osissa.
Ulkoinen viestintä
Tätä toimintoa käytetään toimittamaan hälytyksiä tai tapahtumatietoja ulkoiseen ohjelmaan, VMS-järjestelmään, palvelimeen jne., kun tapahtuma laukaistaan (asetetaan). Valinnaiset viestit voidaan myös ottaa käyttöön ilmoittamaan, kun tapahtuma tyhjennetään (nollataan). Tämä toimitus voidaan tehdä TCP/IP-pistorasiaan tai HTTP/S-palvelimeen reaaliajassa. On olemassa joukko konfiguroitavia protokollia, joissa on mukautettava sisältö. Todennus ja salaus ovat käytettävissä.
Sydämen syke
Sykeviestit lähetetään määritettävissä olevin väliajoin (eikä silloin, kun tapahtumat käynnistyvät), jotta voidaan todistaa live-/saatavuus. Niillä on samankaltaiset ominaisuudet kuin ulkoisella viestitoiminnolla, mutta ne on yleensä määritetty sisältämään yleisiä tilatietoja tietyn tapahtuman yksityiskohtien sijaan.
Tapahtumatiedot URL
Tämä toiminto on käytettävissä vain NDA:n alla, ja sitä tulisi käyttää vain, kun ulkoinen ohjelma vaatii pääsyn kaikkiin tapahtumaarvoihin, kynnyksiin ja tilalippuihin. Ulkoinen ohjelma hakee nämä tiedot yleensä pyynnöstä, mutta ei kovin usein. Tämä menetelmä sisältää yleensä jonkin verran latenssia, kun käytetään vaatimatonta kyselytaajuutta. Tyypilliset äänestysnopeudet vaihtelevat kerran minuutissa - kerran 5 sekunnissa absoluuttisen maksiminopeuden ollessa kerran sekunnissa. Tätä menetelmää voidaan käyttää myös lisätietojen hakemiseen, kun tapahtuma (hälytys) vastaanotetaan.
Ulkoisen viestinnän tiedot
Osa HALOsta web Interface Integration -ponnahdusikkuna mahdollistaa yhden kolmannen osapuolen yhteyden määrittämisen, jossa erilaisia arvoja voidaan lähettää TCP-etäpistorasiaan tai HTTP/HTTPS-palvelimeen. Paikkamerkkejä (tokeneita) käytetään live-arvojen lisäämiseen lähetettävään tekstiin. Vaikka tämän kanavan nimi on "Ulkoinen viestintä", sitä voidaan käyttää melkein mihin tahansa tarkoitukseen, joka vaatii reaaliaikaisia tapahtumalaukaisuja, jotka HALO toimittaa aktiivisesti. Tämä järjestely on varsin joustava, koska "Toiminnot" -kohdan valinnat määräävät, mitkä HALO-tapahtumat lähettävät tämän kanavan kautta.
HTTP-tilassa Set ja Reset Strings ovat URLs, jotka on syötettävä ja muotoiltava halutun kohdepalvelimen edellyttämällä tavalla. Käyttäjä- ja salasanakenttää voidaan käyttää todentamiseen. Katso HTTP-tila alla.
TCP-tilassa Set- ja Reset-merkkijonot ovat vain dataa yksittäisestä viestistä, joka lähetetään vastaanottavaan TCP-liitäntään. Ne voidaan muotoilla kohteen tarpeen mukaan. Kohde määritetään Osoite- ja Portti-kentissä. Katso TCP-tila alla.
Kummassakin tilassa näytetään viimeisimmän viestin tila, joka voi auttaa yhteyden tai muiden ongelmien korjaamisessa. Voit käyttää Toiminnot-ponnahdusikkunan Event TEST -painikkeita pakottaaksesi viestin:
Global On/Off for Set tai Reset on oltava päällä, jotta tämäntyyppiset viestit voidaan ottaa käyttöön. Nollausta ei usein käytetä, koska vain tapahtuman alkaminen on kiinnostavaa, mutta se voi vaihdella. Jokainen tapahtuma voi itsenäisesti määrittää, käyttääkö se Toiminnot-ponnahdusikkunassa joko Aseta- vai Palauta-viestiä. Silmämunapainikkeet näyttävät karkean kuvan siitä, mitä lähetetään avainsanan korvaamisen ja muotoilun jälkeen. Repeat Holdoff -toimintoa voidaan käyttää toistuvien viestien hillitsemiseen viivyttämällä ennen kuin uusi voidaan lähettää. Tämä tehdään itsenäisesti tapahtumakohtaisesti. HALOssa on sisäänrakennettu 15 sekunnin pitoaika tapahtumille, mikä estää tapahtumien nopean uudelleenkäynnistyksen. Jos haluat varmistaa, että minuutissa ei lähetetä enempää kuin 1 tyyppistä tapahtumaa, voit asettaa Repeat Holdoff -asetukseksi 60 (sekuntia).
Sydämen sykkeen yksityiskohdat
Heartbeat-lähetykset toimivat samalla tavalla kuin yllä, paitsi että Toiminnot-sivulla ei ole vuorovaikutusta. Sen sijaan Heartbeat-lähetys tapahtuu säännöllisesti Interval-kentässä määritetyllä tavalla. HTTP-tilassa Set- ja Reset-merkkijonot ovat URLs, jotka on syötettävä ja muotoiltava halutun kohdepalvelimen edellyttämällä tavalla. Käyttäjä- ja salasanakenttää voidaan käyttää todentamiseen. Katso HTTP-tila alla.
Vaikka Heartbeatin ensisijainen tarkoitus on todistaa HALO Smart Sensorin käyttöiästä etäsovellukselle, tätä viestiä voidaan käyttää myös valittujen antureiden tai tapahtumien nykyisten tilatietojen lähettämiseen. Exampyllä oleva le lähettää pitkän merkkijonoparametrin kanssa URL jotka sisältävät Halon nimen, suurimman osan anturiarvoista ja lopuksi Triggered=%ACTIVE%, jotka voivat olla tyhjiä tai luettelon tällä hetkellä käynnistetyistä tapahtumista.
HTTP (ja HTTPS) -tila
Ulkoiset viesti- ja sykemerkkijonot voivat olla http: tai https: URLs tarpeen mukaan. Kohdepalvelin voi syöttää polun ja parametrit tarpeen mukaan. Avainsanat, kuten %NAME% (HALO-laitteen nimi) tai %EID% (tapahtumatunnus), voidaan lisätä tarpeen mukaan, ja ne korvataan vastaavilla tiedoilla, kun viesti lähetetään. Luettelo yleisesti käytetyistä avainsanoista näytetään nopeaa käyttöä varten.
The URL polku voi sisältää avainsanoja sekä parametreja URL. Parametrit voivat olla NAME=VALUE -pareja tai JSON-objektia tai mukautettua muotoa kohdepalvelimen mukaan. EsimampUlkoisten viestien lessit sisältäisivät %EID%:n osoittamaan tapahtuman, joka käynnisti:
- 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 saattaa lisätä %ACTIVE% (tällä hetkellä käynnistetyt tapahtumat) tai anturin arvon:
- https://server.com/alive?location=%NAME%&Triggered=%ACTIVE%
- https://server.com/event?{“location”:”:%NAME%”,”NH3”:%SENSOR:NH3%}
Arvot %SENSOR:…% käyttävät nimiä, jotka löytyvät evtYYYYMMDD.csv-lokin oikeanpuoleisista anturisarakkeiden otsikoista files. Ne ovat tyypillisesti:
Jos kohdepalvelin suosii HTTP PUT- tai POST-protokollaa GET-pyyntöjen sijaan, voit liittää etuliitettä URL kanssa PUT: tai POST:. Voit itsenäisesti lisätä JSON-hyötykuorman, joka on suosittu monien palvelimien keskuudessa, lisäämällä avainsanan [JSONBODY] ja sen jälkeen JSON-muotoillun objektin. Esimampseuraavat:
PUT:https://server.com/event[JSONBODY]{"sijainti":"%NAME%","tapahtuma":"%EID%"}
The URL tukee tyypillisiä IP-osoite (ja IPv6) sekä portti- ja käyttäjän salasanavaihtoehtoja, tai voit tarvittaessa käyttää Käyttäjä- ja Salasana-kenttiä kohdepalvelimena todennusmenetelmille, kuten Basic tai Digest:
https://username:password@123.321.123.321:9876/event…
TCP-tila
Ulkoiset viestit ja sykemerkkijonot ovat vain tietoja varten, koska Osoite- ja Portti-kentät määrittävät kohteen. Osoite tukee nimiä, IPv4 ja IPv6.
Merkkijono voidaan muotoilla kuten yllä kuvatut HTTP-sanomien dataosat tai kohdepalvelimen vaatimalla tavalla.
ExampUlkoisten viestien lessit sisältäisivät %EID%:n osoittamaan tapahtuman, joka käynnisti:
sijainti=%NAME%, tapahtuma=%EID%
{"sijainti":":%NAME%","tapahtuma":"%EID%"}
Examples for Heartbeat saattaa lisätä %ACTIVE% (tällä hetkellä käynnistetyt tapahtumat) tai anturin arvon:
location=%NAME%&Triggered=%ACTIVE%
{"sijainti":":%NAME%","NH3":%SENSOR:NH3%}
"Integration Set"- ja "Integration Reset" -sarakkeiden valintaruudut määrittävät, mitkä tapahtumat käynnistävät lähetyksen. Lisätietoja tapahtumien ja toimintojen asettamisesta on saatavilla HALO-järjestelmänvalvojan oppaassa.
JSON-tapahtumaviestien toimitus
Jotkut kehittäjät haluavat vastaanottaa tapahtumatiedot, jotka on muotoiltu alan standardinmukaiseksi nimetyksi JSON-muodoksi pelkän ASCII-tekstin sijaan, koska edellinen on luotettavampi ja helpompi jäsentää. HALOssa web -sivun Viestit-välilehdellä voit toimittaa JSON-viestejä External Messaging -asetuksissa "Set String" ja "Reset String" sekä "Heartbeat" -viestissä.
Examples:
"Ulkoiset viestit" -asetusten merkkijono:
{ "laite":"%NAME%", "tapahtuma":"%EID%", "hälytys":"kyllä" }
Tämä lähettää yksittäisen TCP- tai UDP JSON -sanoman määritettyyn palvelimeen, joka raportoi ystävällisen laitteen nimen, tapahtuman nimen ja sen, että se on juuri alkanut.
"Ulkoisten viestien" asetusten palautusmerkkijono:
{ "laite":"%NAME%", "tapahtuma":"%EID%", "hälytys":"ei" }
Tämä lähettää yksittäisen TCP- tai UDP JSON -sanoman määritettyyn palvelimeen, joka raportoi ystävällisen laitteen nimen, tapahtuman nimen ja sen, että tila on nyt pysähtynyt.
"Heartbeat" -viesti:
{ "laite":"%NAME%", "elossa":"%DATE% %TIME%" }
Tämä lähettää määräajoin määritetylle palvelimelle TCP- tai UDP JSON -sanoman, joka ilmoittaa, että HALO on elossa ilmoitettuna aikana.
Asiakirjat / Resurssit
 |
Ohjelmiston HALO Smart Sensor API -perusohjelmisto [pdfKäyttöopas HALO Smart Sensor API -perusohjelmisto |
