Руководство по скриптам Lua

Одной из отличительных особенностей всех продуктов комплекса НЕЙРОСС и, в частности, IP-контроллеров БОРЕЙ, ЯРС v.1 (снят с производства!) и других является возможность модификации и расширения алгоритмов работы продукта посредством скриптов автоматизации. С помощью скрипта возможно, например, изменить или полностью заменить алгоритм доступа в контроллере БОРЕЙ. Или реализовать логику сопряжения со внешней информационной системой по протоколу HTTP. Или управлять исполнительными устройствами по заданному алгоритму.

В данном документе приведены общие сведения о скриптах автоматизации, их возможностях и руководство программиста по написанию таких скриптов.

Оглавление

Общие сведения

Скрипт автоматизации — текстовый сценарий, выполнение которого осуществляется программными средствами продукта.

Данный сценарий всегда один. Он может быть пустым — в таком случае скрипт не делает ничего. В скрипте могут быть команды управления — они выполняются по мере выполнения скрипта.

Скрипт автоматизации должен быть написан на языке Lua (версия 5.1). Разработчику доступны стандартные средства языка (операторы, структуры данных и др.), часть функций стандартной библиотеки (см. далее), а также наборы констант и функций, определённых в прикладных Lua-модулях продукта. Прикладные Lua-модули специально разработаны для упрощения написания скриптов и двустороннего взаимодействия с программными средствами продукта — чтобы можно было из скрипта вызывать какие-либо функции продукта или, наоборот, передавать управление в скрипт в процессе функционирования продукта.

Скрипт автоматизации выполняется в «песочнице» — защищённом окружении. Если в ходе работы скрипта возникает ошибка, то выполнение скрипта просто прерывается — нарушается работа функций, так или иначе связанных со скриптами (например, алгоритмов доступа), НО общая работоспособность продукта сохраняется, на стабильность работы программных средств поведение скрипта не влияет.

Как редактировать скрипт

Для удобство редактирования и отладки скрипта автоматизации предназначен текстовый online-редактор, доступный в наших продуктах по адресу http://[ip-address]/lua-editor/ или http://[ip-address]/internal/lua-editor/.

1. В левом блоке — текст скрипта автоматизации. Внесите в него изменения, для сохранения нажмите на кнопку «Сохранить» внизу.
2. В правом блоке можно просматривать lua-код модулей и сниппеты — примеры скриптов автоматизации. Для просмотра сниппета или модуля выберите его в раскрывающемся списке под правым блоком.
   1. Lua-код модулей обычно содержит определение констант, структур, функций, а также обеспечивает удобную для разработчика «обёртку» на доступными функциями основных программных средств.
      ЗАМЕЧАНИЕ: в списке обычно можно посмотреть Lua-код всех модулей всех продуктов, их можно подключить к скрипту автоматизации, но фактически «отсутствующий» модуль просто не будет работать.
   2. Сниппеты — блоки кода, из которых можно почерпнуть идеи при разработке скрипта. Или можно скопировать «куски» сниппета в свой скрипт. Библиотека сниппетов постоянно пополняется разработчиками с добавлением примеров создания скриптов автоматизации.
3. При сохранении скрипта автоматизации выполнение текущего скрипта будет автоматически прервано. После чего будет запущен новый скрипт.

Скриншот редактора скриптов приведён на изображении ниже.

Как отлаживать скрипт

Сообщения об ошибках в Lua-скрипте, а также отладочные сообщения, выводимые из скрипта с помощью модуля log.lua, записываются в журнал аудита. Просмотр этих сообщений в реальном времени возможен при помощи веб-приложения «Журнал аудита», доступного с веб-страницы Рабочий стол.

