Объекты

Объекты - это универсальная сущность для хранения и обмена данными между подсистемами шлюза, например между скриптами LUA. Также объекты позволяют выполнять скрипты при изменении своих значений.

К объектам можно обращаться из скриптов LUA, HTTP API и из Simple Bind

Веб интерфейс

Управление объектами доступно на странице Objects. Здесь доступно создание новых объектов, изменение и удаление существующих.

object

В таблице отображаются следующие данные:

имя объекта
тип данных:
- STR - Строки (используется по умолчанию)
- BOOL - Бинарный (true / false)
- INT - Целое число
- FLOAT - Дробное число
- JSON - строка формата JSON
значения - текущее и предыдущее
время изменения - timestamp последнего и предпоследнего изменения
флаги:
- A (Ack) - при изменении значения объекта передан признак Ack (описание ниже).
- M (MQTT Notify) - при изменении значения объекта значение передается в MQTT (описание ниже).
- N (Network) - обмен с соседними шлюзами в сети посредством подсистемы LocalLink. Начиная с версии 2024.12.19d2
- W (Write) - изменение значения при каждом обращении на запись объекта

Также имеются кнопки управления:

- обновить список объектов
- добавить объект
- редактировать объект
- удалить объект

Управление объектами через веб-интерфейс

Для создания нового объекта нажать "плюсик" . Откроется форма создания объекта

Заполнить необходимые данные и сохранить.

Здесь же можно изменить существующий объект по кнопке .

Инициализация объектов

Объекты хранятся только в памяти и не сохраняются во флеш-память. Поэтому, при необходимости, инициализировать объекты можно в стартовом скрипте init.lua, с помощью функций obj.set(), obj.setShare(), obj.setType() или через веб-интерфейс, как описано выше. Если начальные значения задавать не требуется, то инициализировать не обязательно, поскольку объект создается при первом к нему обращении.

Флаги

Позволяют отслеживать функционал объектов. Установка доступна из скриптов LUA. Чтение - как из LUA, так и из HTTP API.

Обратная связь при изменении значения объектов

Флаг A - ACK

Объекты поддерживают установку флага обратной связи, таким образом в вызываемом скрипте можно получить информацию об источнике изменения.

Например, есть два скрипта. Один записывает значение в объект со своей периодичностью, а другой скрипт значение считывает со своей периодичностью. Необходимо, чтобы пока второй скрипт не считал значение, первый бы не записывал. Для этого первый скрипт при записи выставляет флаг А, если его нет, а второй скрипт при чтении флаг сбрасывает. Вариантов использования масса. Например, можно использовать как дополнительное поле данных в объекте).

Флаг обратной связи виден в веб-интерфейсе (A), а так же возвращается в LUA и HTTP API командах. Также этот флаг передается в событии Event.Obj.Ack скрипту, вызванному по изменению или записи объекта.

MQTT Notify

Флаг M - MQTT Notify

Шлюз может отправлять уведомления в MQTT при изменении объекта. Установка флага доступна как в веб-интерфейсе, так из LUA

При поднятом флаге, шлюз будет публиковать в топик вида: zgwXXXX/obj/OBJ_NAME

Для изменения объекта необходимо отправить значение объекта в топик zgwXXXX/obj/OBJ_NAME/set

Для запроса текущего значения объекта необходимо отправить пустой топик zgwXXXX/obj/OBJ_NAME/get

Network

Флаг N - Network

Сетевые объекты используются для синхронизации данных между несколькими шлюзами. При изменении объекта на одном, он так же изменится и на остальных шлюзах.

При установленном флаге объект и его значения передаются на соседние шлюзы в одной локальной сети. Установка флага доступна как в веб-интерфейсе, так из LUA

Изменение значения при каждом обращении на запись объекта и вызов скрипта

Флаг W - Write

Установка доступна как из веб-интерфейса, так из LUA

При поднятом флаге запись значения в объект производится при каждом к нему обращении. При каждой записи в объект значения, запись производится даже если значение не изменилось. Таким образом, если к объекту привязан скрипт, то он будет вызываться при каждом обращении к объекту на запись. Однако, в таком случае не получится отслеживать время изменения значения.

APIs для работы с объектами

LUA

События

При вызове скрипта привязанного к объекту вызывается событие с типом SCRIPT_EVENT_TYPE_OBJ_CHANGE и значением 2.

Event.Obj.Name - имя объекта, который вызвал скрипт
Event.Obj.Ack - флаг обратной связи объекта
Event.Obj.Value - текущее значение
Event.Obj.OldValue - предыдущее значение

obj.setType()

Изменение типа данных, записываемых в объект. Если объекта не существует, он будет создан.

lua

obj.setType(name, type)
-- name - STR, имя объекта
-- type - STR, тип хранимых данных: STR, INT, BOOL, FLOAT, JSON

obj.setType(name, type)
-- name - STR, имя объекта
-- type - STR, тип хранимых данных: STR, INT, BOOL, FLOAT, JSON

