Pangunahing Software ng HALO Smart Sensor API ng Software
Pasulong
Inilalarawan ng dokumentong ito ang pangkat ng mga pasilidad ng Halo Smart Sensor na kilala bilang BASIC API, o Application Programming Interface. Ang talakayang ito ay inilaan para sa paggamit ng mga programmer o integrator na interesadong isama ang isa o higit pang HALO Smart Sensors (HALOs) sa 3rd party (non-IPVideo) na mga bahagi o system ng software. Sa pangkalahatan, ang HALO API ay nilayon na maglipat ng impormasyon mula sa HALO sa isang kumbensyonal na Ethernet network patungo sa panlabas na programa. Para magawa ang layuning ito, nahahati ang API sa tatlong seksyon: Event Driven Socket Connection, Heartbeat Socket Connection, at Event Data URL. Ang interface ng BACnet ay naroroon din at sakop sa isang hiwalay na dokumento.
Disenyo ng API
Idinisenyo ang API gamit ang mga standard na format ng industriya gaya ng TCP/IP. HTTP, HTTPS, at JSON. Ang disenyo ay hindi nangangailangan ng anumang espesyal o pagmamay-ari na mga diskarte o aklatan na gagamitin sa pagbuo ng panlabas na programa o aplikasyon. Ang API ay nababaluktot at maaaring i-configure at i-program upang maihatid ang eksaktong data na kinakailangan at sa pinakamabisang paraan. Ang mga detalye ng pagpapatakbo ng bawat isa sa mga seksyon sa itaas ay sakop sa mga sumusunod na seksyon ng gabay na ito.
Panlabas na Pagmemensahe
Ginagamit ang pasilidad na ito upang maghatid ng mga alerto o alarma at data ng Kaganapan sa isang panlabas na programa, VMS system, server, atbp. kapag ang isang Kaganapan ay na-trigger (naitakda). Ang mga opsyonal na mensahe ay maaari ding paganahin upang magsenyas kapag ang isang Kaganapan ay na-clear (na-reset). Ang paghahatid na ito ay maaaring gawin sa isang TCP/IP socket o HTTP/S server nang real time. Mayroong isang hanay ng mga na-configure na protocol na may mga napapasadyang nilalaman. Available ang pagpapatunay at pag-encrypt.
Tibok ng puso
Ang mga mensahe ng heartbeat ay ipinapadala sa isang na-configure na pagitan (sa halip na kapag na-trigger ang Mga Kaganapan) upang magbigay ng patunay ng live/availability. Ang mga ito ay may katulad na hanay ng mga kakayahan tulad ng External Messaging ngunit karaniwang iko-configure upang maglaman ng pangkalahatang impormasyon ng estado sa halip na mga detalye tungkol sa isang partikular na kaganapan.
Data ng Kaganapan URL
Ang pasilidad na ito ay magagamit lamang sa ilalim ng isang NDA at dapat lamang gamitin kapag ang panlabas na programa ay nangangailangan ng access sa anuman at lahat ng mga halaga ng Kaganapan, mga limitasyon, at mga flag ng estado. Ang data na ito ay karaniwang kinukuha kapag hinihingi ng panlabas na programa ngunit hindi sa napakataas na dalas. Ang pamamaraang ito ay karaniwang nagkakaroon ng ilang latency kapag ginamit ang isang katamtamang rate ng botohan. Ang mga karaniwang rate ng botohan ay mula sa isang beses bawat minuto hanggang isang beses bawat 5 segundo na may ganap na maximum na rate ng isang beses bawat segundo. Ang paraang ito ay maaari ding gamitin upang kunin ang karagdagang sumusuportang data kapag natanggap ang isang Kaganapan (alerto).
Mga detalye ng External Messaging
Isang seksyon ng HALO web interface Integration popup ay nagbibigay para sa pagsasaayos ng isang solong 3rd party na koneksyon kung saan ang iba't ibang mga halaga ay maaaring ipadala sa isang remote na TCP socket o isang HTTP/HTTPS server. Ang mga place holder (token) ay ginagamit upang magpasok ng mga live na halaga sa ipinadalang teksto. Bagama't may label na "External Messaging," magagamit ang channel na ito para sa halos anumang layunin na nangangailangan ng mga real time na trigger ng Event, na aktibong inihahatid ng HALO. Ang pagsasaayos na ito ay medyo nababaluktot dahil tinutukoy ng mga seleksyon sa "Mga Pagkilos" kung aling Mga Kaganapang HALO ang ipinapadala sa pamamagitan ng channel na ito.
Sa HTTP mode, ang Set at Reset Strings ay ang URLs na dapat ipasok at i-format ayon sa hinihingi ng nais na patutunguhang server. Maaaring gamitin ang field ng User at Password para sa pagpapatunay. Tingnan ang HTTP mode sa ibaba.
Sa TCP mode, ang Set at Reset Strings ay data lamang ng isang mensahe na ipinadala sa tumatanggap na TCP socket. Maaaring i-format ang mga ito kung kinakailangan ng patutunguhan. Tinukoy ang patutunguhan sa mga field ng Address at Port. Tingnan ang TCP Mode sa ibaba.
Para sa alinmang mode, ipinapakita ang status mula sa pinakabagong mensahe na maaaring makatulong sa pag-aayos ng koneksyon o iba pang mga isyu. Maaari mong gamitin ang mga pindutan ng Pagsubok sa Kaganapan sa popup ng Mga Pagkilos upang pilitin ang isang mensahe:
Ang Global On/Off para sa I-set o Reset ay dapat naka-on para paganahin ang mga uri ng mensaheng iyon. Madalas na hindi ginagamit ang pag-reset dahil ang simula lamang ng isang Kaganapan ang interesado, ngunit maaaring mag-iba iyon. Ang bawat Kaganapan ay maaaring independiyenteng tukuyin kung gagamitin nito ang alinman sa Set o ang Reset na mensahe sa popup na Mga Pagkilos. Ang mga pindutan ng eyeball ay magpapakita ng isang magaspang na representasyon ng kung ano ang ipinadala pagkatapos ng mga pagpapalit at pag-format ng keyword. Maaaring gamitin ang Repeat Holdoff upang i-throttle ang mga madalas na mensahe sa pamamagitan ng pagkaantala bago maipadala ang isa pa. Iisa itong ginagawa sa bawat Kaganapan. Ang HALO ay may built-in na oras ng pag-hold para sa mga kaganapan na 15 segundo upang maiwasan ang mabilis na pag-retrigger ng Mga Kaganapan. Kung gusto mong matiyak na hindi hihigit sa 1 Kaganapan ng isang uri ang ipinadala bawat minuto, maaari mong itakda ang Repeat Holdoff sa 60 (segundo).
Mga detalye ng tibok ng puso
Ang mga pagpapadala ng Heartbeat ay gumagana sa katulad na paraan sa itaas maliban na walang pakikipag-ugnayan sa pahina ng Mga Pagkilos. Sa halip, ang pagpapadala ng Heartbeat ay nangyayari sa isang regular na batayan gaya ng na-configure sa Interval field, Sa HTTP mode, ang Set at Reset Strings ay ang URLs na dapat ipasok at i-format ayon sa hinihingi ng nais na patutunguhang server. Maaaring gamitin ang field ng User at Password para sa pagpapatunay. Tingnan ang HTTP mode sa ibaba.
Bagama't ang pangunahing layunin ng Heartbeat ay magbigay ng patunay ng buhay ng isang HALO Smart Sensor sa isang malayuang application, ang mensaheng ito ay maaari ding gamitin upang magpadala ng mga napiling sensor o kasalukuyang impormasyon ng estado ng Event. Ang example sa itaas ay nagpapadala ng isang mahabang string parameter na may URL na kinabibilangan ng pangalan ng Halo, karamihan ng mga value ng sensor, at panghuli Triggered=%ACTIVE% na maaaring walang laman o isang listahan ng kasalukuyang na-trigger na Mga Kaganapan.
HTTP (at HTTPS) Mode
Ang mga string ng External Messaging at Heartbeat ay maaaring http: o https: URLs kung kinakailangan. Maaaring ipasok ang landas at mga parameter kung kinakailangan ng patutunguhang server. Maaaring ipasok ang mga keyword tulad ng %NAME% (HALO device name) o %EID% (Event id) kung kinakailangan at papalitan ng kaukulang data kapag naipadala na ang mensahe. Ang isang listahan ng mga karaniwang ginagamit na keyword ay ipinapakita para sa mabilis na sanggunian.
Ang URL path ay maaaring maglaman ng mga keyword pati na rin ang mga parameter sa URL. Ang mga parameter ay maaaring NAME=VALUE pares o isang JSON object, o isang custom na format depende sa destination server. Halamples para sa External Messaging ay magsasama ng %EID% upang isaad ang Kaganapang nag-trigger:
- 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 ay maaaring magdagdag ng %ACTIVE% (kasalukuyang na-trigger na Mga Kaganapan) o isang halaga ng sensor:
- https://server.com/alive?location=%NAME%&Triggered=%ACTIVE%
- https://server.com/event?{“location”:”:%NAME%”,”NH3”:%SENSOR:NH3%}
Ginagamit ng mga value na %SENSOR:…% ang mga pangalan na makikita sa mga heading ng column ng kanang sensor sa evtYYYYMMDD.csv log files. Sila ay karaniwang:
Kung mas gusto ng destination server ang HTTP PUT o POST sa halip na GET na mga kahilingan, maaari mong i-prefix ang URL may PUT: o POST:. Mag-isa, maaari kang magdagdag ng JSON payload na sikat sa maraming server sa pamamagitan ng pagdaragdag ng [JSONBODY] na keyword na sinusundan ng JSON formatted object. Halample:
PUT:https://server.com/event[JSONBODY]{“location”:”%NAME%”,”event”:”%EID%”}
Ang URL sumusuporta sa tipikal na IP address (at IPv6) at mga opsyon sa port at user-password, o maaari mong gamitin ang mga field ng User at Password kung kinakailangan ang patutunguhang server para sa mga paraan ng pagpapatunay tulad ng Basic o Digest:
https://username:password@123.321.123.321:9876/event…
TCP Mode
Ang mga string ng External Messaging at Heartbeat ay para lamang sa data dahil tinutukoy ng mga field ng Address at Port ang patutunguhan. Sinusuportahan ng Address ang mga pangalan, IPv4 at IPv6.
Maaaring i-format ang string tulad ng mga bahagi ng data ng mga mensaheng HTTP na inilarawan sa itaas, o ayon sa kinakailangan ng patutunguhang server.
Examples para sa External Messaging ay magsasama ng %EID% upang isaad ang Kaganapang nag-trigger:
lokasyon=%NAME%,kaganapan=%EID%
{“lokasyon”:”:%NAME%”,”kaganapan”:”%EID%”}
Examples for Heartbeat ay maaaring magdagdag ng %ACTIVE% (kasalukuyang na-trigger na Mga Kaganapan) o isang halaga ng sensor:
lokasyon=%NAME%&Triggered=%ACTIVE%
{“lokasyon”:”:%NAME%”,”NH3”:%SENSOR:NH3%}
Tinutukoy ng mga checkbox sa mga column na “Integration Set” at “Integration Reset” kung aling Mga Kaganapan ang nagti-trigger ng pagpapadala. Higit pa sa setup ng Mga Kaganapan at Pagkilos ay makukuha sa Gabay ng Administrator ng HALO.
Paghahatid ng JSON Event Messages
Mas gusto ng ilang developer na makatanggap ng data ng Event na naka-format bilang industry standard na self-labeled na JSON kaysa sa plain ASCII text dahil mas maaasahan at mas madaling ma-parse ang dating. Sa HALO web page na tab na “Messaging,” maaari kang magbigay ng mga mensahe ng JSON sa mga setting ng “External Messaging” na “Itakda ang String” at “I-reset ang String” at sa “Tibok ng Puso” na “Mensahe.”
Examples:
Mga Setting ng "External Messaging" Set String:
{ “device”:”%NAME%”, “event”:”%EID%”, “alarm”:”yes” }
Magpapadala ito ng isang mensahe ng TCP o UDP JSON sa tinukoy na server na nag-uulat ng friendly na pangalan ng device, pangalan ng kaganapan at kasisimula pa lang nito.
Mga Setting ng “External Messaging” I-reset ang String:
{ “device”:”%NAME%”, “event”:”%EID%”, “alarm”:”no” }
Magpapadala ito ng isang mensahe ng TCP o UDP JSON sa tinukoy na server na nag-uulat ng friendly na pangalan ng device, pangalan ng kaganapan at na huminto na ang kundisyon.
Mensahe ng "Tibok ng Puso":
{ “device”:”%NAME%”, “alive”:”%DATE% %TIME%” }
Pana-panahong magpapadala ito ng TCP o UDP JSON na mensahe sa tinukoy na server na nag-uulat na ang HALO ay buhay sa ipinahiwatig na oras.
Mga Dokumento / Mga Mapagkukunan
 |
Pangunahing Software ng HALO Smart Sensor API ng Software [pdf] Gabay sa Gumagamit HALO Smart Sensor API Basic Software |
