Одной из отличительных особенностей всех продуктов комплекса НЕЙРОСС и, в частности, IP-контроллеров БОРЕЙ, ЯРС v.1 (снят с производства!) и других является возможность модификации и расширения алгоритмов работы продукта посредством скриптов автоматизации. С помощью скрипта возможно, например, изменить или полностью заменить алгоритм доступа в контроллере БОРЕЙ. Или реализовать логику сопряжения со внешней информационной системой по протоколу HTTP. Или управлять исполнительными устройствами по заданному алгоритму.
В данном документе приведены общие сведения о скриптах автоматизации, их возможностях и руководство программиста по написанию таких скриптов.
Скрипт автоматизации может существенно изменить «заводскую» логику работы продукта. Потому разработку скрипта рекомендуется проводить только опытному пользователю. Производитель продукта не несёт ответственности за несоответствие реальных и заявленных свойств продукта в случае, если такое расхождение возникло вследствие внесения изменений в скрипт автоматизации. |
Скрипт автоматизации — текстовый сценарий, выполнение которого осуществляется программными средствами продукта.
Данный сценарий всегда один. Он может быть пустым — в таком случае скрипт не делает ничего. В скрипте могут быть команды управления — они выполняются по мере выполнения скрипта.
Скрипт автоматизации должен быть написан на языке Lua (версия 5.1). Разработчику доступны стандартные средства языка (операторы, структуры данных и др.), часть функций стандартной библиотеки (см. далее), а также наборы констант и функций, определённых в прикладных Lua-модулях продукта. Прикладные Lua-модули специально разработаны для упрощения написания скриптов и двустороннего взаимодействия с программными средствами продукта — чтобы можно было из скрипта вызывать какие-либо функции продукта или, наоборот, передавать управление в скрипт в процессе функционирования продукта.
В разных продуктах могут быть доступны разные прикладные модули. Так, модуль управления доступом |
Скрипт автоматизации выполняется в «песочнице» — защищённом окружении. Если в ходе работы скрипта возникает ошибка, то выполнение скрипта просто прерывается — нарушается работа функций, так или иначе связанных со скриптами (например, алгоритмов доступа), НО общая работоспособность продукта сохраняется, на стабильность работы программных средств поведение скрипта не влияет.
В случае IP-контроллеров (БОРЕЙ, ИГНИС и пр.) скрипт автоматизации является изменяемыми данными также, как любые другие конфигурационные данные продукта (как, например, настройки сетевых интерфейсов или параметры доступа). Потому после внесения изменений в скрипт, успешной отладки и апробации сценария ОБЯЗАТЕЛЬНО создавайте резервную копию. Резервная копия будет содержать скрипт автоматизации, и в случае, если файловая система на SD-карте вдруг будет повреждена, скрипт будет восстановлен вместе с остальными конфигурационными данными из резервной копии. |
Для удобство редактирования и отладки скрипта автоматизации предназначен текстовый online-редактор, доступный в наших продуктах по адресу http://[ip-address]/lua-editor/
или http://[ip-address]/internal/lua-editor/
.
При сохранении скрипта автоматизации полностью перезапускается вся виртуальная Lua-машина, в следствие чего перезапускаются и системные Lua-скрипты — такие, например, как алгоритмы управления доступом и другие. |
Скриншот редактора скриптов приведён на изображении ниже.
Сообщения об ошибках в Lua-скрипте, а также отладочные сообщения, выводимые из скрипта с помощью модуля log.lua, записываются в журнал аудита. Просмотр этих сообщений в реальном времени возможен при помощи веб-приложения «Журнал аудита», доступного с веб-страницы Рабочий стол.
* — OFF
LuaManager — DEBUG
lua_scall — DEBUG
neyross::LogLuaModule — DEBUG
Скрипт автоматизации должен быть написан на языке Lua версии 5.1.
Официальный сайт языка Lua (на английском языке) — http://www.lua.org/
Официальная документация по языку Lua версии 5.1 — http://www.lua.org/manual/5.1/ (английский язык)
Перевод документации по языку Lua версии 5.1 на русский язык: http://www.lua.ru/doc/
Также можно ознакомиться с документацией на русском языке для последней актуальной версии Lua (5.3 на момент написания статьи) по ссылке http://lua.org.ru/contents_ru.html. Большая часть содержимого также актуальна и для версии 5.1, поддерживаемой продуктами НЕЙРОСС.
В скриптах автоматизации доступны следующие разделы стандартной библиотеки:
Следующие разделы недоступны (не могут быть использованы) в скрипте автоматизации:
В таблице ниже перечислены прикладные модули, их описание и продукты, в которых эти модули могут быть использованы.
Модуль | Продукты | Краткое описание | |
---|---|---|---|
БОРЕЙ ЯРС | Модуль интеграции с подсистемой охранно-тревожной сигнализации контроллера. | ||
Все продукты | Модуль общесистемных функций. Получение системных даты / времени, генерация UUID-ов и так далее. | ||
БОРЕЙ ЯРС | |||
БОРЕЙ ЯРС | Модуль взаимодействия с периферией на контроллерах БОРЕЙ и ЯРС. Модуль позволяет:
| ||
Все продукты | Модуль поддержки HTTP-протокола; модуль позволяет:
| ||
ИГНИС | |||
Все продукты | Модуль аудита позволяет выводить в журнал аудита текстовые сообщения с заданным уровнем логирования | ||
ЯРС | |||
ЯРС | |||
ЯРС | |||
БОРЕЙ ЯРС | Модуль интеграции с подсистемой доступа в контроллерах БОРЕЙ, ЯРС. Модуль позволяет реализовать свой алгоритм доступа вместо предустановленного или внести изменения в стандартные алгоритмы, переопределив отдельные части алгоритма. | ||
Все продукты | Модуль для долговременного сохранения настроек / параметров скрипта автоматизации в форме ключ=значение | ||
Все продукты | Асинхронное выполнение отложенных по времени или периодических действий.
| ||
Каждый прикладной Lua-модуль обычно сопровождается соответствующим lua-файлом, который можно просматривать в правой части веб-редактора скрипта автоматизации. В таких lua-файлах каждая функция, константа или перечисление обычно сопровождаются подробными комментариями с указанием назначения и способа использования соответствующего кода. |
Подключение прикладного Lua-модуля осуществляется функцией require. Рекомендуемая форма использования:
local log = require("log") |
Вызвать функцию Lua-модуля в таком случае можно следующим образом, например:
local logger = log.get_logger("MyLogger") |
Описание временно недоступно.
Данный модуль предоставляет общесистемные функции. Перечень функций приведён в таблице ниже.
Функция | Аргументы | Результат | Описание |
---|---|---|---|
now() | нет | число с плавающей точкой | Возвращает число с плавающей точкой, соответствующее количеству секунд, прошедшему с 1970 года (с точностью до миллисекунд) |
uuid() | нет | строка | Генерирует уникальный идентификатор по стандарту ISO. Возвращает строковое представление идентификатора, например:
|
localtime(t) | число | таблица Lua | Для переданного числа возвращает структуру данных с полями для года, месяца, дня и так далее. В аргументе передать число с плавающей точкой, соответствующее количеству секунд, прошедшему с 1970 года (с точностью до миллисекунд). Структура данных соответствует |
mktime(tm) | таблица Lua | число | Принимает на вход структуру tm (POSIX; см. https://linux.die.net/man/3/localtime_r) в форме Lua-таблицы и возвращает число с плавающей точкой, равное количеству секунд, прошедшему с 1970 года (с точностью до миллисекунд) |
iso8601_print(t) | число | строка | Для переданного числа (формат см. common.now()) возвращает строку представления даты и времени в формате ISO8601. В аргументе передать число с плавающей точкой, соответствующее количеству секунд, прошедшему с 1970 года (с точностью до миллисекунд). |
iso8601_parse(s) | строка | число | Принимает на вход строку в формате ISO8601 и возвращает соответствующее данной строке число с плавающей точкой, равное количеству секунд, прошедшему с 1970 года (с точностью до миллисекунд) |
Описание временно недоступно.
Данный модуль позволяет управлять выходами (на плате контроллера БОРЕЙ, ЯРС, а также на модулях расширения АМ-06) и световой / звуковой индикацией подключенных к контроллеру считывателей.
В перечислении fec.TYPE
описаны различные типы периферии. Для управления пригодны типы fec.TYPE.RELE
(выход на плате контроллера) и fec.TYPE.SART_RELE
(выход на модуле расширения). Для управления выходами следует использовать функцию set_value(тип периферии, ID элемента, состояние), где в первый параметр необходимо передать одно из значений перечисления fec.TYPE
, во второй параметр — идентификатор (адрес) элемента для управления, в третий параметр — требуемое состояние (для выходов это 0 = Выключено, 1 = Включено). Например:
local fec = require("fec") fec.set_value(fec.TYPE.RELE, 1, 1) |
В этом примере выполняется включение первого реле на плате контроллера.
Нумерация выходов начинается с 1. Адрес выхода на модуле расширения определяется его адресом на шине.
К контроллеру БОРЕЙ (и ЯРС) можно подключить два считывателя, на плате есть выходы для управления красным, зелёным светодиодами и звуковой индикацией. Управлять светодиодами и бипером можно также с помощью функции set_value
. Возможные режимы индикации светодиода определены в перечислении fec.DIOD
. Доступно некоторое количество предустановленных режимов различной частоты и скважности. Звуковую индикацию можно только либо включить, либо выключить (см. перичесление fec.BEEPER
).
Поскольку управление светодиодной / звуковой индикацией на считывателях осуществляется в рамках алгоритмов доступа и состояние красного, зелёного светодиодов и звука взаимосвязано (если красный светодиод горит, то зелёный погашен и др.) — для удобства управления всей индикацией реализована функция-обёртка fec.set_reader(ID считывателя, зелёный светодиод, красный светодиод, звук)
. Пример использования функции приведён ниже:
local fec = require("fec") fec.set_reader(1, fec.DIOD.MODE_OFF, fec.DIOD.MODE_025_025, fec.BEEPER.MODE_OFF) |
Модуль позволяет отправлять HTTP-запросы прямо из Lua-скрипта, а также асинхронно обрабатывать ответы на отправленные ранее запросы.
Для отправки запроса и обработки ответа необходимо:
on_http_response(данные ответа)
.http.with(объект-обработчик)
. Функция возвращает создаёт и возвращает объект-запрос. transmit(параметры запроса)
. Запрос будет отправлен в соответствии с заданными параметрами запроса. По мере получения ответа (или если запрос не удастся) будет асинхронно вызван метод on_http_response
у созданного на первом шаге объекта-обработчика.Ниже приведён пример использования модуля HTTP для отправки GET-запроса на IP-адрес веб-сайта http://example.com.
local log = require("log") local http = require("http") local logger = log.get_logger("script.lua") -- обработчик ответа на HTTP-запрос local example_handler = {} -- этот метод обработчика будет вызван при получении ответа на запрос function example_handler:on_http_response(response_data) if response_data == nil then logger:error("connection has failed; no response received") else logger:debug("response received; status="..response_data.status..", type(body)="..type(response_data.body)) end end -- параметры запроса local http_request = { url = "http://93.184.216.34", -- адрес http://example.com method = http.METHOD.GET, version = http.VERSION.HTTP10, timeout = 5000 } -- отправка HTTP-запроса logger:debug("querying http://example.com") http.with(example_handler):transmit(http_request) |
В параметрах запроса можно указать следующие данные:
method
— используемый HTTP-метод, значение из перечисления http.METHOD
; значение по умолчанию http.METHOD.GET
;version
— используемая версия протокола HTTP, значение из перечисления http.VERSION
; значение по умолчанию http.VERSION.HTTP11
;url
— целевой адрес / URL запрашиваемого ресурса, обязательный параметр;timeout
— таймаут ожидания ответа / сетевого соединения, в миллисекундах; по умолчанию 13000 (13 секунд);header
— таблица HTTP-заголовков (см. далее);body
— тело запроса (см. далее).Можно указать произвольные заголовки HTTP-запроса в форме Lua-таблицы со строковыми парами типа «ключ = значение». При этом «ключ» будет выступать в роли имени HTTP-заголовка, а «значение» — в роли значения HTTP-заголовка.
Пример:
-- параметры запроса local http_request = { url = "http://93.184.216.34", method = http.METHOD.GET, version = http.VERSION.HTTP10, timeout = 5000 } http_request.header = {} http_request.header["X-Extra-Header"] = "my extra header value" |
Модуль позволяет отправлять в HTTP-запросах (PUT или POST) данные в форме текста или JSON.
Для передачи запроса с телом в форме текста достаточно присвоить параметру запроса body соответствующее строковое значение. Например:
local http_request = { url = "http://10.1.30.3:8080/myservice", method = http.METHOD.POST, body = "<a>hello XML</a>" } http_request.header = {} http_request.header["Content-Type"] = "text/xml; charset=UTF-8" |
Модуль также позволяет передавать запрос с телом в форме JSON-документа, который автоматически формируется из Lua-таблицы. Например:
local http_request = { url = "http://10.1.30.3:8080/myservice", method = http.METHOD.POST } http_request.body = { myParam = "A", wowThisIsSubTable = {} } http_request.body["ohNumberHere"] = 42 http_request.body.wowThisIsSubTable["robot"] = "kill all human" |
При отправке запроса с такими параметрами HTTP-заголовок Content-Type будет автоматически установлен в application/json, а тело запроса будет содержать следующий JSON-документ:
{ "myParam": "A", "ohNumberHere": 42, "wowThisIsSubTable": { "robot": "kill all human" } } |
При преобразовании Lua-таблицы в JSON поддерживаются все типы данных КРОМЕ массивов (таблиц с числовыми ключами). |
При поступлении ответа или сбое при отправке запроса асинхронно вызывается метод on_http_response(response_data)
на объекте-обработчике. Параметр метода — это Lua-таблица, содержащая следующие данные:
status
— код HTTP-ответа, число в соответствии со спецификацией [https://ru.wikipedia.org/wiki/Список_кодов_состояния_HTTP];header
— HTTP-заголовки ответа в форме Lua-таблицы (аналогично HTTP-заголовкам запроса);body
— тело ответа.Если отправка запроса не удалась и ответ не был получен, то аргумент метода равен nil
.
Тело ответа в зависимости от Content-Type
может быть либо Lua-таблицей (если Content-Type
ответа равен application/json
— тело автоматически преобразуется в Lua-таблицу), либо текстом / строкой (в остальных случаях).
Описание временно недоступно.
Модуль позволяет выводить текстовые сообщения в журнал аудита.
Для вывода сообщений разработчику необходимо:
log.lua
в скрипт автоматизации командой require.log.get_logger(имя-логгера)
.trace
, debug
, info
, warn
или error
у объекта-логгера.Пример приведён ниже:
local log = require("log") local logger = log.get_logger("MyLogger") local answer = 42 logger:debug("The answer is "..tostring(answer)) |
Обратите внимание:
neyross::LogLuaModule
, а потому в настройки журнала аудита следует добавить соответствующий фильтр, например: neyross::LogLuaModule | DEBUG
.trace
(только для отладочного режима, в журнал не попадают никогда);debug
(отладочные сообщения);info
(информационные сообщения);warn
(сообщения-предупреждения);error
(сообщения об ошибках)...
и функцию приведения нестроковых типов к строке tostring
из стандартной библиотеки.Описание временно недоступно.
Модуль предоставляет API для мониторинга состояния входов (зон) на модулях расширения ЯРС.
loninput.lua позволяет «подписаться» на изменения состояния входов. Для управления «подписчиками» в модуле доступны следующие функции:
Функция | Назначение | Комментарии |
---|---|---|
| Добавить объект подписчика | Функция принимает следующие параметры:
|
remove_listener(key) | Удалить объект подписчика | Единственный аргумент key указывает на добавленного ранее подписчика, которого необходимо «отписать» от получения уведомлений. |
Каждый объект-подписчик должен быть представлен Lua-таблицей с функцией on_loninput_input_state_changed(device_address, input_index, raw_state, logical_state)
.
Данная функция будет вызвана:
add_listener
для всех входов всех модулей (что позволяет получить текущее состояние нужных входов в момент добавления подписчика).В функцию on_loninput_input_state_changed
передаются следующие параметры:
Параметр | Тип данных | Описание |
---|---|---|
device_address | Число | Адрес устройства, к которому относится вход (зона) |
input_index | Число | Индекс входа (зоны), которому соответствует состояние |
raw_state | Число | Технический код состояния входа (зоны), полученный от модуля; возможные коды перечислены в таблице RAW_INPUT_STATE |
logical_state | Число | Логическое состояние входа значения из перечисления LOGICAL_INPUT_STATE |
Логическое состояние входа может быть следующим:
LOGICAL_INPUT_STATE.UNKNOWN
) — значение не известно;LOGICAL_INPUT_STATE.OFF
) — вход выключен, нормальное состояние (логический 0);LOGICAL_INPUT_STATE.ON
) — вход включен, тревожное состояние (логическая 1).Модуль предоставляет API для интеграции с подсистемой доступа модулей расширения ЯРС, таких как МДС и М2. Модуль позволяет модифицировать стандартные алгоритмы доступа.
Подсистема доступа в модулях расширения ЯРС по своей структуре и поведению отвечает требованиям спецификаций Onvif (Profile C, Access Control Service, Door Control Service). В частности, состояние точек доступа, команды управления ими и другие аспекты отвечают указанным спецификациям. Рекомендуется ознакомиться с данными спецификациями перед использованием модуля |
Получить список точек доступа с их идентификаторами можно через поле lonpacs.ap_instance
, которое заполняется при инициализации модуля и виртуальной Lua-машины (до того, как будет выполняться пользовательский Lua-скрипт). Поле lonpacs.ap_instance
содержит Lua-таблицу, в которой ключами являются токены точек доступа, а значениями — Lua-таблицы с системными параметрами точек доступа. Структура таблицы представлена в коде ниже:
lonpacs.ap = { "токен первой точки доступа" = { ... }, "токен второй точки доступа" = { ... }, ... -- и так далее } |
Каждая точка доступа в списке — это либо точка доступа модуля расширения МДС, либо одна из точек доступа М2.
Для управления точками доступа на модулях расширения доступна функция transmit_status(token, status)
, которая позволяет отправлять модулям команды управления. Функция принимает следующие параметры:
Параметр | Тип | Описание |
---|---|---|
token | Строка | Идентификатор (токен) точки доступа, которой необходимо управлять |
status | Число | Команда управления (требуемый статус точки доступа); значение из перечисления lonpacs.AP_COMMAND (см. ниже) |
Для управления точкам доступа доступны следующие команды (значения параметра status
):
Команда | Значение | Описание |
---|---|---|
STATUS_QUERY | -1 | Запрос состояния точки доступа |
RESTORE | 12 | Переключиться в дежурный режим работы |
OPEN_BLOCKED | 21 | Разблокировать точку доступа |
CLOSE_BLOCKED | 22 | Заблокировать точку доступа |
DISABLE | 13 | |
INITIATE_PASS | 18 | Инициировать проход |
Модуль lonpacs.lua
позволяет «подписаться» на события изменения состояния точек доступа, мониторинга связи с точками доступа, изменения состояния прохода (фазы алгоритма прохода). Для управления «подписчиками» в модуле доступны следующие функции:
Функция | Назначение | Комментарии |
---|---|---|
| Добавить объект подписчика | Функция принимает следующие параметры:
|
remove_listener(key) | Удалить объект подписчика | Единственный аргумент key указывает на добавленного ранее подписчика, которого необходимо «отписать» от получения уведомлений. |
Каждый объект-подписчик должен быть представлен Lua-таблицей со следующими функциями:
Функция | Назначение | Комментарии |
---|---|---|
lonpacs_on_ap_status_changed(token, ap_status) | Получение и обработка изменений состояния точки доступа | В функцию передаются следующие параметры:
|
lonpacs_on_pass_status_changed(token, status, notify_key) | Получение и обработка изменений состояния алгоритма прохода | В функцию передаются следующие параметры:
|
lonpacs_on_connection_changed(token, connection) | Получение и обработка изменений состояния связи с точкой доступа | В функцию передаются следующие параметры:
|
Параметр ap_status
может принимать одно из следующих значений:
Состояние точки доступа | Значение | Описание |
---|---|---|
USER_QUERY | 0 | Точка доступа в состоянии ожидания транзакции |
FORCE_OPEN | 1 | Взлом двери |
EPB | 2 | Старт транзакции прохода по кнопке выхода |
HOLD_OPEN | 5 | Дверь удержана открытой (удержание двери) |
DENIAL | 6 | Завершение транзакции прохода:
|
OPEN | 10 | Дверь открыта при совершении прохода |
DISABLE | 13 | Точка доступа в состоянии "заблокирована".
|
DOOR_CLOSED | 15 |
|
INITIATE_PASS | 18 | Старт транзакции прохода пользователя (при получении разрешения на доступ). Точка доступа переходит в состояние ожидания открытия двери. |
OPEN_BLOCKED | 21 | Точка доступа в состоянии "открыта и заблокирована":
Текущая транзакция пользователя обрывается. |
CLOSE_BLOCKED | 22 | Точка доступа в состоянии "закрыта и заблокирована":
Текущая транзакция пользователя обрывается. |
LOCK_ACTUATOR_ERROR | 32 | Неисправное состояние замка (не является состоянием точки доступа) |
BLOCKED_HOLD_OPEN | 53 | Удержание двери точки доступа в состоянии "закрыта и заблокирована" |
BLOCKED_FORCE_OPEN | 54 | Взлом двери точки доступа в состоянии "закрыта и заблокирована" |
ARMED_CLOSE_BLOCKED | 105 | Точка доступа в состоянии "закрыта и заблокирована постановкой под охрану связанной группы зон":
Текущая транзакция пользователя обрывается. |
ARMED_CLOSE_BLOCKED_FORCE_OPEN | 106 | Взлом двери точки доступа в состоянии "закрыта и заблокирована постановкой под охрану связанной группы зон" |
ap_status
определяет интегральное состояние составляющих точку доступа элементов (замок, дверной контакт). Для получения состояния этих элементов нужно использовать функцию lonpacs.parse_ap_status(ap_status)
.
Функция parse_ap_status
возвращает Lua-таблицу следующего вида:
{ door_state = .. lock_state = .. mode = .. alarm = .. } |
где значение полей таблицы следующее:
Поле | Описание | Возможные значения |
---|---|---|
door_state | Состояние двери (открыта, закрыта, ...) | Возможные значения определены в
|
lock_state | Состояние замка | Возможные значения определены в
|
mode | Режим точки доступа (разблокирована, заблокирована, ...) | Возможные значения определены в
|
alarm | Состояние тревоги точки доступа (удержана дверь и др.) | Возможные значения определены в
|
Значение кода состояния алгоритма прохода (фазы прохода) status,
полученного в функции lonpacs_on_pass_status_changed(token, status, notify_key),
может принимать одно из следующих значений:
Код (условный) | Принимаемое значение | Описание |
---|---|---|
ACS_DENIED | 42 | Доступ запрещен |
NO_PASS | 3 | Проход не совершен |
PASS | 4 | Проход совершен |
ACS_ID_PRESENT | 95 | Предъявлен идентификатор СКУД (запрос пользователя СКУД в базе ЯРС) |
ARM_ID_PRESENT | 107 | Предъявлен идентификатор для управления постановкой на охрану связанной группы зон |
DISARM_ID_PRESENT | 108 | Предъявлен идентификатор для управления снятием с охраны связанной группы зон |
REPEATED_PRESENT | 59 | Повторное предъявление идентификатора в ходе транзакции СКУД |
Модуль предоставляет API для интеграции с подсистемой доступа (только для контроллеров БОРЕЙ и ЯРС). Модуль позволяет либо модифицировать стандартные алгоритмы доступа, либо реализовать собственный алгоритм.
Подсистема доступа в контроллерах БОРЕЙ, ЯРС по своей структуре и поведению отвечает требованиям спецификаций Onvif (Profile C, Access Control Service, Door Control Service). В частности, состояние точек доступа, команды управления ими и другие аспекты отвечают указанным спецификациям. Рекомендуется ознакомиться с данными спецификациями перед использованием модуля |
Подсистема доступа в контроллерах БОРЕЙ, ЯРС поддерживает две точки доступа (поддержка дополнительных точек доступа на модулях расширения ЯРС осуществляется в Lua-модуле lonpacs.lua). Соответственно, первый считыватель относится к первой точке доступа, а второй — ко второй. У каждой точки доступа есть строковой уникальный идентификатор, называемый токеном.
Получить список точек доступа с их идентификаторами можно через поле pacs.ap
, которое заполняется при инициализации модуля и виртуальной Lua-машины (до того, как будет выполняться пользовательский Lua-скрипт). Поле pacs.ap
содержит Lua-таблицу, в которой ключами являются токены точек доступа, а значениями — Lua-таблицы с системными параметрами точек доступа. Структура таблицы представлена в коде ниже:
pacs.ap = { "токен первой точки доступа" = { "#" = 0, ... }, "токен второй точки доступа" = { "#" = 1, ... } } |
Соответственно, для перебора точек доступа (например, чтобы для каждой точки доступа проинциализировать свой алгоритм) удобно использовать следующий код:
for key,item in pairs(pacs.ap) do if item["#"] == 0 or item["#"] == 1 then -- код обработки точки доступа с токеном = key else logger:error("unexpected access point number; #="..item["#"].."; token="..key) end end |
В контроллере БОРЕЙ точек доступа всегда ровно две, с номерами 0 и 1. Точка доступа с номером 0 (у которой значение свойства pacs.ap["токен"]["#"]
равно 0 — это первая точка доступа), точка доступа с номером 1 — вторая.
В настройках доступа у контроллера можно выбрать «Режим работы» — «Две односторонние», «Одна двусторонняя», «Пользовательский». В стандартных режимах работы «Две односторонние» и «Одна двусторонняя» программные средства самостоятельно реализуют алгоритм доступа, таблицы параметров (pacs.ap["токен"]
) содержат параметры, которые пользователь может изменить через веб-приложение. В режиме «Пользовательский» таблицы параметров по умолчанию обычно пусты.
Для реализации собственной логики доступа с помощью Lua-скриптов пользователю следует выбрать в настройках контроллера режим = «Пользовательский». В этом режиме системные параметры алгоритма доступа (которые обрабатываются не в Lua-скрипте, а в основных программных средствах) не задаются через веб-интерфейс, и должны быть определены пользователем прямо в Lua-скрипте. Инструкция по установке системных параметров приведена в разделе «Изменение системных параметров» далее. |
Управление состоянием точки доступа, а также режимом её работы (начало транзакции доступа, завершение транзакции и так далее) осуществляется из Lua-скрипта. Соответствующие функции описаны в разделе «Управление точкой доступа».
В каждый момент времени состояние точки доступа описывается N-мерным вектором:
Режим работы точки доступа |
|
|
Состояние двери | Неизвестно (Unknown) Открыто (Open) Закрыто (Closed) Неисправность (Fault) | Определяется из Lua-скрипта. |
Состояние замка | Неизвестно (Unknown) Открыт (Unlocked) Закрыт (Locked) Неисправность (Fault) | Определяется из Lua-скрипта. |
Тревожный статус | Норма (Normal) Взлом двери (DoorForcedOpen) Удержание двери (DoorOpenTooLong) | Определяется из Lua-скрипта. |
Статус тампера | Неизвестно (Unknown) Корпус закрыт (NotInTamper) Вскрытие корпуса (TamperDetected) | Автоматически определяется программными средствами по факту вскрытия / закрытия корпуса контроллера. Не следует управлять этой осью состояния из Lua-скрипта. |
Точки доступа поддерживают внешние команды управления блокировки, разблокировки, восстановления режима, включения / отключения, разрешения и подтверждения доступа. При обработке таких команд программные средства передают управление в Lua-скрипт. Также при предъявлении идентификатора, изменении состояния периферии (входов), выполенении внешних команд над точками доступа и т.д. подсистема доступа передаёт управление в Lua-скрипт. Пользователь может запрограммировать реакцию на соответствующие события с помощью функций-обработчиков (см. раздел «Функции-обработчики»).
Через каждую точку доступа в один момент времени может осуществляться одна транзакция доступа. Транзакция доступа — это процесс, который начинается с момента идентификации доступа, и завершается при возврате точки доступа в начальное состояние. В случае удержания двери транзакция доступа продолжается.
Транзакция доступа начинается либо вызовом pacs.authenticate
в случае разрешения доступа, либо по вызову pacs_grant
(для случая анонимного доступа). Завершается транзакция по вызову pacs_reset
. Соответствующие функции описаны в разделе «Управление точкой доступа».
В процессе транзакции сохраняются идентификационные признаки посетителя и прочая информация, эти данные подставляются во все извещения, формируемые контроллером.
Часть извещений (в основном о запрещении доступа) формируются программными средствами. Пользователь также может в любой момент времени отправить извещение из Lua-скрипта с помощью функции pacs_notify
, с указанием кода извещения. Для отправки доступно более полусотни извещений. Полный список доступных для отправки извещений приведён в документации на HTTP-API контроллера в части СКУД.
В режиме доступа «Пользовательский» для реализации алгоритма может потребоваться задать из Lua-скрипта для каждой точки доступа системные параметры. Для указания параметров из Lua-скрипта предназначена функция pacs.set_configuration(token, {...})
, в первом аргументе необходимо передать токен точки доступа, во втором аргументе — Lua-таблицу с параметрами. Например:
for key,item in pairs(pacs.ap) do local configuration = {} configuration["input.mode"] = "card" pacs.set_configuration(key, configuration) end |
Ниже приведены основные системные параметры, которые можно / нужно настраивать:
Параметр | Ключ | Значение | Описание |
---|---|---|---|
Режим идентификации | input.mode | Одно значение из: | Позволяет определить требуемый режим идентификации — какие идентификаторы посетителя ожидаются на вход + как они будут проверяться. ВНИМАНИЕ: этот параметр необходимо задать, если из Lua-скрипта будет вызвана функция |
Число попыток ввода данных | input.retry_limit | Целое число больше 0 | В случае, если input.mode равен card_and_pincode — определяет количество попыток ввода пинкода после предъявления карты. |
Время ожидания ввода данных | input.retry_timeout | Целое число больше 0, в секундах | В случае, если input.mode равен card_and_pincode — определяет время ожидания ввода пинкода после предъявления карты. |
Формат карты | other.card_format | Одно значение из: auto , Raw-64 , Raw-VL |
|
Маска (номера карты) | other.card_mask | FFFFFFFFFFFFFFFF | 64 бита маски в формате HEX-строки из 16 символов |
Набор параметров блока «Контроль повторного прохода» | Описание временно недоступно. | ||
Набор параметров блока «Проход под принуждением» | Только в режиме идентификации «Карта и пинкод» Описание временно недоступно. | ||
Набор параметров блока «Проход с подтвержденеим» | Описание временно недоступно. | ||
Набор параметров блока «Доступ по правилу N-лиц» | Описание временно недоступно. |
Модуль позволяет разработчику определить глобальные Lua-функции с заданными именами. Такие функции-обработчики будут вызваны программными средствами контроллера по мере выполнения функций доступа.
В данном случае это должны быть именно «глобальные функции», определённые, например, следующим образом:
Локальные функции с таким же именем не будут вызваны:
|
Ниже приведён список доступных для определения функций-обработчиков:
Функция | Назначение | Комментарии | |
---|---|---|---|
pacs_reader_input(token, data) | К считывателю предъявлен идентификатор | Вызывается тогда, когда к считывателю контроллера предъявлен идентификатор. ВАЖНО: проверка идентификатора ещё не осуществлялась. В случае, если данные предъявлены к считывателю Wiegand / 1-Wire, выполняется разбор считанных битов и определение номера карты / кода предприятия в соответствии с системными параметрами В первом аргументе
Если идентификатор отсутствует (например, не вводился пинкод), то соответствующее поле таблицы также отсутствует. Обычно в коде данной функции выполняется вызов | |
pacs_accessed(token, args) | Получена внешняя команда на инициацию транзакции доступа. | Первый аргумент Второй аргумент
Подробную спецификацию команды инициации транзакции доступа смотри в спецификациях Onvif. | |
pacs_granted(token) | Доступ разрешён (в результате проверки идентификатора) | Данная функция-обработчик вызывается тогда, когда вызов Первый аргумент | |
pacs_denied(token) | Доступ запрещён (в результате проверки идентификатора) | Данная функция-обработчик вызывается тогда, когда в результате Первый аргумент | |
pacs_enabled(token) | Точка доступа включена (по внешней команде) | Первый аргумент token — токен точки доступа. | |
pacs_disabled(token) | Точка доступа отключена (по внешней команде) | Первый аргумент token — токен точки доступа. | |
pacs_identification(token, event) | Изменилось состояние ожидания ввода данных в режиме «Карта и пинкод» | Первый аргумент Второй аргумент | |
pacs_external_locked(token) → boolean | Должен быть восстановлен режим работы точки доступа (обычный режим работы) | Режим работы точки доступа должен быть восстановлен — по внешней команде (из веб-интерфейса или по Onvif; см. Onvif Profile C). Это функция-обработчик для внешней команды, обычно в коде данной функции выполняется вызов Функция должна возвращать булевое значение — Первый аргумент | |
pacs_external_unlocked(token) → boolean | Точка доступа должна быть разблокирована | Режим работы точки доступа должен быть изменён на «Разблокировано» — по внешней команде (из веб-интерфейса или по Onvif; см. Onvif Profile C). Это функция-обработчик для внешней команды, обычно в коде данной функции выполняется вызов Функция должна возвращать булевое значение — Первый аргумент | |
pacs_external_blocked(token) → boolean | Точка доступа должна быть заблокирована | Режим работы точки доступа должен быть изменён на «Заблокировано» — по внешней команде (из веб-интерфейса или по Onvif; см. Onvif Profile C). Это функция-обработчик для внешней команды, обычно в коде данной функции выполняется вызов Функция должна возвращать булевое значение — Первый аргумент | |
pacs_external_authorization(token, decision) | Разрешение доступа по внешней команде | Первый аргумент token — токен точки доступа. | |
pacs_input(port, device, type_, id, raw) | Изменение состояния элемента периферии | Параметры Параметр Параметр Параметр | |
pacs_cancel_transaction(token) | Получена внешняя команда на прерывание транзакции доступа | Первый аргумент token — токен точки доступа. |
При использовании стандартных алгоритмов «Две односторонних точки доступа», «Одна двусторонняя точка доступа» перечисленные в таблице функции-обработчики уже определены, в них выполняется логика стандартных алгоритмов доступа. Пользователь может переопределить эти обработчики в своём скрипте. Таким образом, переопределив ВСЕ функции пользователь реализует полностью свою логику доступа, НО при этом получит доступ ко всем параметрам, задаваемым для стандартных алгоритмов через веб-интерфейс — через поле |
При изменении состояния какого-либо элемента периферии (обычно, это различные входы) вызывается функция-обработчик pacs_input
. Ниже приведён Lua-код, который позволит в зависимости от типа элемента периферии получить его логическое состояние.
local fec = require("fec") -- Логическое состояние элемента local VALUE = { OFF = 0, ON = 1, SHORT = 2, BROKEN = 3 } -- Получение логического состояния для элемента типа «Сухой контакт» function get_dry_contact_value(raw, invert) if raw == 1 then if invert then return VALUE.OFF else return VALUE.ON end else if invert then return VALUE.ON else return VALUE.OFF end end end -- Получение логического состояния для элемента типа «Резистивный шлейф» function get_rin_value(raw,invert) if raw <= 17 then -- эмпирический порог резистивного шлейфа if invert then return VALUE.OFF else return VALUE.ON end else if invert then return VALUE.ON else return VALUE.OFF end end end -- Получение логического состояния входов разного типа -- Дополнительный аргумент invert позволяет обрабатывать настройку вида «нормально-открыт» function get_input_value(raw, invert, type_) if (type_ == fec.TYPE.DRY_CONTACT) then return get_dry_contact_value(raw, invert) elseif (type_ == fec.TYPE.RADIAL_INPUT) then return get_rin_value(raw, invert) else log_error("invalid type: "..type_) return 0 end end |
Для управления точкой доступа / транзакцией доступа по выбранной точке доступа предназначены следующие функции:
Функция | Назначение | Комментарии | |
---|---|---|---|
pacs.authenticate(token, {...}) | Выполнить проверку переданных идентификаторов и начать транзакцию доступа | Первый аргумент — токен точки доступа. Второй аргумент — Lua-таблица с идентификаторами (такая же, какая получена в функции-обработчике
В результате проверки будет вызвана функция обработчик Если передан transaction_uuid, то соответствующее значение будет использоваться в роли идентификатора транзакции и будет подставлено во все отправляемые извещения. Если значение не будет указано, то будет сгенерирован уникальный UUID транзакции. ВАЖНО: если таблица во втором аргументе будет пуста, то проверка идентификаторов по базе данных проводиться не будет, автоматически будет выдано разрешение на доступ, будет вызвана функция-обработчик | |
pacs_reset(token) | Восстановить обычный режим работы точки доступа | Первый аргумент — токен точки доступа. ВАЖНО: текущая транзакция прекращается, все связанные с транзакцией данные (пропуска и пр.) очищаются. Данную функцию обязательно надо вызвать при завершении транзакции доступа. | |
pacs_block(token) | Перевести точку доступа в состояние «Заблокировано» | Первый аргумент — токен точки доступа. | |
pacs_unlock(token) | Перевести точку доступа в состояние «Разблокировано» | Первый аргумент — токен точки доступа. | |
pacs_pause(token) | Прекратить приём идентификаторов на точке доступа | Первый аргумент — токен точки доступа. Транзакция доступа не прерывается. Обычно используется при переходе в состояния типа «Взлом двери» или «Удержание двери». | |
pacs_grant(token) | Разрешить анонимный доступ и начать анонимную транзакцию доступа | Обычно применяется для начала транзакции по кнопке выхода. Поведение отличается от | |
pacs_notify(token) | Отправить извещение с заданным кодом | Доступный список кодов см. в документации на HTTP-API контроллера в части СКУД. | |
pacs_update_door_state(token, state) | Изменить состояние точки доступа | Первый аргумент — токен точки доступа. Второй аргумент — Lua-таблица со значением состояния по различным «осям»:
Во втором аргументе можно отправлять только те «оси» состояния, которые необходимы. Доступные значения состояния см. в разделе «Общие сведения». |
Описание временно недоступно.
Модуль предоставляет функции для перманентного сохранения и последующего чтения конфигурационных параметров или параметров скрипта автоматизации.
В некоторых случаях может потребоваться сохранять состояние или параметры работы скрипта автоматизации при перезапуске продукта. Или, например, может возникнуть потребность, чтобы определённые параметры были сохранены в резервной копии и восстановлены в случае сбоя файловой системы на IP-контроллере (БОРЕЙ, ЯРС и пр.). Для работы с такими данными и предназначен модуль storage.lua
.
Модуль позволяет сохранять в персистентное хранилище Lua-таблицы с данными под заданным именем, а впоследствии извлекать их из хранилища по имени. Таблица с данными может содержать только пары «ключ = значение», где «ключ» это всегда строка, а «значение» может быть строкового, числового или булевого типа.
Для помещения данных в хранилище предназначена функция storage.set(ключ, данные)
, для сохранения — storage.save(ключ)
, для извлечения — storage.get(ключ)
.
Вызов функции |
Пример использования модуля приведён ниже:
local storage = require("storage") local my_options = storage.get("my_key") my_options.param1 = "A" my_options.param2 = 42 storage.save("my_key") local another_options = { param1 = "B", param2 = 43 } storage.set("my_key", another_options) -- my_options более не ссылается на объект в хранилище! storage.save("my_key") |
Описание временно недоступно.
Данный модуль предоставляет для скрипта автоматизации две функции для выполнения отложенных во времени вычислений. Первая функция — это set_timeout
. Она предназначена для разового выполнения некоторой Lua-функции спустя заданное количество времени. Вторая функция — set_interval
. Она позволяет запланировать выполнение некоторой Lua-функции каждые N миллисекунд. Функция будет выполняться периодически до тех пор, пока задание на выполнение не будет явно отменено (см. clear_interval
далее) или Lua-машина не будет перезапущена.
Также модуль предоставляет две функции для отмены запланированных ранее заданий: clear_timeout
и clear_interval
.
Для использования функций модуля не требуется ничего подключать с помощью require. Функции |
Запланировать вызов указанной Lua-функции спустя заданное количество миллисекунд.
Полная сигнатура функции: set_timeout(имя-функции, длительность, ключ)
, где
При вызове set_timeout
возвращает уникальный идентификатор созданного задания на отложенное выполнение. Это значение можно использовать в последующем вызове clear_timeout
для отмены запланированного ранее задания.
Пример:
local log = require("log") local logger = log.get_logger("script.lua") local key1_id = set_timeout("my_timeout", 10000, "key1") -- выполнить my_timeout через 20 секунд с key1 local key2_id = set_timeout("my_timeout", 20000, "key2") -- выполнить my_timeout через 20 секунд с key2 function my_timeout(key) if key == "key1" then logger:debug("stopping timeout on key2") clear_timeout(key2_id) -- отменяем задание с key2 elif key == "key2" then logger:error("this should be never invoked") else logger:error("unexpected key="..key) end end |
Функция позволяет отменить ранее запланированное задание: clear_timeout(ID задания)
, где ID задания
— результат выполнения функции set_timeout
.
Сигнатура налогична set_timeout: set_interval(имя-функции, длительность, ключ)
, где
Также как и в JavaScript, рекомендуется избегать использования set_interval, сделав выбор в пользу рекурсивного set_timeout. |
Аналогично clear_timeout функция позволяет отменить запланированное ранее периодическое задание: clear_interval(ID задания)
, где ID задания
— результат выполнения функции set_interval
.
Описание временно недоступно.