Szoftver HALO Smart Sensor API alapszoftver
Előre
Ez a dokumentum a Halo Smart Sensor szolgáltatásainak csoportját írja le, amelyek együttes nevén BASIC API vagy alkalmazásprogramozási felület. Ez a vita azoknak a programozóknak vagy integrátoroknak szól, akik egy vagy több HALO intelligens érzékelő (HALO) integrálása iránt érdeklődnek harmadik féltől származó (nem IPVideo) szoftverkomponensekkel vagy rendszerekkel. Általánosságban elmondható, hogy a HALO API célja az információ hatékony átvitele a HALO-tól a hagyományos Ethernet hálózaton keresztül a külső programhoz. E cél elérése érdekében az API három részre oszlik: eseményvezérelt socket kapcsolat, szívverés socket kapcsolat és eseményadatok. URL. A BACnet interfész is jelen van, és külön dokumentumban szerepel.
API-tervezés
Az API-t iparági szabványos formátumok, például TCP/IP felhasználásával tervezték. HTTP, HTTPS és JSON. A tervezés nem igényel különleges vagy szabadalmaztatott technikákat vagy könyvtárakat a külső program vagy alkalmazás fejlesztése során. Az API rugalmas, és úgy konfigurálható és programozható, hogy pontosan a szükséges adatokat és a leghatékonyabb módon szállítsa. A fenti szakaszok működésének részleteit az útmutató következő részei ismertetik.
Külső üzenetküldés
Ez a lehetőség riasztások vagy riasztások és eseményadatok továbbítására szolgál egy külső programhoz, VMS-rendszerhez, szerverhez stb., amikor egy esemény aktiválódik (be van állítva). Opcionális üzenetek is engedélyezhetők, hogy jelezzék, ha egy esemény törlődik (reset). Ez a kézbesítés valós időben történhet TCP/IP socketre vagy HTTP/S szerverre. Számos konfigurálható protokoll létezik testreszabható tartalommal. Hitelesítés és titkosítás elérhető.
Szívverés
A szívverési üzenetek konfigurálható időközönként kerülnek elküldésre (ahelyett, hogy az események aktiválódnak), hogy igazolják az élő/rendelkezésre állást. A külső üzenetkezeléshez hasonló képességekkel rendelkeznek, de általában úgy vannak beállítva, hogy általános állapotinformációkat tartalmazzanak, nem pedig egy adott esemény részleteit.
Eseményadatok URL
Ez a lehetőség csak NDA keretében érhető el, és csak akkor használható, ha a külső program hozzáférést igényel az összes eseményértékhez, küszöbértékhez és állapotjelzőhöz. Ezeket az adatokat általában kérésre lekéri a külső program, de nem túl nagy gyakorisággal. Ez a módszer általában némi késéssel jár, ha szerény lekérdezési arányt használnak. A tipikus lekérdezési arány percenként egyszeri és 5 másodpercenkénti egyszeri tartományban van, az abszolút maximális arány pedig másodpercenként egyszer. Ez a módszer használható további támogató adatok lekérésére is, amikor esemény (riasztás) érkezik.
Külső üzenetküldés részletei
A HALO egy része web Az interfész Integrációs előugró ablak egyetlen harmadik féltől származó kapcsolat konfigurálását teszi lehetővé, ahol különféle értékek küldhetők egy távoli TCP-foglalathoz vagy egy HTTP/HTTPS-kiszolgálóhoz. Helytartók (token) arra szolgálnak, hogy élő értékeket illesszenek be a továbbított szövegbe. Bár „Külső üzenetküldés” felirattal van ellátva, ez a csatorna szinte minden olyan célra használható, amely valós idejű eseményindítókat igényel, amelyeket a HALO aktívan szállít. Ez az elrendezés meglehetősen rugalmas, mivel a „Műveletek” menüpontban található választások határozzák meg, hogy mely HALO események továbbíthatók ezen a csatornán.
HTTP módban a Set és Reset String a URLs, amelyeket a kívánt célszervernek megfelelően kell beírni és formázni. A Felhasználó és Jelszó mező használható a hitelesítéshez. Lásd alább a HTTP módot.
TCP módban a Set és Reset String csak a fogadó TCP socketnek küldött egyetlen üzenet adatai. A célhely igényei szerint formázhatók. A célállomás a Cím és a Port mezőben van megadva. Lásd alább a TCP módot.
Mindkét módban a legutóbbi üzenet állapota jelenik meg, amely segíthet a csatlakozási vagy egyéb problémák megoldásában. Használhatja a Műveletek előugró ablak Event TEST gombjait egy üzenet kényszerítéséhez:
Az ilyen típusú üzenetek engedélyezéséhez a Beállítás vagy Visszaállítás Globális Be/Ki beállítását Be kell kapcsolni. A visszaállítást gyakran nem használják, mert csak az esemény kezdete érdekes, de ez változhat. Minden esemény önállóan meghatározhatja, hogy a Műveletek előugró ablakban a Beállítás vagy a Visszaállítás üzenetet használja-e. A szemgolyó gombjai a kulcsszócsere és a formázás után elküldött adatok durva megjelenítését jelzik. A Repeat Holdoff funkció a gyakori üzenetek visszaszorítására használható úgy, hogy késlelteti egy másik üzenet küldését. Ez eseményenként függetlenül történik. A HALO beépített 15 másodperces tartási idővel rendelkezik az eseményekhez, hogy megakadályozza az események gyors újraindítását. Ha azt szeretné, hogy percenként legfeljebb 1 esemény kerüljön elküldésre, a Repeat Holdoff értéket 60 (másodperc) értékre állíthatja.
A szívverés részletei
A Heartbeat adások a fentiekhez hasonló módon működnek, kivéve, hogy nincs interakció a Műveletek oldallal. Ehelyett a Heartbeat átvitel rendszeresen megtörténik az Intervallum mezőben konfigurált módon. HTTP módban a Set és Reset String a URLs, amelyeket a kívánt célszervernek megfelelően kell beírni és formázni. A Felhasználó és Jelszó mező használható a hitelesítéshez. Lásd alább a HTTP módot.
Míg a Heartbeat elsődleges célja a HALO Smart Sensor élettartamának igazolása egy távoli alkalmazás számára, ez az üzenet felhasználható kiválasztott érzékelők vagy aktuális eseményállapot-információk továbbítására is. Az exampA fenti le egy hosszú karakterlánc-paramétert küld a URL amelyek tartalmazzák a Halo nevét, az érzékelőértékek többségét, és végül a Triggered=%ACTIVE% értéket, amely lehet üres, vagy az aktuálisan kiváltott események listája.
HTTP (és HTTPS) mód
A külső üzenetküldési és szívverési karakterláncok lehetnek http: vagy https: URLs szükség szerint. Az elérési út és a paraméterek szükség szerint megadhatók a célszerver által. Az olyan kulcsszavak, mint a %NAME% (HALO eszköznév) vagy a %EID% (eseményazonosító), szükség szerint beilleszthetők, és az üzenet elküldésekor a megfelelő adatokkal helyettesíthetők. Gyors áttekintés céljából megjelenik a gyakran használt kulcsszavak listája.
A URL Az elérési út kulcsszavakat és paramétereket tartalmazhat URL. A paraméterek lehetnek NAME=VALUE párok vagy JSON-objektum, vagy egyéni formátum a célkiszolgálótól függően. VoltampA külső üzenetkezeléshez tartozó lesek tartalmazzák a %EID%-ot, hogy jelezzék azt az eseményt, amely kiváltotta:
- https://server.com/event/%NAME%/%EID%
- https://server.com/event?location=%NAME%&event=%EID%
- https://server.com/event?{“location”:”:%NAME%”,”event”:”%EID%”}
ExampA les for Heartbeat hozzáadhat %ACTIVE% értéket (jelenleg aktivált események) vagy egy szenzorértéket:
- https://server.com/alive?location=%NAME%&Triggered=%ACTIVE%
- https://server.com/event?{“location”:”:%NAME%”,”NH3”:%SENSOR:NH3%}
A %SENSOR:…% értékek az evtYYYYMMDD.csv napló jobb oldali érzékelő oszlopfejlécében található neveket használják files. Ezek jellemzően:
Ha a célszerver a HTTP PUT vagy POST protokollt részesíti előnyben a GET kérések helyett, akkor a URL PUT: vagy POST:. Függetlenül is hozzáadhat egy JSON hasznos adatot, amely sok kiszolgálón népszerű, ha hozzáadja a [JSONBODY] kulcsszót, majd egy JSON formátumú objektumot. Voltample:
PUT:https://server.com/event[JSONBODY]{"hely":"%NAME%","esemény":"%EID%"}
A URL támogatja a tipikus IP-címet (és IPv6-ot), valamint a port- és felhasználói jelszó-beállításokat, vagy használhatja a Felhasználó és a Jelszó mezőket, ha szükséges, célszerverként olyan hitelesítési módszerekhez, mint a Basic vagy a Digest:
https://username:password@123.321.123.321:9876/event…
TCP mód
A külső üzenetküldés és a szívverés karakterláncai csak adatokra szolgálnak, mivel a Cím és a Port mezők határozzák meg a célállomást. A cím támogatja a neveket, az IPv4-et és az IPv6-ot.
A karakterlánc formázható a fent leírt HTTP-üzenetek adatrészeihez hasonlóan, vagy a célszerver által megkövetelt módon.
ExampA külső üzenetkezeléshez tartozó lesek tartalmazzák a %EID%-ot, hogy jelezzék azt az eseményt, amely kiváltotta:
location=%NAME%,esemény=%EID%
{"hely":":%NAME%","esemény":"%EID%"}
ExampA les for Heartbeat hozzáadhat %ACTIVE% értéket (jelenleg aktivált események) vagy egy szenzorértéket:
location=%NAME%&Triggered=%ACTIVE%
{"hely":":%NAME%","NH3":%SENSOR:NH3%}
Az „Integrációs készlet” és az „Integráció visszaállítása” oszlopban lévő jelölőnégyzetek határozzák meg, hogy mely események indítják el a küldést. Az események és műveletek beállításáról bővebben a HALO rendszergazdai útmutatójában olvashat.
JSON-eseményüzenetek kézbesítése
Egyes fejlesztők szívesebben fogadják az eseményadatokat iparági szabványnak megfelelő öncímkézett JSON-formátumban, nem pedig egyszerű ASCII-szövegként, mivel az előbbi megbízhatóbb és könnyebben értelmezhető. A HALO-n web oldalon az „Üzenetek” lapon adhat meg JSON-üzeneteket a „Külső üzenetküldés” beállításaiban „Set String” és „Reset String”, valamint a „Heartbeat” „Message”.
Examples:
„Külső üzenetküldés” beállítási karakterlánc:
{ „eszköz”:”%NAME%”, „esemény”:”%EID%”, „riasztás”:”igen” }
Ez egyetlen TCP- vagy UDP JSON-üzenetet küld a megadott kiszolgálónak, jelezve az eszköz barátságos nevét, az esemény nevét és azt, hogy éppen most indult.
„Külső üzenetküldés” beállításai Karakterlánc visszaállítása:
{ „eszköz”:”%NAME%”, „esemény”:”%EID%”, „riasztás”:”nem” }
Ez egyetlen TCP- vagy UDP JSON-üzenetet küld a megadott kiszolgálónak, amely jelenti az eszköz barátságos nevét, az esemény nevét, és azt, hogy a feltétel leállt.
„Szívverés” üzenet:
{ „eszköz”:”%NAME%”, „élő”:”%DATE% %TIME%” }
Ez időnként TCP- vagy UDP JSON-üzenetet küld a megadott szervernek, jelezve, hogy a HALO a jelzett időpontban életben van.
Dokumentumok / Források
 |
Szoftver HALO Smart Sensor API alapszoftver [pdf] Felhasználói útmutató HALO Smart Sensor API alapszoftver |