1. Авторизуйтесь в веб-интерфейсе и перейдите на Рабочий стол.
2. Перейдите в веб-приложение «Журнал аудита».
3. На второй вкладке «Фильтры» выберите в списке логгер web.
4. В настройках фильтрации укажите следующие строки (первая строка:
   1. * — OFF
   2. LuaManager — DEBUG
   3. lua_scall — DEBUG
   4. neyross::LogLuaModule — DEBUG
5. Пример корректно настроенного логгера:
   
6. Перейдите на третью вкладку «Живой журнал».
7. Установите флаги DEBUG, INFO, WARN, ERROR для вывода сообщений всех возможностей уровней тревожности.
   
8. При выполнении Lua-скрипта на странице будут появляться соответствующие сообщения. Более свежие сообщения выводятся сверху.
   

Руководство разработчика

Общие сведения о Lua

Скрипт автоматизации должен быть написан на языке 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, поддерживаемой продуктами НЕЙРОСС.

Ограничения стандартной библиотеки

В скриптах автоматизации доступны следующие разделы стандартной библиотеки:

• Basic Functions
• Coroutine Manipulation
• Modules
• String Manipulation
• Table Manipulation
• Mathematical Functions

Следующие разделы недоступны (не могут быть использованы) в скрипте автоматизации:

• Input and Output Facilities
• Operating System Facilities

Прикладные Lua-модули

В таблице ниже перечислены прикладные модули, их описание и продукты, в которых эти модули могут быть использованы.

Подключение прикладного Lua-модуля осуществляется функцией require. Рекомендуемая форма использования:

local log = require("log")

Вызвать функцию Lua-модуля в таком случае можно следующим образом, например:

local logger = log.get_logger("MyLogger")

alarm.lua

Описание временно недоступно.

common.lua

Данный модуль предоставляет общесистемные функции. Перечень функций приведён в таблице ниже.

deviceio.lua

Описание временно недоступно.

fec.lua

Данный модуль позволяет управлять выходами (на плате контроллера БОРЕЙ, ЯРС, а также на модулях расширения АМ-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

Модуль позволяет отправлять HTTP-запросы прямо из Lua-скрипта, а также асинхронно обрабатывать ответы на отправленные ранее запросы.

Для отправки запроса и обработки ответа необходимо:

1. Определить объект-обработчик ответа (Lua-таблицу) с методом on_http_response(данные ответа).
2. Создать объект-запрос посредством вызова функции-фабрики http.with(объект-обработчик). Функция возвращает создаёт и возвращает объект-запрос.
3. Вызывать на объекте-запросе метод 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-запроса

Можно указать произвольные заголовки 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-запроса

Модуль позволяет отправлять в 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" }
}

Обработка ответа

При поступлении ответа или сбое при отправке запроса асинхронно вызывается метод 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-таблицу), либо текстом / строкой (в остальных случаях).

ignis.lua

Описание временно недоступно.

log.lua

Модуль позволяет выводить текстовые сообщения в журнал аудита.

Для вывода сообщений разработчику необходимо:

1. Подключить модуль log.lua в скрипт автоматизации командой require.
2. Создать объект-логгер с заданным именем, вызвав функцию log.get_logger(имя-логгера).
3. В требуемом месте скрипта вывести сообщение в журнал аудита с заданным уровнем «тревожности», вызвав один из методов 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))

Обратите внимание:

1. В журнал аудита сообщения выводятся от имени компонента программных средств neyross::LogLuaModule, а потому в настройки журнала аудита следует добавить соответствующий фильтр, например: neyross::LogLuaModule | DEBUG.
2. Имя объекта-логгера также выводится в журнале аудита перед заданным текстовым сообщением. В скрипте автоматизации можно создать и использовать любое количество объектов-логгеров с разными именами. Это позволяет различить сообщения в журнале аудита от разных логических разделов скрипта автоматизации.
3. В журнале аудита для каждой записи также выводится имя функции (если таковая есть), в которой вызван объект-логгер и номер соответствующей строки в скрипте, что ещё более упрощает понимание — к какой части скрипта относится соответствующее сообщение в журнале аудита.
4. Различные методы объекта-логгера выводят в журнал сообщения с разным уровнем «тревожности». Доступны следующие методы и уровни по приоритетам (от низкого / неважного до высокого / тревожного):
   1. trace (только для отладочного режима, в журнал не попадают никогда);
   2. debug (отладочные сообщения);
   3. info (информационные сообщения);
   4. warn (сообщения-предупреждения);
   5. error (сообщения об ошибках).