obj.setShare()

Управление флагами распространения объекта.

lua

obj.setShare(name, mqtt, network)
-- name - STR, имя объекта
-- mqtt - BOOL, флаг передачи уведомлений в MQTT
  -- false = передача выключена
  -- true = передача включена. В таблице объектов (WebUI/Objects) отображается символом M (MQTT Notify)
-- network - BOOL, флаг обмена объектом с соседними шлюзами
  -- false = обмен выключен
  -- true = обмен включен. В таблице объектов (WebUI/Objects) отображается символом N (Net Notify)

obj.setShare(name, mqtt, network)
-- name - STR, имя объекта
-- mqtt - BOOL, флаг передачи уведомлений в MQTT
  -- false = передача выключена
  -- true = передача включена. В таблице объектов (WebUI/Objects) отображается символом M (MQTT Notify)
-- network - BOOL, флаг обмена объектом с соседними шлюзами
  -- false = обмен выключен
  -- true = обмен включен. В таблице объектов (WebUI/Objects) отображается символом N (Net Notify)

obj.set()

Запись данных в объект, управление флагом обратной связи. Если объекта не существует, он будет создан.

lua

result = obj.set(name, value[, flagACK])
-- name - STR, имя объекта
-- value - записываемые данные, любого типа
-- flagACK - BOOL, флаг обратной связи
  -- true = включен. В таблице объектов отображается символом A (ACK)
  -- false = выключен. В таблице объектов не отображается
-- result - BOOL, true - значение изменено и успешно записано, false - значение не изменилось, поэтому не записано

result = obj.set(name, value[, flagACK])
-- name - STR, имя объекта
-- value - записываемые данные, любого типа
-- flagACK - BOOL, флаг обратной связи
  -- true = включен. В таблице объектов отображается символом A (ACK)
  -- false = выключен. В таблице объектов не отображается
-- result - BOOL, true - значение изменено и успешно записано, false - значение не изменилось, поэтому не записано

obj.get()

Получение данных, хранящихся в объекте. Данные будут получены того же типа, какой задан объектом (проверяется функцией LUA type()).

lua

result = obj.get(name)
-- name - STR, имя объекта
-- result - текущее значение или NIL если объект не найден

result = obj.get(name)
-- name - STR, имя объекта
-- result - текущее значение или NIL если объект не найден

В объекте хранится текущее значение, предыдущее и состояние флага ACK.

Пример получения всех значений:

lua

local current_value, previos_value, flag_ack = obj.get("object_name")
-- переменные будут содержать:
-- current_value = текущее значение
-- previos_value = предыдущее значение
-- flag_ack = статус флага ACK: true|false

local current_value, previos_value, flag_ack = obj.get("object_name")
-- переменные будут содержать:
-- current_value = текущее значение
-- previos_value = предыдущее значение
-- flag_ack = статус флага ACK: true|false

obj.getTime()

Получение тайм-штампов изменения текущего и предыдущего значений. Оба значения можно получить так-же как в obj.get()

lua

obj.getTime(name)
-- name - STR, имя объекта

obj.getTime(name)
-- name - STR, имя объекта

obj.setScript()

Привязка к объекту скрипта, который будет выполняться при каждом изменении значения объекта или при каждой его записи. Если объекта не существует, он будет создан.

lua

obj.setScript(name, script.lua[, run_on_write])
-- name - STR, имя объекта
-- script.lua - STR, имя файла скрипта с расширением
-- run_on_write - BOOL, false (default) = запуск при обновлении значения; true = запуск каждый раз при записи значения в объект + поднимается флаг W

obj.setScript(name, script.lua[, run_on_write])
-- name - STR, имя объекта
-- script.lua - STR, имя файла скрипта с расширением
-- run_on_write - BOOL, false (default) = запуск при обновлении значения; true = запуск каждый раз при записи значения в объект + поднимается флаг W

obj.remove()

Удаление объекта

lua

result = obj.remove(name)
-- name - имя объекта
-- result - BOOL, true - успех, false - объект не найден

result = obj.remove(name)
-- name - имя объекта
-- result - BOOL, true - успех, false - объект не найден

HTTP API

Получить список объектов

http

GET /api/obj

GET /api/obj

Установить значение объекта

http

POST /api/obj?name=XXX&value=YYY
<!--
name - имя объекта
value - значение -->

POST /api/obj?name=XXX&value=YYY
<!--
name - имя объекта
value - значение -->

Удалить объект с устройства

http

DELETE /api/obj?name=obj_name

DELETE /api/obj?name=obj_name

Получить значение объекта

http

GET /api/obj?name=XXX

GET /api/obj?name=XXX

Флаги возвращаются в поле flags: flag_value:

