Объекты
Объекты - это универсальная сущность для хранения и обмена данными между подсистемами шлюза, например между скриптами LUA. Также объекты позволяют выполнять скрипты при изменении своих значений.
К объектам можно обращаться из скриптовLUA, HTTP API и из Simple Bind
Веб интерфейс
Просмотреть текущие объекты можно на странице Objects.
В таблице отображаются следующие данные:
- имя объекта
- тип данных:
- STR - Строки (используется по умолчанию)
- BOOL - Бинарный (true / false)
- INT - Целое число
- FLOAT - Дробное число
- JSON - строка формата JSON
- значения - текущее и предыдущее
- время изменения - timestamp последнего и предпоследнего изменения
- флаги:
- A (Ack) - при изменении значения объекта передан признак Ack (описание ниже).
- M (MQTT Notify) - при изменении значения объекта значение передается в MQTT (описание ниже). Ранее обозначался символом
N
- W (Write) - изменение значения при каждом обращении на запись объекта
Инициализация объектов
Объекты хранятся только в памяти и не сохраняются во флеш-память. Поэтому, при необходимости, инициализировать объекты можно в стартовом скрипте init.lua
, с помощью функций obj.setOpt(), obj.set()
. Если начальные значения задавать не требуется, то инициализировать не обязательно, поскольку объект создается при первом к нему обращении.
Флаги
Позволяют отслеживать функционал объектов. Установка доступна из скриптов LUA. Чтение - как из LUA, так и из HTTP API.
Обратная связь при изменении значения объектов
Флаг A
- ACK
Объекты поддерживают установку флага обратной связи, таким образом можно в вызываемом скрипте можно получить информацию об источнике изменения.
Флаг обратной связи виден в веб-интерфейсе (A
), а так же возвращается в LUA и HTTP API командах. Также этот флаг передается в событии Event.Obj.Ack
скрипту, вызванному по изменению или записи объекта.
MQTT Notify
Флаг M
- MQTT Notify
Шлюз может отправлять уведомления в MQTT при изменении объекта.
При поднятом флаге, шлюз будет публиковать в топик вида: zgwXXXX/obj/OBJ_NAME
Для изменения объекта необходимо отправить значение объекта в топик zgwXXXX/obj/OBJ_NAME/set
Для запроса текущего значения объекта необходимо отправить пустой топик zgwXXXX/obj/OBJ_NAME/get
Изменение значения при каждом обращении на запись объекта
Флаг W
- Write
При поднятом флаге запись значения в объект производится при каждом к нему обращении.
APIs для работы с объектами
LUA
События
При вызове скрипта привязанного к объекту вызывается событие с типом SCRIPT_EVENT_TYPE_OBJ_CHANGE
и значением 2.
Event.Obj.Name
- имя объекта, который вызвал скриптEvent.Obj.Ack
- флаг обратной связи объектаEvent.Obj.Value
- текущее значениеEvent.Obj.OldValue
- предыдущее значение
obj.setOpt()
Изменения типа данных, записываемых в объект, управление флагом передачи уведомлений в MQTT. Если объекта не существует, он будет создан.
obj.setOpt(name, type[, flagMQTT])
-- name - STR, имя объекта
-- type - STR, тип хранимых данных: STR, INT, BOOL, FLOAT, JSON
-- flagMQTT - BOOL, флаг передачи уведомлений в MQTT
-- false = передача выключена
-- true = передача включена. В таблице объектов (WebUI/Objects) отображается сомволом M (MQTT Notify)
obj.set()
Запись данных в объект, управление флагом обратной связи. Если объекта не существует, он будет создан.
result = obj.set(name, value[, flagACK])
-- name - STR, имя объекта
-- value - записываемые данные, любого типа
-- flagACK - BOOL, флаг обратной связи
-- true = включен. В таблице объектов отображается символом A (ACK)
-- false = выключен. В таблице объектов не отображается
-- result - BOOL, true - значение изменено и успешно записано, false - значение не изменилось, поэтому не записано
obj.get()
Получение данных, хранящихся в объекте
result = obj.get(name)
-- name - STR, имя объекта
-- result - текущее значение или NIL если объект не найден
В объекте хранится текущее значение, предыдущее и состояние флага ACK.
Пример получения всех значений:
local current_value, previos_value, flag_ack = obj.get("object_name")
-- переменные будут содержать:
-- current_value = текущее значение
-- previos_value = предыдущее значение
-- flag_ack = статус флага ACK: true|false
obj.getTime()
Получение тайм-штампов изменения текущего и предыдущего значений. Оба значения можно получить так-же как в obj.get()
obj.getTime(name)
-- name - STR, имя объекта
obj.setScript()
Привязка к объекту скрипта, который будет выполняться при каждом изменении значения объекта или при каждой его записи. Если объекта не существует, он будет создан.
obj.setScript(name, script.lua[, run_on_write])
-- name - STR, имя объекта
-- script.lua - STR, имя файла скрипта с расширением
-- run_on_write - BOOL, false (default) = запуск при обновлении значения; true = запуск каждый раз при записи значения в объект + поднимается флаг W
obj.onChange() - deprecated
Привязка к объекту скрипта, который будет выполняться при каждом изменении значения объекта. Если объекта не существует, он будет создан.
obj.onChange(name, script.lua)
-- name - STR, имя объекта
-- script.lua - STR, имя файла скрипта с расширением
obj.remove()
Удаление объекта
result = obj.remove(name)
-- name - имя объекта
-- result - BOOL, true - успех, false - объект не найден
HTTP API
Получить список объектов
GET /api/obj
Установить значение объекта
POST /api/obj?name=XXX&value=YYY
<!--
name - имя объекта
value - значение -->
Удалить объект с устройства
DELETE /api/obj?name=obj_name
Получить значение объекта
GET /api/obj?name=XXX
Флаги возвращаются в поле flags: flag_value
:
flag_value = 0: ACK=0; MQTT=0
flag_value = 1: ACK=0; MQTT=1
flag_value = 2: ACK=1; MQTT=0
flag_value = 3: ACK=1; MQTT=1
Примеры
Установки значения объекта
obj.set("security.status", true)
Установка значения с передачей ACK
obj.set("security.status", true, true)
Пример скрипта-обработчика событий обращения к объекту
Скрипт привязывается к объекту командой obj.setScript()
в init.lua
local status = ""
local current_status, previous_status, ack = obj.get("security.status")
-- добавим обработчик булевых значений для склейки со строками
if current_status == true then
status = "true"
else
status = "false"
end
-- отправляем уведомление только в случае изменения значений с признаком ackw
if ack == true then
telegram.send("wsecurity status is " .. status)
end
Удаление объекта
obj.remove("security.status")
Изменение типа переменной
obj.setOpt("security.status", "INT")
Включение уведомления об изменении в MQTT
obj.setOpt("security.status", "INT", true)
Получение времени изменения объекта
local curr, prev = obj.getTime("security.status")
print("Время предыдущего изменения:" .. prev .. ", И последнего: " .. curr .. " длительность события: " .. curr-prev)
Сетевые объекты
Используются для синхронизации данных между несколькими шлюзами, при изменении объекта на одном, он так же изменится и на остальных шлюзах.
Данный функционал в разработке.