Ang HALO Smart Sensor API Basic Software sa Software
Sa unahan
Kini nga dokumento naghulagway sa grupo sa mga pasilidad sa Halo Smart Sensor nga nailhan nga BASIC API, o Application Programming Interface. Kini nga diskusyon gituyo alang sa paggamit sa mga programmer o integrator nga interesado sa pag-integrate sa usa o daghan pa nga HALO Smart Sensors (HALOs) sa 3rd party (non-IPVideo) software component o system. Sa kinatibuk-an, ang HALO API gituyo sa pagbalhin sa impormasyon nga episyente gikan sa HALO sa usa ka conventional Ethernet network ngadto sa external nga programa. Aron matuman kini nga tumong, ang API gibahin sa tulo ka mga seksyon: Event Driven Socket Connection, Heartbeat Socket Connection, ug Event Data URL. Ang interface sa BACnet anaa usab ug gitabonan sa usa ka bulag nga dokumento.
Disenyo sa API
Gidisenyo ang API gamit ang mga standard nga format sa industriya sama sa TCP/IP. HTTP, HTTPS, ug JSON. Ang disenyo wala magkinahanglan ug bisan unsang espesyal o proprietary nga mga teknik o librarya nga gamiton sa pagpalambo sa eksternal nga programa o aplikasyon. Ang API kay flexible ug mahimong ma-configure ug maprograma aron mahatag ang eksakto nga datos nga gikinahanglan ug sa labing episyente nga paagi. Ang mga detalye sa operasyon sa matag usa sa ibabaw nga mga seksyon gitabonan sa mosunod nga mga seksyon niini nga giya.
Panggawas nga Mensahe
Kini nga pasilidad gigamit sa paghatud sa mga alerto o mga alarma ug data sa Hitabo sa usa ka eksternal nga programa, sistema sa VMS, server, ug uban pa kung ang usa ka Hitabo ma-trigger (gitakda). Ang mga opsyonal nga mensahe mahimo usab nga ma-enable sa pagsenyas kung ang usa ka Hitabo mawagtang (gi-reset). Kini nga paghatod mahimo sa usa ka TCP/IP socket o HTTP/S server sa tinuod nga panahon. Adunay ubay-ubay nga ma-configure nga mga protocol nga adunay napasadya nga sulud. Anaa ang authentication ug encryption.
Pitik sa kasingkasing
Ang mga mensahe sa heartbeat gipadala sa usa ka ma-configure nga agwat (imbes kung kanus-a ma-trigger ang mga Hitabo) aron maghatag og pruweba sa live/availability. Sila adunay susama nga lain-laing mga kapabilidad sama sa External Messaging apan kasagaran i-configure aron adunay kinatibuk-ang impormasyon sa estado kaysa mga detalye mahitungod sa usa ka partikular nga panghitabo.
Data sa Hitabo URL
Kini nga pasilidad anaa lamang ubos sa usa ka NDA ug kinahanglang gamiton lamang kung ang eksternal nga programa nanginahanglan og access sa bisan unsa ug sa tanan nga Event values, thresholds, ug state flags. Kini nga datos kasagarang makuha kung gipangayo sa eksternal nga programa apan dili sa taas kaayo nga frequency. Kini nga pamaagi sa kasagaran adunay pipila ka latency kung ang usa ka kasarangan nga rate sa pagboto gigamit. Ang kasagarang mga rate sa pagboto gikan sa kausa matag minuto hangtod kausa matag 5 segundos nga adunay hingpit nga labing taas nga rate nga kausa matag segundo. Kini nga pamaagi mahimo usab nga gamiton aron makuha ang dugang nga pagsuporta sa datos kung ang usa ka Panghitabo (alerto) madawat.
Mga detalye sa External Messaging
Usa ka seksyon sa HALO web interface Ang Integration popup naghatag alang sa configuration sa usa ka 3rd party nga koneksyon diin ang lain-laing mga kantidad mahimong ipadala ngadto sa usa ka hilit nga TCP socket o usa ka HTTP/HTTPS server. Ang mga placeholder (mga token) gigamit sa pagsal-ot sa buhi nga mga bili ngadto sa gipasa nga teksto. Bisan kung gimarkahan nga "External Messaging," kini nga channel mahimong magamit sa halos bisan unsang katuyoan nga nanginahanglan tinuod nga oras nga Pag-trigger sa Panghitabo, nga aktibo nga gihatag sa HALO. Kini nga kahikayan medyo flexible tungod kay ang mga pagpili sa "Mga Aksyon" nagtino kung unsang HALO nga mga Hitabo ang ipadala pinaagi niini nga channel.
Sa HTTP mode, ang Set ug Reset Strings mao ang URLs nga kinahanglan nga isulod ug pormat ingon nga gikinahanglan sa gitinguha nga destinasyon server. Ang usa ka uma sa User ug Password mahimong magamit alang sa pag-authenticate. Tan-awa ang HTTP mode sa ubos.
Sa TCP mode, ang Set ug Reset Strings mao lamang ang data sa usa ka mensahe nga gipadala ngadto sa nakadawat nga TCP socket. Mahimo silang ma-format kung gikinahanglan sa destinasyon. Ang destinasyon gipiho sa mga natad sa Address ug Port. Tan-awa ang TCP Mode sa ubos.
Alang sa bisan unsang mode, ang status gikan sa pinakabag-o nga mensahe gipakita nga makatabang sa pag-ayo sa koneksyon o uban pang mga isyu. Mahimo nimong gamiton ang mga buton sa TEST sa Hitabo sa popup nga Mga Aksyon aron mapugos ang usa ka mensahe:
Ang Global On/Off para sa Set o Reset kinahanglan nga On para ma-enable kanang mga klase sa mga mensahe. Ang pag-reset kasagaran dili gamiton tungod kay ang pagsugod lamang sa usa ka Hitabo ang interesado, apan kana mahimong magkalahi. Ang matag Hitabo mahimong independente nga magtino kung gamiton ba ang Set o ang Reset nga mensahe sa popup nga Mga Aksyon. Ang mga butones sa eyeball magpakita sa usa ka bagis nga representasyon sa kung unsa ang gipadala pagkahuman sa mga pagpuli sa keyword ug pag-format. Ang Repeat Holdoff mahimong magamit sa pag- throttle sa kanunay nga mga mensahe pinaagi sa paglangan sa dili pa ipadala ang lain. Gihimo kini nga independente kada Hitabo. Ang HALO adunay built-in nga oras sa pagpugong alang sa mga panghitabo nga 15 segundos aron malikayan ang paspas nga pag-retrigger sa Mga Hitabo. Kung gusto nimo nga masiguro nga dili molapas sa 1 nga panghitabo sa usa ka tipo ang ipadala matag minuto, mahimo nimong itakda ang Repeat Holdoff sa 60 (segundo).
Detalye sa heartbeat
Ang mga transmission sa Heartbeat naglihok sa parehas nga paagi sa naa sa itaas gawas nga wala’y interaksyon sa panid sa Mga Aksyon. Hinunoa, ang transmission sa Heartbeat mahitabo sa usa ka regular nga basehan ingon nga gi-configure sa Interval field, Sa HTTP mode, ang Set ug Reset Strings mao ang URLs nga kinahanglan nga isulod ug pormat ingon nga gikinahanglan sa gitinguha nga destinasyon server. Ang usa ka uma sa User ug Password mahimong magamit alang sa pag-authenticate. Tan-awa ang HTTP mode sa ubos.
Samtang ang panguna nga katuyoan sa Pintik sa Kasingkasing mao ang paghatag pamatuod sa kinabuhi sa usa ka HALO Smart Sensor sa usa ka hilit nga aplikasyon, kini nga mensahe mahimo usab nga magamit aron ipadala ang mga pinili nga sensor o karon nga kasayuran sa kahimtang sa panghitabo. Ang example sa ibabaw nagpadala sa usa ka taas nga string parameter uban sa URL nga naglakip sa Halo nga ngalan, kadaghanan sa sensor values, ug sa katapusan Triggered=%ACTIVE% nga mahimong walay sulod o usa ka lista sa kasamtangang na-trigger nga mga Hitabo.
HTTP (ug HTTPS) Mode
Ang External Messaging ug Heartbeat strings mahimong http: o https: URLs ingon sa gikinahanglan. Ang agianan ug mga parametro mahimong masulod kung gikinahanglan sa destinasyon nga server. Ang mga keyword sama sa %NAME% (HALO device name) o %EID% (Event id) mahimong isal-ot kung gikinahanglan ug pulihan sa tagsa-tagsa nga datos kung ipadala ang mensahe. Ang usa ka lista sa kasagarang gigamit nga mga keyword gipakita alang sa dali nga pakisayran.
Ang URL Ang agianan mahimong adunay mga keyword ingon man ang mga parameter sa URL. Ang mga parameter mahimong NAME=VALUE nga mga pares o usa ka butang nga JSON, o usa ka naandan nga pormat depende sa destinasyon nga server. Examples alang sa External Messaging maglakip sa %EID% aron ipahibalo ang Hitabo nga 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 mahimong makadugang og %ACTIVE% (karon gi-trigger nga mga Hitabo) o usa ka sensor value:
- https://server.com/alive?location=%NAME%&Triggered=%ACTIVE%
- https://server.com/event?{“location”:”:%NAME%”,”NH3”:%SENSOR:NH3%}
Ang %SENSOR:…% nga mga kantidad naggamit sa mga ngalan nga makita sa tuo nga mga ulohan sa kolum sa sensor sa evtYYYYMMDD.csv log files. Kasagaran sila:
Kung gusto sa destinasyon nga server ang HTTP PUT o POST imbes nga GET nga mga hangyo, mahimo nimong i-prefix ang URL uban sa PUT: o POST:. Sa gawasnon, mahimo nimong idugang ang usa ka payload sa JSON nga sikat sa daghang mga server pinaagi sa pagdugang sa [JSONBODY] nga keyword nga gisundan sa usa ka butang nga na-format sa JSON. Example:
PUT:https://server.com/event[JSONBODY]{“location”:”%NAME%”,”event”:”%EID%”}
Ang URL nagsuporta sa tipikal nga IP address (ug IPv6) ug port ug user-password nga mga kapilian, o mahimo nimong gamiton ang User ug Password field kung gikinahanglan ang destinasyon nga server alang sa mga pamaagi sa pag-authenticate sama sa Basic o Digest:
https://username:password@123.321.123.321:9876/event…
TCP Mode
Ang External Messaging ug Heartbeat strings kay para lang sa data kay ang Address ug Port fields nagtino sa destinasyon. Ang Address nagsuporta sa mga ngalan, IPv4 ug IPv6.
Ang string mahimong ma-format sama sa mga bahin sa datos sa HTTP nga mga mensahe nga gihulagway sa ibabaw, o ingon nga gikinahanglan sa destinasyon nga server.
Examples alang sa External Messaging maglakip sa %EID% aron ipahibalo ang Hitabo nga nag-trigger:
lokasyon=%NAME%, hitabo=%EID%
{“lokasyon”:”:%NAME%”,”event”:”%EID%”}
Examples for Heartbeat mahimong makadugang og %ACTIVE% (karon gi-trigger nga mga Hitabo) o usa ka sensor value:
lokasyon=%NAME%&Gi-trigger=%ACTIVE%
{“lokasyon”:”:%NAME%”,”NH3”:%SENSOR:NH3%}
Ang mga checkbox sa "Integration Set" ug "Integration Reset" nga mga kolum nagtino kung unsang mga Hitabo ang nagpalihok sa pagpadala. Daghan pa bahin sa setup sa Mga Hitabo ug Aksyon anaa sa HALO Administrator's Guide.
Paghatud sa Mga Mensahe sa Panghitabo sa JSON
Gipili sa ubang mga developer nga makadawat sa datos sa Panghitabo nga gi-format isip standard sa industriya nga gimarkahan sa kaugalingon nga JSON kaysa yano nga ASCII nga teksto tungod kay ang nahauna mas kasaligan ug dali nga ma-parse. Sa HALO web page nga "Messaging" nga tab, mahimo nimong ihatag ang mga mensahe sa JSON sa mga setting sa "External Messaging" nga "Set String" ug "Reset String" ug sa "Heartbeat" "Message."
Examples:
Mga Setting sa "External Messaging" Set String:
{ “device”:”%NAME%”, “event”:”%EID%”, “alarm”:”oo” }
Magpadala kini og usa ka mensahe sa TCP o UDP JSON ngadto sa espesipikong server nga nagtaho sa mahigalaon nga ngalan sa device, ngalan sa panghitabo ug nga bag-o lang kini nagsugod.
Mga Setting sa "External Messaging" Reset String:
{ “device”:”%NAME%”, “event”:”%EID%”, “alarm”:”no” }
Magpadala kini og usa ka mensahe sa TCP o UDP JSON ngadto sa espesipikong server nga nagtaho sa mahigalaon nga ngalan sa device, ngalan sa panghitabo ug nga ang kondisyon mihunong na.
Mensahe sa "Pitik sa Kasingkasing":
{ “device”:”%NAME%”, “buhi”:”%DATE% %TIME%” }
Kini matag karon ug unya magpadala usa ka TCP o UDP JSON nga mensahe sa gitakda nga server nga nagreport nga ang HALO buhi sa gipakita nga oras.
Mga Dokumento / Mga Kapanguhaan
 |
Ang HALO Smart Sensor API Basic Software sa Software [pdf] Giya sa Gumagamit HALO Smart Sensor API Basic Software |
