Базов софтуер на API на HALO Smart Sensor
Напред
Този документ описва групата от съоръжения на Halo Smart Sensor, известни общо като BASIC API или интерфейс за програмиране на приложения. Тази дискусия е предназначена за използване от програмисти или интегратори, които се интересуват от интегрирането на един или повече интелигентни сензори HALO (HALO) със софтуерни компоненти или системи на трети страни (не-IPVideo). Като цяло API на HALO е предназначен за ефективно прехвърляне на информация от HALO през конвенционална Ethernet мрежа към външната програма. За постигане на тази цел API е разделен на три секции: управлявана от събития връзка на сокет, връзка на сърдечен гнездо и данни за събития URL. BACnet интерфейсът също присъства и е описан в отделен документ.
API дизайн
API е проектиран с помощта на индустриални стандартни формати като TCP/IP. HTTP, HTTPS и JSON. Дизайнът не изисква никакви специални или патентовани техники или библиотеки, които да бъдат използвани при разработването на външната програма или приложение. API е гъвкав и може да бъде конфигуриран и програмиран да доставя точно необходимите данни и по най-ефективния начин. Подробностите за работата на всеки от горните раздели са разгледани в следващите раздели на това ръководство.
Външни съобщения
Това съоръжение се използва за доставяне на сигнали или аларми и данни за събитие към външна програма, VMS система, сървър и т.н., когато дадено събитие е задействано (е зададено). Незадължителните съобщения също могат да бъдат активирани, за да сигнализират, когато дадено събитие се изчисти (нулира). Тази доставка може да бъде направена до TCP/IP сокет или HTTP/S сървър в реално време. Има набор от конфигурируеми протоколи с персонализирано съдържание. Налични са удостоверяване и криптиране.
Сърцебиене
Heartbeat съобщенията се изпращат на конфигурируем интервал (вместо когато се задействат събития), за да се осигури доказателство за на живо/наличност. Те имат подобен набор от възможности като външните съобщения, но обикновено са конфигурирани да съдържат обща информация за състоянието, а не подробности за конкретно събитие.
Данни за събитието URL
Това съоръжение е достъпно само при NDA и трябва да се използва само когато външната програма изисква достъп до всички стойности на събития, прагове и флагове за състояние. Тези данни обикновено се извличат при поискване от външната програма, но не с много висока честота. Този метод обикновено включва известно забавяне, когато се използва умерена честота на анкетиране. Типичните честоти на запитване варират от веднъж на минута до веднъж на 5 секунди с абсолютна максимална скорост веднъж на секунда. Този метод може да се използва и за извличане на допълнителни подкрепящи данни, когато се получи събитие (предупреждение).
Подробности за външни съобщения
Част от HALO web Изскачащият прозорец за интегриране на интерфейс осигурява конфигуриране на една връзка на трета страна, където различни стойности могат да бъдат изпратени до отдалечен TCP сокет или HTTP/HTTPS сървър. Заместители (токени) се използват за вмъкване на живи стойности в предавания текст. Въпреки че е обозначен като „Външни съобщения“, този канал може да се използва за почти всякакви цели, изискващи задействания на събития в реално време, доставяни активно от HALO. Тази подредба е доста гъвкава, защото селекциите в „Действия“ определят кои HALO събития се предават през този канал.
В HTTP режим низовете Set и Reset са URLs, които трябва да бъдат въведени и форматирани, както се изисква от желания целеви сървър. Полето Потребител и Парола може да се използва за удостоверяване. Вижте HTTP режим по-долу.
В TCP режим низовете Set и Reset са само данните от едно съобщение, което се изпраща до приемащия TCP сокет. Те могат да бъдат форматирани според нуждите на дестинацията. Дестинацията е посочена в полетата Адрес и Порт. Вижте TCP режим по-долу.
И за двата режима се показва състояние от най-новото съобщение, което може да помогне при коригиране на връзката или други проблеми. Можете да използвате бутоните Event TEST в изскачащия прозорец Actions, за да принудите съобщение:
Глобалното включване/изключване за настройка или нулиране трябва да е включено, за да се активират тези типове съобщения. Нулирането често не се използва, защото само началото на дадено събитие представлява интерес, но това може да варира. Всяко събитие може самостоятелно да посочи дали ще използва или съобщението Set или Reset в изскачащия прозорец Actions. Бутоните на очната ябълка ще покажат грубо представяне на това, което се изпраща след заместване на ключови думи и форматиране. Repeat Holdoff може да се използва за ограничаване на честите съобщения чрез забавяне, преди да може да бъде изпратено друго. Това се прави независимо за всяко събитие. HALO има вградено време на задържане за събития от 15 секунди, за да предотврати бързо повторно задействане на събития. Ако искате да сте сигурни, че не се изпраща повече от 1 събитие от даден тип на минута, можете да зададете Repeat Holdoff на 60 (секунди).
Подробности за сърдечния ритъм
Предаванията Heartbeat функционират по начин, подобен на горния, с изключение на това, че няма взаимодействие със страницата Действия. Вместо това предаването Heartbeat се извършва редовно, както е конфигурирано с полето Interval. В HTTP режим низовете Set и Reset са URLs, които трябва да бъдат въведени и форматирани, както се изисква от желания целеви сървър. Полето Потребител и Парола може да се използва за удостоверяване. Вижте HTTP режим по-долу.
Въпреки че основната цел на Heartbeat е да предостави доказателство за живота на HALO Smart Sensor на отдалечено приложение, това съобщение може да се използва и за предаване на избрани сензори или текуща информация за състоянието на събитието. Бившиятample по-горе изпраща параметър с дълъг низ с URL които включват името на Halo, по-голямата част от стойностите на сензора и накрая Triggered=%ACTIVE%, което може да е празно или списък с текущо задействани събития.
HTTP (и HTTPS) режим
Низовете за външни съобщения и Heartbeat могат да бъдат http: или https: URLs според нуждите. Пътят и параметрите могат да бъдат въведени според нуждите на целевия сървър. Ключови думи като %NAME% (име на устройство HALO) или %EID% (идентификационен номер на събитие) могат да бъдат вмъкнати според нуждите и ще бъдат заменени със съответните данни, когато съобщението бъде изпратено. Показан е списък с често използвани ключови думи за бърза справка.
The URL пътят може да съдържа ключови думи, както и параметрите на URL. Параметрите може да са двойки NAME=VALUE или JSON обект, или персонализиран формат в зависимост от целевия сървър. Прampфайловете за външни съобщения ще включват %EID%, за да укажат събитието, което е задействало:
- https://server.com/event/%NAME%/%EID%
- https://server.com/event?location=%NAME%&event=%EID%
- https://server.com/event?{“location”:”:%NAME%”,”event”:”%EID%”}
Exampфайловете за Heartbeat може да добавят %ACTIVE% (текущо задействани събития) или стойност на сензор:
- https://server.com/alive?location=%NAME%&Triggered=%ACTIVE%
- https://server.com/event?{“location”:”:%NAME%”,”NH3”:%SENSOR:NH3%}
Стойностите %SENSOR:…% използват имената, намиращи се в заглавията на дясната колона на сензора в регистрационния файл evtYYYYMMDD.csv fileс. Те обикновено са:
Ако целевият сървър предпочита HTTP PUT или POST вместо GET заявки, можете да добавите префикс към URL с PUT: или POST:. Независимо от това можете да добавите JSON полезен товар, който е популярен сред много сървъри, като добавите ключовата дума [JSONBODY], последвана от JSON форматиран обект. Прampле:
PUT:https://server.com/event[JSONBODY]{“location”:”%NAME%”,”event”:”%EID%”}
The URL поддържа типичен IP адрес (и IPv6) и опции за порт и потребителска парола или можете да използвате полетата Потребител и Парола, ако е необходимо, да бъдете целевият сървър за методи за удостоверяване като Basic или Digest:
https://username:password@123.321.123.321:9876/event…
TCP режим
Низовете за външни съобщения и Heartbeat са само за данни, тъй като полетата Address и Port указват дестинацията. Адресът поддържа имена, IPv4 и IPv6.
Низът може да бъде форматиран като частите с данни на HTTP съобщенията, описани по-горе, или както се изисква от целевия сървър.
Exampфайловете за външни съобщения ще включват %EID%, за да укажат събитието, което е задействало:
местоположение=%NAME%,event=%EID%
{“location”:”:%NAME%”,”event”:”%EID%”}
Exampфайловете за Heartbeat може да добавят %ACTIVE% (текущо задействани събития) или стойност на сензор:
местоположение=%NAME%&Triggered=%ACTIVE%
{“местоположение”:”:%ИМЕ%”,”NH3”:%СЕНЗОР:NH3%}
Квадратчетата за отметка в колоните „Integration Set“ и „Integration Reset“ определят кои събития задействат изпращането. Повече за настройката на събития и действия можете да намерите в Ръководството на администратора на HALO.
Доставка на JSON съобщения за събития
Някои разработчици предпочитат да получават данни за събитието, форматирани като индустриален стандарт, самомаркиран JSON, вместо обикновен ASCII текст, тъй като първият е по-надежден и по-лесен за анализ. На HALO web раздел „Съобщения“, можете да предоставите JSON съобщения в настройките „Външни съобщения“ „Задаване на низ“ и „Нулиране на низ“ и в „Сърдечен пулс“ „Съобщение“.
Exampлес:
Низ за настройка на настройките за „външни съобщения“:
{ “device”:”%NAME%”, “event”:”%EID%”, “alarm”:”yes” }
Това ще изпрати едно TCP или UDP JSON съобщение до посочения сървър, съобщаващо за приятелското име на устройството, името на събитието и че то току-що е започнало.
Низ за нулиране на настройките за „външни съобщения“:
{ “device”:”%NAME%”, “event”:”%EID%”, “alarm”:”no” }
Това ще изпрати едно TCP или UDP JSON съобщение до посочения сървър, съобщаващо за приятелското име на устройството, името на събитието и че условието вече е спряно.
Съобщение „Сърцебиене“:
{ “device”:”%NAME%”, “alive”:”%DATE% %TIME%” }
Това периодично ще изпраща TCP или UDP JSON съобщение до посочения сървър, съобщавайки, че HALO е жив в посочения момент.
Документи / Ресурси
 |
Базов софтуер на API на HALO Smart Sensor [pdf] Ръководство за потребителя HALO Smart Sensor API Основен софтуер |