5. Методы объекта-логгера принимают на вход один строковой параметр. Для формирования строки из нескольких параметров используйте оператор конкатенации строк .. и функцию приведения нестроковых типов к строке tostring из стандартной библиотеки.

longate.lua

Описание временно недоступно.

loninput.lua

Модуль предоставляет API для мониторинга состояния входов (зон) на модулях расширения ЯРС.

loninput.lua позволяет «подписаться» на изменения состояния входов. Для управления «подписчиками» в модуле доступны следующие функции:

Каждый объект-подписчик должен быть представлен Lua-таблицей с функцией on_loninput_input_state_changed(device_address, input_index, raw_state, logical_state).

Данная функция будет вызвана:

1. при изменении состояния входа какого-либо модуля расширения,
2. сразу в процессе добавления подписчика через add_listener для всех входов всех модулей (что позволяет получить текущее состояние нужных входов в момент добавления подписчика).

В функцию on_loninput_input_state_changed передаются следующие параметры:

Логическое состояние входа может быть следующим:

• 0 (LOGICAL_INPUT_STATE.UNKNOWN) — значение не известно;
• 1 (LOGICAL_INPUT_STATE.OFF) — вход выключен, нормальное состояние (логический 0);
• 2 (LOGICAL_INPUT_STATE.ON) — вход включен, тревожное состояние (логическая 1).

lonpacs.lua

Модуль предоставляет API для интеграции с подсистемой доступа модулей расширения ЯРС, таких как МДС и М2. Модуль позволяет модифицировать стандартные алгоритмы доступа.

Получить список точек доступа с их идентификаторами можно через поле lonpacs.ap_instance, которое заполняется при инициализации модуля и виртуальной Lua-машины (до того, как будет выполняться пользовательский Lua-скрипт). Поле lonpacs.ap_instance содержит Lua-таблицу, в которой ключами являются токены точек доступа, а значениями — Lua-таблицы с системными параметрами точек доступа. Структура таблицы представлена в коде ниже:

lonpacs.ap = {
  "токен первой точки доступа" = {
    ...
  },
  "токен второй точки доступа" = {
    ...
  },
  ... -- и так далее
}

Каждая точка доступа в списке — это либо точка доступа модуля расширения МДС, либо одна из точек доступа М2.

Управление точкой доступа

Для управления точками доступа на модулях расширения доступна функция transmit_status(token, status), которая позволяет отправлять модулям команды управления. Функция принимает следующие параметры:

Для управления точкам доступа доступны следующие команды (значения параметра status):

Состояние точки доступа

Модуль lonpacs.lua позволяет «подписаться» на события изменения состояния точек доступа, мониторинга связи с точками доступа, изменения состояния прохода (фазы алгоритма прохода). Для управления «подписчиками» в модуле доступны следующие функции:

Каждый объект-подписчик должен быть представлен Lua-таблицей со следующими функциями:

Параметр ap_status может принимать одно из следующих значений:

ap_status определяет интегральное состояние составляющих точку доступа элементов (замок, дверной контакт). Для получения состояния этих элементов нужно использовать функцию lonpacs.parse_ap_status(ap_status). 

Функция parse_ap_status возвращает Lua-таблицу следующего вида:

{
  door_state = ..
  lock_state = ..
  mode = ..
  alarm = ..
}

где значение полей таблицы следующее:

Значение кода состояния алгоритма прохода (фазы прохода) status, полученного в функции lonpacs_on_pass_status_changed(token, status, notify_key), может принимать одно из следующих значений:

pacs.lua