flag_value = 0: ACK=0; MQTT=0; Net=0
flag_value = 1: ACK=0; MQTT=1; Net=0
flag_value = 2: ACK=1; MQTT=0; Net=0
flag_value = 3: ACK=1; MQTT=1; Net=0
flag_value = 4: ACK=0; MQTT=0; Net=1
flag_value = 5: ACK=0; MQTT=1; Net=1
flag_value = 6: ACK=1; MQTT=0; Net=1
flag_value = 7: ACK=1; MQTT=1; Net=1

Примеры

Создание и настройка объекта

lua

obj.setType("test", "JSON") -- создает объект test с типом данных JSON
obj.setType("test", "STR") -- изменяет тип данных объекта на STR

obj.setType("test", "JSON") -- создает объект test с типом данных JSON
obj.setType("test", "STR") -- изменяет тип данных объекта на STR

Управление флагом MQTT объекта

lua

obj.setShare("test", true) -- включить передачу уведомлений в MQTT

obj.setShare("test", true) -- включить передачу уведомлений в MQTT

Управление флагом N объекта

lua

obj.setShare("test", false, true) -- отключить передачу уведомлений в MQTT и включить обмен объектом с соседними шлюзами

obj.setShare("test", false, true) -- отключить передачу уведомлений в MQTT и включить обмен объектом с соседними шлюзами

Установка значения объекта

lua

obj.set("security.status", true)

obj.set("security.status", true)

Установка значения с передачей ACK

lua

obj.set("security.status", true, true)

obj.set("security.status", true, true)

Пример скрипта-обработчика событий обращения к объекту

Скрипт привязывается к объекту командой obj.setScript() в init.lua

lua

local status = ""
local current_status, previous_status, ack = obj.get("security.status")
-- добавим обработчик булевых значений для склейки со строками
if current_status == true then
  status = "true"
else
  status = "false"
end
-- отправляем уведомление только  в случае изменения значений с признаком ack
if ack == true then
  telegram.send("wsecurity status is " .. status)
end

local status = ""
local current_status, previous_status, ack = obj.get("security.status")
-- добавим обработчик булевых значений для склейки со строками
if current_status == true then
  status = "true"
else
  status = "false"
end
-- отправляем уведомление только  в случае изменения значений с признаком ack
if ack == true then
  telegram.send("wsecurity status is " .. status)
end

Удаление объекта

lua

obj.remove("security.status")

obj.remove("security.status")

Изменение типа переменной

lua

obj.setType("security.status", "INT")

obj.setType("security.status", "INT")

Получение времени изменения объекта

lua

local curr, prev = obj.getTime("security.status")
print("Время предыдущего изменения:" .. prev .. ", И последнего: " .. curr .. " длительность события: " .. curr-prev)

local curr, prev = obj.getTime("security.status")
print("Время предыдущего изменения:" .. prev .. ", И последнего: " .. curr .. " длительность события: " .. curr-prev)

Инкрементирование значения объекта каждую секунду

lua

obj.set('reg1', 0)
scripts.setTimer("#obj.set('reg1', obj.get('reg1')+1)", 1)

obj.set('reg1', 0)
scripts.setTimer("#obj.set('reg1', obj.get('reg1')+1)", 1)

Объекты ​

Веб интерфейс ​

Управление объектами через веб-интерфейс ​

Инициализация объектов ​

Флаги ​

Обратная связь при изменении значения объектов ​

MQTT Notify ​

Network ​

Изменение значения при каждом обращении на запись объекта и вызов скрипта ​

APIs для работы с объектами ​

LUA ​

События ​

obj.setType() ​

obj.setShare() ​

obj.set() ​

obj.get() ​

obj.getTime() ​

obj.setScript() ​

obj.remove() ​

HTTP API ​

Получить список объектов ​

Установить значение объекта ​

Удалить объект с устройства ​

Получить значение объекта ​

Примеры ​

Создание и настройка объекта ​

Управление флагом MQTT объекта ​

Управление флагом N объекта ​

Установка значения объекта ​

Установка значения с передачей ACK ​

Пример скрипта-обработчика событий обращения к объекту ​

Удаление объекта ​

Изменение типа переменной ​

Получение времени изменения объекта ​

Инкрементирование значения объекта каждую секунду ​

Объекты

Веб интерфейс

Управление объектами через веб-интерфейс

Инициализация объектов

Флаги

Обратная связь при изменении значения объектов

MQTT Notify

Network

Изменение значения при каждом обращении на запись объекта и вызов скрипта

APIs для работы с объектами

LUA

События

obj.setType()

obj.setShare()

obj.set()

obj.get()

obj.getTime()

obj.setScript()

obj.remove()

HTTP API

Получить список объектов

Установить значение объекта

Удалить объект с устройства

Получить значение объекта

Примеры

Создание и настройка объекта

Управление флагом MQTT объекта

Управление флагом N объекта

Установка значения объекта

Установка значения с передачей ACK

Пример скрипта-обработчика событий обращения к объекту

Удаление объекта

Изменение типа переменной

Получение времени изменения объекта

Инкрементирование значения объекта каждую секунду