Programaro de HALO Smart Sensor API Baza Programaro
Antaŭen
Ĉi tiu dokumento priskribas la grupon de instalaĵoj de la Halo Smart Sensor konata kolektive kiel la BASIC API, aŭ Application Programming Interface. Ĉi tiu diskuto estas destinita por uzo de programistoj aŭ integrigantoj, kiuj interesiĝas pri integri unu aŭ pli da HALO Smart Sensors (HALO) kun triaj (ne-IPVideo) programaj komponantoj aŭ sistemoj. Ĝenerale, la HALO API estas celita transdoni informojn efike de HALO tra konvencia Eterreto reto al la ekstera programo. Por plenumi ĉi tiun celon, la API estas dividita en tri sekciojn: Event Driven Socket Connection, Heartbeat Socket Connection kaj Event Datumoj URL. BACnet-interfaco ankaŭ ĉeestas kaj kovrita en aparta dokumento.
API-Dezajno
La API estas desegnita per industriaj normaj formatoj kiel TCP/IP. HTTP, HTTPS kaj JSON. La dezajno ne postulas iujn ajn specialajn aŭ proprietajn teknikojn aŭ bibliotekojn esti uzataj en la evoluo de la ekstera programo aŭ aplikaĵo. La API estas fleksebla kaj povas esti agordita kaj programita por liveri precize la necesajn datumojn kaj en la plej efika maniero. La detaloj pri la funkciado de ĉiu el la supraj sekcioj estas kovritaj en la sekvaj sekcioj de ĉi tiu gvidilo.
Ekstera Mesaĝado
Ĉi tiu instalaĵo estas uzata por liveri atentigojn aŭ alarmojn kaj Eventajn datumojn al ekstera programo, VMS-sistemo, servilo, ktp. kiam Evento estas ekigita (estas fiksita). Laŭvolaj mesaĝoj ankaŭ povas esti ebligitaj por signali kiam Evento malpleniĝas (estas rekomencigita). Ĉi tiu livero povas fari al TCP/IP-ingo aŭ HTTP/S-servilo en reala tempo. Estas gamo da agordeblaj protokoloj kun agordebla enhavo. Aŭtentikigo kaj ĉifrado estas disponeblaj.
Korbato
Korbatmesaĝoj estas senditaj je agordebla intervalo (anstataŭ kiam Eventoj estas ekigitaj) por provizi pruvon de viva/havebleco. Ili havas similan gamon da kapabloj kiel Ekstera Mesaĝado sed tipe estus agordita por enhavi ĝeneralajn ŝtatinformojn prefere ol detaloj pri speciala okazaĵo.
Eventaj Datumoj URL
Ĉi tiu instalaĵo estas nur havebla sub NDA kaj devus esti uzata nur kiam la ekstera programo postulas aliron al iuj kaj ĉiuj Eventaj valoroj, sojloj kaj ŝtataj flagoj. Ĉi tiuj datumoj estas ĝenerale prenitaj laŭ postulo de la ekstera programo sed ne ĉe tre alta frekvenco. Tiu metodo ĝenerale altiras iom da latenteco kiam modesta balota indico estas uzita. Tipaj balottarifoj varias de unufoje je minuto ĝis unufoje je 5 sekundoj kun absoluta maksimuma indico de unufoje je sekundo. Ĉi tiu metodo ankaŭ povas esti uzata por preni pliajn subtenajn datumojn kiam Evento (averto) estas ricevita.
Detaloj pri Eksteraj Mesaĝoj
Sekcio de la HALO web interfaco Integriga ŝprucfenestro provizas agordon de ununura tria-partia konekto kie diversaj valoroj povas esti senditaj al fora TCP-ingo aŭ HTTP/HTTPS-servilo. Lokteniloj (ĵetonoj) estas uzataj por enmeti vivajn valorojn en la transdonitan tekston. Kvankam etikedita "Ekstera Mesaĝado", ĉi tiu kanalo povas esti uzata por preskaŭ ajna celo postulante realtempajn Eventajn ekigilojn, aktive liverita de HALO. Ĉi tiu aranĝo estas sufiĉe fleksebla ĉar elektoj sur la "Agoj" determinas kiuj HALO-Okazaĵoj transdonas tra ĉi tiu kanalo.
En HTTP-reĝimo, la Agordu kaj Restarigi Ŝnurojn estas la URLs, kiuj devas esti enmetitaj kaj formatitaj laŭ la bezono de la dezirata celservilo. Kampo de Uzanto kaj Pasvorto povas esti uzata por aŭtentigo. Vidu HTTP-reĝimon sube.
En TCP-reĝimo, la Agordu kaj Restarigi Ŝnurojn estas nur la datumoj de ununura mesaĝo kiu estas sendita al la ricevanta TCP-ingo. Ili povas esti formatitaj laŭbezone de la celo. La celo estas specifita en la kampoj Adreso kaj Haveno. Vidu TCP-Reĝimon sube.
Por ambaŭ reĝimoj, stato de la plej lastatempa mesaĝo montriĝas, kio povas helpi ripari konekton aŭ aliajn problemojn. Vi povus uzi la butonojn de Event TEST en la ŝprucfenestron Agoj por devigi mesaĝon:
Tutmonda Enŝaltita/Malŝaltita por Agordi aŭ Restarigi devas esti Enŝaltita por ebligi tiujn specojn de mesaĝoj. Restarigi ofte ne estas uzata ĉar nur la komenco de Evento interesas, sed tio povas varii. Ĉiu Evento povas sendepende specifi ĉu ĝi uzos aŭ la Agordi aŭ la Restarigi mesaĝon sur la Agoj ŝprucfenestron. La okulglobaj butonoj montros malglatan reprezenton de tio, kio estas sendita post ŝlosilvortaj anstataŭoj kaj formatado. Repeat Holdoff povas esti uzata por akceli oftajn mesaĝojn prokrastante antaŭ ol alia povas esti sendita. Ĉi tio estas farita sendepende per Evento. HALO havas enkonstruitan tenan tempon por eventoj de 15 sekundoj por malhelpi rapidan reeksigon de Eventoj. Se vi volis certigi, ke ne pli ol 1 Evento de ia tipo estas sendita por minuto, vi povus agordi Ripeti Holdoff al 60 (sekundoj).
Korbataj detaloj
La transsendoj de Heartbeat funkcias simile al ĉi-supraj krom ke ne ekzistas interago kun la paĝo Agoj. Anstataŭe, la transdono de Heartbeat okazas regule kiel agordita kun la kampo Intervalo, En HTTP-reĝimo, la Agordu kaj Restarigi Kordojn estas la URLs, kiuj devas esti enmetitaj kaj formatitaj laŭ la bezono de la dezirata celservilo. Kampo de Uzanto kaj Pasvorto povas esti uzata por aŭtentigo. Vidu HTTP-reĝimon sube.
Dum la ĉefa celo de la Korbato estas provizi pruvon de vivo de HALO Smart Sensor al fora aplikaĵo, ĉi tiu mesaĝo ankaŭ povas esti uzata por transdoni elektitajn sensilojn aŭ aktualajn Okazajn statonformojn. La eksample supre sendas longan ĉenparametron kun la URL kiuj inkluzivas la Halo-nomon, plimulton de sensilvaloroj, kaj laste Triggered=%ACTIVE% kiu povus esti malplena aŭ listo de nuntempe ekigitaj Eventoj.
HTTP (kaj HTTPS) Reĝimo
Eksteraj Mesaĝoj kaj Korbatoj povas esti http: aŭ https: URLs laŭbezone. Vojo kaj parametroj povas esti enigitaj laŭbezone de la celservilo. Ŝlosilvortoj kiel %NAME% (HALO-aparatonomo) aŭ %EID% (Eventa id) povas esti enmetitaj laŭbezone kaj estos anstataŭigitaj per respektivaj datumoj kiam la mesaĝo estas sendita. Listo de ofte uzataj ŝlosilvortoj estas montrita por rapida referenco.
La URL vojo povas enhavi ŝlosilvortojn same kiel la parametrojn al la URL. La parametroj povus esti NAME=VALUE-paroj aŭ JSON-objekto, aŭ laŭmenda formato depende de la celservilo. Ekzamplesoj por Ekstera Mesaĝado inkludus %EID% por indiki la Eventon kiu ekigis:
- https://server.com/event/%NAME%/%EID%
- https://server.com/event?location=%NAME%&event=%EID%
- https://server.com/event?{“location”:”:%NAME%”,”event”:”%EID%”}
Examplesoj por Heartbeat povus aldoni %ACTIVE% (nuntempe ekigitaj Eventoj) aŭ sensilvaloron:
- https://server.com/alive?location=%NAME%&Triggered=%ACTIVE%
- https://server.com/event?{“location”:”:%NAME%”,”NH3”:%SENSOR:NH3%}
La %SENSOR:...% valoroj uzas la nomojn trovitajn en la dekstraj sensilaj kolumnotitoloj en evtYYYYMMDD.csv-protokolo files. Ili estas tipe:
Se la celservilo preferas HTTP PUT aŭ POST anstataŭ GET petojn, vi povas prefiksi la URL kun PUT: aŭ POST:. Sendepende, vi povas aldoni JSON-utilan ŝarĝon, kiu estas populara ĉe multaj serviloj, aldonante la ŝlosilvorton [JSONBODY] sekvita de JSON formatita objekto. Ekzample:
MENU:https://server.com/event[JSONBODY]{“loko”:”%NAME%”,”event”:”%EID%”}
La URL subtenas tipan IP-adreson (kaj IPv6) kaj eblojn de haveno kaj uzant-pasvorto, aŭ vi povas uzi la kampojn Uzanto kaj Pasvorto se necese estu la celservilo por aŭtentikigmetodoj kiel Basic aŭ Digest:
https://username:password@123.321.123.321:9876/event…
TCP-reĝimo
Eksteraj Mesaĝoj kaj Korbataj kordoj estas nur por datumoj ĉar la kampoj Adreso kaj Haveno specifas la celon. La Adreso subtenas nomojn, IPv4 kaj IPv6.
La ĉeno povas esti formatita kiel la datumpartoj de HTTP-mesaĝoj priskribitaj supre, aŭ kiel postulite de la celservilo.
Examplesoj por Ekstera Mesaĝado inkludus %EID% por indiki la Eventon kiu ekigis:
loko=%NAME%,evento=%EID%
{“location”:”:%NAME%”,”okazaĵo”:”%EID%”}
Examplesoj por Heartbeat povus aldoni %ACTIVE% (nuntempe ekigitaj Eventoj) aŭ sensilvaloron:
loko=%NAME%&Deĉenigita=%ACTIVE%
{“location”:”:%NAME%”,”NH3”:%SENSOR:NH3%}
Markobutonoj en la kolumnoj "Integriga Aro" kaj "Integra Restarigi" determinas kiuj Eventoj ekigas sendon. Pli pri la aranĝo de Eventoj kaj Agoj haveblas en la Gvidilo de Administranto de HALO.
Livero de JSON-Eventaj Mesaĝoj
Iuj programistoj preferas ricevi Eventajn datumojn formatitajn kiel industria norma mem-etikedita JSON prefere ol simpla ASCII-teksto ĉar la unua estas pli fidinde kaj pli facile analizita. Sur la HALO web paĝo "Mesaĝado" langeto, vi povas provizi JSON-mesaĝojn en "Ekstera Mesaĝado" agordoj "Agordu Ŝnuron" kaj "Restarigi Ŝnuron" kaj en la "Korbato" "Mesaĝo".
Examples:
Agordoj "Ekstera Mesaĝado" Agordu Ŝnuron:
{ “device”:”%NAME%”, “event”:”%EID%”, “alarm”:”jes” }
Ĉi tio sendos ununuran TCP aŭ UDP JSON-mesaĝon al la specifita servilo raportante la amikan aparatnomon, eventonomon kaj ke ĝi ĵus komenciĝis.
"Ekstera Mesaĝado" Agordoj Restarigi Ŝnuron:
{ “device”:”%NAME%”, “event”:”%EID%”, “alarm”:”ne”}
Ĉi tio sendos ununuran TCP aŭ UDP JSON-mesaĝon al la specifita servilo raportante la amikan aparatnomon, eventonomon kaj ke la kondiĉo nun ĉesis.
Mesaĝo "Korbato":
{ “device”:”%NAME%”, “alive”:”%DATE% %TIME%” }
Ĉi tio periode sendos TCP aŭ UDP JSON-mesaĝon al la specifita servilo raportante ke la HALO vivas en la indikita tempo.
Dokumentoj/Rimedoj
 |
Programaro de HALO Smart Sensor API Baza Programaro [pdf] Uzantogvidilo HALO Smart Sensor API Baza Programaro |
