Базове програмне забезпечення HALO Smart Sensor API
вперед
У цьому документі описано групу можливостей датчика Halo Smart Sensor, відомих під загальною назвою BASIC API або інтерфейс прикладного програмування. Це обговорення призначене для програмістів або інтеграторів, які зацікавлені в інтеграції одного або кількох розумних датчиків HALO (HALO) із сторонніми програмними компонентами (не IPVideo) або системами. Загалом API HALO призначений для ефективної передачі інформації з HALO через звичайну мережу Ethernet до зовнішньої програми. Щоб досягти цієї мети, API розділено на три розділи: кероване подіями з’єднання сокета, з’єднання сокета Heartbeat і дані про події URL. Інтерфейс BACnet також присутній і розглядається в окремому документі.
Дизайн API
API розроблено з використанням галузевих стандартних форматів, таких як TCP/IP. HTTP, HTTPS і JSON. Розробка не потребує використання будь-яких спеціальних або запатентованих методів або бібліотек під час розробки зовнішньої програми чи програми. API є гнучким і може бути налаштований і запрограмований для доставки саме необхідних даних у найбільш ефективний спосіб. Подробиці роботи кожного з вищезазначених розділів описано в наступних розділах цього посібника.
Зовнішній обмін повідомленнями
Цей засіб використовується для доставки сповіщень або тривог і даних про події до зовнішньої програми, системи VMS, сервера тощо, коли подія запускається (встановлюється). Також можна ввімкнути додаткові повідомлення, щоб сигналізувати, коли подія очищається (скидається). Ця доставка може здійснюватися до сокета TCP/IP або сервера HTTP/S у режимі реального часу. Існує ряд конфігурованих протоколів із настроюваним вмістом. Доступні аутентифікація та шифрування.
Серцебиття
Інформаційні повідомлення надсилаються через настроюваний інтервал (замість того, коли запускаються події), щоб забезпечити підтвердження живої/доступності. Вони мають такий самий діапазон можливостей, як і зовнішні повідомлення, але зазвичай налаштовані так, щоб містити загальну інформацію про стан, а не деталі про конкретну подію.
Дані про події URL
Цей засіб доступний лише згідно з угодою про нерозповсюдження, і його слід використовувати лише тоді, коли зовнішній програмі потрібен доступ до будь-яких чи всіх значень подій, порогових значень і позначок стану. Зазвичай зовнішня програма отримує ці дані на вимогу, але не дуже часто. Цей метод зазвичай викликає деяку затримку, коли використовується помірна швидкість опитування. Типова швидкість опитування коливається від одного разу на хвилину до одного разу на 5 секунд з абсолютною максимальною швидкістю один раз на секунду. Цей метод також можна використовувати для отримання додаткових допоміжних даних, коли надходить Подія (сповіщення).
Деталі зовнішнього обміну повідомленнями
Розділ HALO web Спливаюче вікно інтеграції інтерфейсу забезпечує конфігурацію окремого підключення третьої сторони, де різні значення можна надсилати до віддаленого TCP-сокета або сервера HTTP/HTTPS. Заповнювачі (токени) використовуються для вставки живих значень у переданий текст. Незважаючи на те, що цей канал має позначку «Зовнішній обмін повідомленнями», цей канал можна використовувати майже для будь-яких цілей, які потребують ініціювання подій у реальному часі, активно доставлених HALO. Це розташування є досить гнучким, оскільки вибір у «Діях» визначає, які події HALO передаються через цей канал.
У режимі HTTP рядки Set і Reset є URLs, який потрібно ввести та відформатувати відповідно до вимог потрібного сервера призначення. Для автентифікації можна використовувати поля користувача та пароля. Дивіться режим HTTP нижче.
У режимі TCP рядки «Установити» та «Скинути» — це лише дані одного повідомлення, яке надсилається до приймального сокета TCP. Їх можна відформатувати за потреби призначення. Пункт призначення вказується в полях Адреса та Порт. Дивіться режим TCP нижче.
Для обох режимів відображається статус останнього повідомлення, що може допомогти у виправленні з’єднання чи інших проблемах. Ви можете скористатися кнопками Event TEST у спливаючому вікні «Дії», щоб примусово надіслати повідомлення:
Щоб увімкнути ці типи повідомлень, параметр Global On/Off для Set або Reset має бути On. Скидання часто не використовується, оскільки цікавить лише початок Події, але це може відрізнятися. Кожна подія може окремо вказати, чи використовуватиметься повідомлення «Установити» чи «Скинути» у спливаючому вікні «Дії». Кнопки очного яблука відображатимуть приблизне представлення того, що надіслано після замін ключових слів і форматування. Repeat Holdoff можна використовувати для обмеження частих повідомлень шляхом затримки перед надсиланням іншого. Це робиться окремо для кожної події. HALO має вбудований час утримання для подій 15 секунд, щоб запобігти швидкому повторному запуску подій. Якщо ви хочете забезпечити надсилання не більше 1 події певного типу за хвилину, ви можете встановити Repeat Holdoff на 60 (секунд).
Подробиці серцебиття
Передачі Heartbeat функціонують подібно до описаного вище, за винятком того, що немає взаємодії зі сторінкою Дії. Натомість передача Heartbeat відбувається регулярно, як налаштовано за допомогою поля Interval. У режимі HTTP рядки Set і Reset є URLs, який потрібно ввести та відформатувати відповідно до вимог потрібного сервера призначення. Для автентифікації можна використовувати поля користувача та пароля. Дивіться режим HTTP нижче.
Хоча основною метою Heartbeat є підтвердження життя розумного датчика HALO для віддаленої програми, це повідомлення також можна використовувати для передачі вибраних датчиків або інформації про поточний стан події. Колишній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), порт і пароль користувача, або ви можете використовувати поля «Користувач» і «Пароль», якщо потрібно, як сервер призначення для таких методів автентифікації, як «Базовий» або «Дайджест».
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%
{“location”:”:%NAME%”,”NH3”:%SENSOR:NH3%}
Прапорці в стовпцях «Integration Set» і «Integration Reset» визначають, які події ініціюють надсилання. Додаткові відомості про налаштування подій і дій доступні в посібнику адміністратора HALO.
Доставка повідомлень про події JSON
Деякі розробники вважають за краще отримувати дані подій у форматі галузевого стандарту самомаркованого JSON, а не простого тексту ASCII, оскільки перший є більш надійним і легшим для аналізу. На HALO web на вкладці «Повідомлення», ви можете надати повідомлення JSON у налаштуваннях «Зовнішні повідомлення» «Установити рядок» і «Скинути рядок» і в «Сердцебиття» «Повідомлення».
Examples:
Рядок налаштувань налаштувань зовнішнього обміну повідомленнями:
{ “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 активний у вказаний час.
Документи / Ресурси
 |
Базове програмне забезпечення HALO Smart Sensor API [pdfПосібник користувача Базове програмне забезпечення HALO Smart Sensor API |
