Skip to content

Latest commit

 

History

History
302 lines (207 loc) · 12.6 KB

objects.md

File metadata and controls

302 lines (207 loc) · 12.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 при изменении объекта.

При поднятом флаге, шлюз будет публиковать в топик вида: 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.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()

Получение данных, хранящихся в объекте

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
-- отправляем уведомление только  в случае изменения значений с признаком ackw
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)

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

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

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