Skip to content

Latest commit

 

History

History
331 lines (224 loc) · 15.6 KB

objects.md

File metadata and controls

331 lines (224 loc) · 15.6 KB
Raw

Объекты

Объекты - это универсальная сущность для хранения и обмена данными между подсистемами шлюза, например между скриптами 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
    • 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 при изменении объекта. Установка флага доступна как в веб-интерфейсе, так из LUA

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

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

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

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

Флаг 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()

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

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

obj.setShare()

Управление сетевыми флагами объекта. На 25.10.2023 доступен флаг MQTT.

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

obj.setOpt() - deprecated

Изменение типа данных, записываемых в объект, управление флагом передачи уведомлений в MQTT. Если объекта не существует, он будет создан. Внимание функция может быть удалена в прошивках после 2023.10.25. Её заменят функции obj.setType() для настройки типов и obj.setShare() для настройки флагов.

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()

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

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

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

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

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

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
-- отправляем уведомление только  в случае изменения значений с признаком ack
if ack == true then
  telegram.send("wsecurity status is " .. status)
end

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

obj.remove("security.status")

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

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

Включение уведомления об изменении в MQTT

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

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

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

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

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

Сетевые объекты

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

Данный функционал в разработке.