Модуль предоставляет API для интеграции с подсистемой доступа (только для контроллеров БОРЕЙ и ЯРС). Модуль позволяет либо модифицировать стандартные алгоритмы доступа, либо реализовать собственный алгоритм.

Общие сведения

Подсистема доступа в контроллерах БОРЕЙ, ЯРС поддерживает две точки доступа (поддержка дополнительных точек доступа на модулях расширения ЯРС осуществляется в 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-скрипта. Соответствующие функции описаны в разделе «Управление точкой доступа».

В каждый момент времени состояние точки доступа описывается N-мерным вектором:

Точки доступа поддерживают внешние команды управления блокировки, разблокировки, восстановления режима, включения / отключения, разрешения и подтверждения доступа. При обработке таких команд программные средства передают управление в 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

Ниже приведены основные системные параметры, которые можно / нужно настраивать:

Функции-обработчики

Модуль позволяет разработчику определить глобальные Lua-функции с заданными именами. Такие функции-обработчики будут вызваны программными средствами контроллера по мере выполнения функций доступа.

function pacs_reader_input(token, data)
  -- тело функции
end

local pacs_reader_input = function(token, data)
  -- функция не будет вызвана
end

Ниже приведён список доступных для определения функций-обработчиков:

{
  "facility_code" = "123",
  "card_number" = "12345",
  "pincode" = "12345"
}

{
  "use_extended_time" = true,
  "access_time_duration" = число (unix-timestamp),
  "open_too_long_time_duration" = число (unix-timestamp),
  "pre_alarm_time_duration" = число (unix-timestamp)
}

Изменение состояния периферии

При изменении состояния какого-либо элемента периферии (обычно, это различные входы) вызывается функция-обработчик 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

Управление точкой доступа

Для управления точкой доступа / транзакцией доступа по выбранной точке доступа предназначены следующие функции:

{
  "facility_code" = "123",
  "card_number" = "12345",
  "pincode" = "12345",
  "transaction_uuid" = "..."
}

{
  "lock" = Unlocked,
  "door" = Open,
  "mode" = Accessed,
  "alarm" = Normal,
}

Поиск в базе данных

Описание временно недоступно.

storage.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")

tenso.lua

Описание временно недоступно.

timer.lua

Данный модуль предоставляет для скрипта автоматизации две функции для выполнения отложенных во времени вычислений. Первая функция — это set_timeout. Она предназначена для разового выполнения некоторой Lua-функции спустя заданное количество времени. Вторая функция — set_interval. Она позволяет запланировать выполнение некоторой Lua-функции каждые N миллисекунд. Функция будет выполняться периодически до тех пор, пока задание на выполнение не будет явно отменено (см. clear_interval далее) или Lua-машина не будет перезапущена.

Также модуль предоставляет две функции для отмены запланированных ранее заданий: clear_timeout и clear_interval.

set_timeout

Запланировать вызов указанной Lua-функции спустя заданное количество миллисекунд.

Полная сигнатура функции: set_timeout(имя-функции, длительность, ключ), где

• имя функции — строка, имя Lua-функции для вызова;
• длительность — число, задержка выполнения функции, в миллисекундах;
• ключ — строка, ключ, по которому можно будет понять в Lua-функции, кто и когда запланировал её отложенный вызов.

При вызове 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

Функция позволяет отменить ранее запланированное задание: clear_timeout(ID задания), где ID задания — результат выполнения функции set_timeout.

set_interval

Сигнатура налогична set_timeout: set_interval(имя-функции, длительность, ключ), где

• имя функции — строка, имя Lua-функции для вызова;
• интервал — число, период выполнения функции, в миллисекундах;
• ключ — строка, ключ, по которому можно будет понять в Lua-функции, кто и когда запланировал её отложенный вызов.

clear_interval

Аналогично clear_timeout функция позволяет отменить запланированное ранее периодическое задание: clear_interval(ID задания), где ID задания — результат выполнения функции set_interval.

terminal.lua

Описание временно недоступно.