Поддержка lua скриптов

Web site

Поддержка lua скриптов

Введение

Шлюз SLS самодостаточен и может обходиться без внешних систем управления Умным домом. Для реализации автоматизаций, он поддерживает скриптовый язык программирования LUA. При разработке скриптов можно использовать функции как встроенные в прошивку шлюза, так и функции поддерживаемых шлюзом библиотек LUA. Текущая, поддерживаемая, версия LUA 5.4.4 (с версии прошивки 2022.01.30d1).

Соглашения

Немного о форматировании и названиях различных объектов шлюза.

Для работы с различными объектами используется формат кода типа zigbee.getStatus(). В терминологии LUA это выглядит как библиотека.функция(). Поэтому постараемся придерживаться подобного именования объектов SLS.

Форматирование текста:

  • пункты меню: File -> Save
  • небольшие куски кода: print(a)
  • многострочный код:
local var = 0
print(var)

Описание синтаксиса:

result = function(var1, var2[, var3])
-- Описание переменных, передаваемых в функцию и их тип
-- var1 - STR, переменная 1
-- var2 - INT, переменная 2
-- var3 - BOOL, переменная 3 (если в [квадратных] скобках, то передавать не обязательно)
-- описание результата
-- result - type, если функция что-то возвращает, описывается здесь

Примечания:

  • draft - черновик или будет добавлено в будущем
  • deprecated - будет удалено в будущем

Асинхронное программирование

Немного о модели программирования для нашего шлюза. При проектировании алгоритмов лучше не использовать функции а-ля os.delay() и самописные аналоги, выполняющие паузы в работе сценария более 1 секунды. Вместо этого лучше проектировать вызовы кусков кода из разных скриптов.

Например, часто при включении света в техническом или проходном помещении, необходимо сделать паузу и свет выключить. Первое, что приходит в голову - это сделать паузу в теле текущего сценария. Но, правильнее передать управление другому скрипту или вызвать основной рекурсивно.
Об асинхронности в программировании можно почитать, например здесь.

Примеры кода

Все примеры скриптов собраны здесь

Редактор скриптов и отладка

Редактор скриптов, по совместительству с файловым менеджером предназначен для создания, удаления и редактирования файлов, в том числе и скриптов. Найти его можно в меню Actions -> Files (в старых версиях прошивки Actions -> Scripts). lua Script Editor Редактор разделен на несколько областей:

  • Меню, с кнопками:
    • Toggle files - скрыть / отобразить панель файлов
    • Save - сохранить
    • Run - запустить скрипт на исполнение
    • Clear output - очистить панель вывода
  • Панель Files. Позволяет управлять файлами:
    • Создать - New file
    • Удалить - значок корзины напротив имени каждого файла
    • Открыть на редактирование - каждый файл представляет собой ссылку, по которой файл открывается в панели редактора
  • Панель редактора
  • Панель вывода - консоль для вывода результатов работы редактируемого скрипта

Скриптовый stdout функции LUA print() выводит информацию на Панель вывода, а также в системный лог (меню Log) шлюза. Данную функцию удобно использовать для отладки.

Для разработки или отладки скрипта, необходимо создать новый файл или открыть существующий. Например, с именем test.lua и в него ввести код на языке LUA.

Отладка скриптов выполняется преимущественно в Редакторе скриптов SLS. Однако, некоторые пользовательские функции может быть удобнее разрабатывать во “взрослых” IDE. Например, нативный ZeroBrain Studio, VS Code, Atom и других.

Запуск скриптов

В зависимости от задач, выполняемых той или иной автоматизацией, доступны несколько вариантов запуска скриптов:

  1. из скрипта инициализации
  2. при изменении состояния устройства
  3. по событию изменения объекта
  4. запуск из другого скрипта
  5. с помощью HTTP API
  6. периодический запуск (Таймеры)
  7. по подписке mqtt (в разработке).

Также, в любом месте, где прописывается имя файла скрипта, возможно писать сразу код в таком формате:

'#code', где code - тело скрипта
--Например:
scripts.setTimer('#zigbee.set("0x0123456789012345", "state", "ON")', 10, "ку")

Скрипт инициализации

При запуске системы выполняется скрипт инициализации init.lua, если он есть. Перед началом работы со скриптами, рекомендуется проверить его наличие рядом со всеми остальными скриптами *.lua. Если файла нет, то его нужно в редакторе скриптов. В init.lua полезно инициализировать переменные для работы с устройством, а также выполнить какие либо действия. Например:

-- init.lua --
-- Уведомление в Telegram о старте шлюза --
telegram.settoken("51778***5:AAG0bvK***")
telegram.setchat("-3348***")
telegram.send("SLS загружен!!!")

Запуск скрипта при изменении состояния устройства

Скрипт можно запускать как одно из правил SimpleBind.

Синтаксис: scriptname.lua[,Param]

Например, так может выглядеть запись SB Rule для датчика открытия SB Rule

  • mainDoorOnLight.lua - имя запускаемого скрипта
  • Param - необязательный параметр, через который в скрипт можно передать необходимые аргументы. Принимается он в скрипте через Событие Event.Param Аргументов может быть несколько. В данном примере передается 3 аргумента, разделенные символом :: целевое устройство, которым должен управлять датчик по сработке; контролируемый статус; задержка управляющего действия. Если аргументы не прописывать, то при изменении условий, придется менять эти значения в теле скрипта. Пример похожего скрипта здесь

Также, в Simple Bind можно запускать текст скрипта: SB Rule Run Lua Code

Запуск скрипта по событию изменения объекта

Привязка к объекту скрипта: obj.setScript()

Запуск LUA скрипта из другого скрипта

dofile()

Выполняет текст скрипта в контексте текущего.

dofile(scriptPath)
-- scriptPath - STR, путь к запускаемому скрипту вида "/int/script.lua"

scripts.run()

scripts.run(script[, Param])
-- script - STR, имя файла скрипта, без расширения `lua`
-- Param - STR, аргументы, передаваемые в скрипт

Библиотеки SLS

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

  • obj. - работа с объектами
  • Event. - работа с событиями
  • zigbee. - управление zigbee устройствами
  • mqtt. - работа с MQTT брокером
  • http. - взаимодействие с внешними системами по HTTP
  • telegram. - отправка уведомлений и управление шлюзом. Подробнее здесь
  • os. - взаимодействие с операционной системой шлюза. Работа с хранилищем
  • gpio. - управление GPIO
  • audio. - управление встроенным в шлюза звуком
  • net. - получение IP адресов шлюза
  • yeelight. - управление устройствами Yeelight
  • cloud. - работа с облаком SLS cloud.slsys.io

Примеры использования.

Библиотека EVENT

Библиотека Event служит для передачи данных в скрипт, в зависимости от того, из какой подсистемы он вызван.

Типы событий

События различаются типом Event.Type. В скрипт передается числовое значение типа события, позволяющее определить источник вызова и получить различные параметры:

  1. Вызов по изменению состояния привязанного сенсора. Правило Simple Bind. SCRIPT_EVENT_TYPE_STATE_UPDATE
  2. Вызов по изменению объекта. SCRIPT_EVENT_TYPE_OBJ_CHANGE
  3. Вызов по входящему сообщению Telegram SCRIPT_EVENT_TYPE_TLG_MESSAGE
  4. Таймер однократный. SCRIPT_EVENT_TYPE_TIMEOUT
  5. Таймер периодический. SCRIPT_EVENT_TYPE_INTERVAL
  6. Таймер Cron. SCRIPT_EVENT_TYPE_CRON
  7. Вызов из LUA командой scripts.run() SCRIPT_EVENT_TYPE_RUN

Свойства событий

Для всех типов событий передаются следующие свойства:

  • Event.Type - тип события INT
  • Event.Name - имя файла вызванного скрипта с расширением
  • Event.Time - время вызова скрипта table(sec, min, hour, day, wday, month, year).

Вызов из SB Rule

  • Event.Param - аргументы
  • Event.nwkAddr - nwkAddr вызывающего устройства
  • Event.ieeeAddr - ieeeAddr вызывающего устройства
  • Event.ModelId - ModelId вызывающего устройства
  • Event.FriendlyName - FriendlyName вызывающего устройства
  • Event.State.Name - имя вызывающего “состояния”
  • Event.State.Value - текущее значение “состояния”
  • Event.State.OldValue - предыдущее значение “состояния”

Вызов по однократному таймеру

  • Event.Param - аргументы

Вызов по периодическому таймеру

  • Event.Param - аргументы

Вызов по таймеру Cron

  • Event.Param - аргументы

Библиотека ZIGBEE

Служит для управления zigbee устройствами, зарегистрированными на шлюзе. Подробные примеры здесь

zigbee.getStatus()

Возвращает статус координатора. Если запущен, вернёт 9. Начиная с версии 2022.07.24d1.

coord_status = zigbee.getStatus()
-- coord_status - INT, статус zigbee координатора. 9 - OK

zigbee.join()

Включает режим сопряжения для подключения новых устройств

zigbee.join(duration = 255[, router])
-- duration - INT, время в секундах, на которое включить Join
-- router - STR, FriendlyName, ieeeAddr или nwkAddr устройства - роутера. Если опустить этот параметр, сопряжение будет открыто для всей сети

zigbee.value()

Возвращает значения состояния устройства из кэша

result = zigbee.value(device, state)
-- device - STR, FriendlyName, ieeeAddr или nwkAddr устройства
-- state - STR, состояние, значение которого необходимо получить
-- result - значение состояния

zigbee.get()

Вызывает функцию GET в конвертере. Возвращает true в случае успеха.

result = zigbee.get(device, state)
-- device - STR, FriendlyName, ieeeAddr или nwkAddr устройства
-- state - STR, состояние, значение которого необходимо получить
-- result - BOOL, true - успех, false - вероятно в конвертере нет команды GET

zigbee.set()

Устанавливает значение состояния устройства

result = zigbee.set(device, stateName, stateValue)
-- device - STR, FriendlyName, ieeeAddr или nwkAddr устройства
-- stateName - STR, имя состояния, значение которого необходимо изменить
-- stateValue - значение состояние. Тип - свой для каждого значения. Например, для кнопки State:Action тип будет STR, а для яркости State:brightness тип будет INT 
-- result - NIL - устройство не найдено, BOOL, true - успех, false - ошибка в имени состояния и/или его значении

zigbee.setState()

Устанавливает значение состояния устройства. Можно указать тип значения (по умолчанию STR) и необходимо ли выполнять события (с версии 2022.07.24d1, по умолчанию true) . В отличие от zigbee.set() позволяет создавать свои состояния, виртуальные. Например, для хранения данных какого-либо состояния, в альтернативных единицах измерения.

result = zigbee.setState(device, stateName, stateValue[[, type], events])
-- device - STR, FriendlyName, ieeeAddr или nwkAddr устройства
-- stateName - STR, имя состояния, значение которого необходимо изменить
-- stateValue - значение состояние
-- type - STR, тип значений состояния
-- events - BOOL, выполнять события (по умолчанию true)
-- result - BOOL,  true - успех, false - устройство не найдено

zigbee.setModel()

Программное переназначение типа устройства.

zigbee.setModel(device, ModelId)
-- device - STR, FriendlyName, ieeeAddr или nwkAddr устройства
-- ModelId - STR, ModelId устройства, которое поддерживается шлюзом.

В некоторых случаях протокол взаимодействия новых устройств совпадает с теми, что уже поддерживаются шлюзом SLS. В таком случае можно при загрузке шлюза подменять идентификаторы, добавив в init.lua код:

zigbee.setModel("xBox", "ptvo.switch")

Данный функционал будет полезен пользователям генератора прошивок ptvo, кто самостоятельно изменит имя устройства на кастомное.

zigbee.readAttr() - draft

Отправляет запрос на чтение атрибута в кластере.

zigbee.readAttr(device, epId, clusterId, AttrId[, manufId])
-- device - STR, FriendlyName, ieeeAddr или nwkAddr устройства
-- epID - INT, номер эндпоинта
-- clusterID - INT, номер кластера
-- AttrId - INT, номер атрибута
-- Например, вернуть атрибут swBuild в кластере genBasic в 1 эндпоинте:
zigbee.readAttr("0x90FD9FFFFEF7E26D", 1, 0x4000, 0x0000)

zigbee.writeAttr() - draft

Записывает значение атрибута в кластере.

zigbee.writeAttr(device, epId, clusterId, AttrId, dataType, value[, manufId])
-- device - STR, FriendlyName, ieeeAddr или nwkAddr устройства
-- epID - INT, номер эндпоинта
-- clusterID - INT, номер кластера
-- AttrId - INT, номер атрибута
-- dataType - INT, тип данных. Например UINT8 - это 0x20
-- value - значение атрибута

zigbee.configReport() - draft

Конфигурирует репортинг атрибута в кластере.

zigbee.configReport(device, epId, clusterId, AttrId, dataType, minRepInt, maxRepInt, repChange)
-- device - STR, FriendlyName, ieeeAddr или nwkAddr устройства
-- epID - INT, номер эндпоинта
-- clusterID - INT, номер кластера. Например GEN_POWER_CFG - это 0x0001
-- AttrId - INT, номер атрибута. Например BatteryVoltage - это 0x0020
-- dataType - INT, тип данных. Например UINT8 - это 0x20
-- minRepInt - INT, минимальный интервал отправки в сек
-- maxRepInt - INT, максимальный интервал отправки в сек
-- repChange - INT, минимальное значение, на которое должен измениться атрибут, для репортинга

Например:

zigbee.configReport("0x90FD9FFFFEF7E26D", 1, 0x0001, 0x0021, 0x20, 1800, 3600, 1)
-- 0x90FD9FFFFEF7E26D - ieeeAddr устройства 
-- 1 - первый эндпоинт
-- 0x0001 - кластер GEN_POWER_CFG
-- 0x0021 - атрибут BatteryPercentageRemaining
-- 0x20 - тип данных UINT8
-- 1800, 3600, 1 - репортить от 30 мин до 1 часа при изменении атрибута на 1

Библиотека MQTT

mqtt.pub()

Публикует на MQTT сервер в топик topic значение payload.

mqtt.pub(topic, payload)

Пример управления реле на прошивке Tasmota - cmnd/имя устройства/имя реле

mqtt.pub('cmnd/sonoff5/power', 'toggle')

mqtt.connected()

Возвращает статус подключение к брокеру MQTT. Выполняется без параметров.

mqtt.sub()

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

mqtt.sub(topic, objName)
-- topic - STR, топик MQTT
-- objName - STR, объект, в который записываются данные

Пример подписки на топик с температурой, которую шлюз помещает в объект:

mqtt.sub('dev/sensor/temp', 'room_temp')

mqtt.unSub()

Отписывается от топика.

mqtt.unSub(topic)

Пример отписки от топика с температурой

mqtt.unSub('dev/sensor/temp')

Библиотека HTTP

http.request2()

Служит для отправки HTTP (HTTPS в разработке) запросов во внешние системы. Поддерживает методы GET и POST.

http.request2 (url[:port], [method, headers, body])
-- url:port - STR, URL адрес и порт целевого ресурса
-- method - STR, метод POST или GET
-- headers - STR, заголовки запроса
-- body - STR, тело запроса

Примеры

http.request() - deprecated

Библиотека TELEGRAM

Подробное описание здесь

telegram.settoken()

Инициализирует токен

telegram.settoken(token)
-- token - STR, API-токен вашего бота

telegram.setchat()

Инициализирует чат, в который бот будет отправлять уведомления

telegram.setchat(chatid)
-- chatid - STR, ID чата, куда бот будет писать сообщения

telegram.secure()

Инициализирует протокол HTTPS. Внимание! Включение этой опции отнимает большое количество свободной памяти! Возможны частые перезагрузки шлюза!

telegram.secure(enable)
-- enable - BOOL, включить: true, выключить (по-умолчанию): false

telegram.receive()

Инициализирует обработку входящих сообщений

telegram.receive(enable)
-- enable - BOOL, включить: true, выключить (по-умолчанию): false

telegram.send()

Отправляет сообщение.

telegram.send(msg[, chatid, parse_mode])
-- msg - STR, сообщение 
-- chatid - STR, ID чата, куда бот будет писать сообщения
-- parse_mode - STR, можно использовать для отправки ReplyKeyboard

Библиотека OS

Примеры

os.time()

Возвращает Unix время. Вызывается без параметров.

os.sunrise([offset])

Возвращает время восхода солнца (часы, минуты). Для правильной работы требуется выполнить настройки Settings -> Time & Location

os.sunrise([offset])
-- offset - INT, позволяет добавить смещение в минутах к результату вывода
-- Пример:
sunriseH, sunriseM = os.sunrise()
print("Восход солнца в " .. sunriseH .. ":" .. sunriseM )
-->  Восход солнца в 10:55

os.sunset([offset])

Возвращает время заката солнца (часы, минуты). Для правильной работы требуется выполнить настройки Settings -> Time & Location

os.sunset([offset])
-- offset - INT, позволяет добавить смещение в минутах к результату вывода

os.setSleep()

Включает и выключает режим сна для модема WiFi. По-умолчанию выключено. Также можно заставить систему заснуть глубоким сном на time секунд, тем самым снизив энергопотребление практически до нуля. В этом режиме не работает ничего, кроме таймера отсчета до окончания сна, по прошествии которого система перезагрузится. Это может использоваться при питании от аккумулятора.

os.setSleep(enable[,time])
-- enable - BOOL, включить = true, выключить = false спящий режим
-- time - INT, время сна в сек.

os.delay()

Выполняет паузу выполнения скрипта на указанное время. Не рекомендуется делать паузу более чем на 1 секунду.

os.delay(time)
-- time - INT, время паузы в милисекундах (1 сек = 1000 мс)

os.millis()

Возвращает количество миллисекунд с момента загрузки системы. Вызывается без параметров.

os.getUptime()

Возвращает время с момента загрузки системы. Вызывается без параметров.

Пример:

print('Uptime: ' .. os.getUptime())
--> Uptime: 11 days 17:43:03

os.ntp()

Возвращает статус подключение к серверу времени (NTP): true - синхронизация с сервером NTP выполнена успешно. Вызывается без параметров.

os.freeMem()

Возвращает количество свободной памяти в байтах.

os.freeMem([type])
-- type - STR, heap, psram
-- без параметров возвращает объем FreeHeap

os.save()

Сохраняет данные. Тоже, что и меню Actions -> Save. Вызывается без параметров.

os.restart()

Перезагружает ОС. Вызывается без параметров.

os.ping()

Отправляет запросы ICMP PING на тестируемый хост. Возвращает среднее время ответа или -1 при недоступности.

os.ping(host[, count])
-- host - STR, IP или DNS адрес хоста
-- count - INT, количество запрсов (по-умолчанию 1)

os.wdt()

Включается и выключает WDT (Сторожевой таймер), может использоваться для отладки незапланированных перезагрузок.

os.wdt(enable)
-- enable - BOOL, включить (true), выключить (false)

os.udplogenable()

Включает логирование через UDP. Примеры получения лога

os.udplogenable(enable)
-- enable - BOOL, включить UDP лог (true); выключить (false)

os.setAssets()

Задает место хранения ресурсов web-интерфейса, для размещения на альтернативном web-сервере, например локальном. В разработке хранение web-ресурсов в хранилище SLS, для систем без выхода в интернет.

os.setAssets(url)
-- url - STR, источник ресурсов

os.led()

os.led(mode, brightness, r, g, b[, effect])
-- mode - STR, режим. OFF - выключено, ON - включено, AUTO - индикация режимов/состояний шлюза (см. описаниее далее) 
-- brightness - INT, яркость (целое, от 0 до 255)
-- r, g, b - INT, цвет (целое, от 0 до 255 или -1, если цвет менять не требуется)
-- effect - INT, включает эффекты в соответствии с таблицей

Подробнее о работе с LED здесь

os. функции для работы с хранилищем

Описание функций для работы с хранилищем здесь

Библиотека GPIO

Управление контактами ввода/вывода (GPIO) чипа ESP32.

gpio.mode()

Управление режимом контакта:

  • gpio.INPUT: ввод
  • gpio.OUTPUT: вывод
  • gpio.INPUT_PULLUP: подтянуть к VCC
  • gpio.INPUT_PULLDOWN: подтянуть к GND
gpio.mode(pin, mode)
-- pin: номер контакта
-- mode: режим контакта - gpio.INPUT, gpio.INPUT_PULLUP, gpio.INPUT_PULLDOWN, gpio.OUTPUT

gpio.read()

Чтение сигнала с GPIO

gpio.read(pin[, ADC)
-- pin: номер контакта
-- ADC: true - чтение ADC; false - чтение цифрового сигнала

Задать каналу 2 режим входа, получить его значение:

gpio.mode(25, gpio.INPUT)
local value = gpio.read(25)
print(value)

gpio.write()

Запись уровня в GPIO

gpio.write(pin, level)
-- pin: номер контакта
-- level: уровень - gpio.HIGH - высокий, gpio.LOW - низкий

Например, задать каналу 4 режим выхода и включить его на 100мс:

gpio.mode(27, gpio.OUTPUT)
gpio.write(27, 1)
os.delay(100)
gpio.write(27, 0)

PWM (ШИМ)

ШИМ-контроллер ESP32 имеет 16 независимых каналов, которые можно настроить для генерации ШИМ-сигналов с различными свойствами. Все выводы, которые могут выступать в качестве выходов, могут использоваться в качестве выводов ШИМ (GPIO с 34 по 39 не могут генерировать ШИМ).

gpio.pwmSetup()

Настройка ШИМ

gpio.pwmSetup(channel, pin[, freq = 5000[, resolution = 8]])
-- chanel: канал ШИМ - 0-15
-- pin: номер контакта
-- resolution: разрешение 1-16 bits
-- freq: частота

gpio.pwm()

Управление ШИМ

gpio.pwm(channel, value)
-- channel: канал 0-15
-- value: значение ШИМ

Например, задать каналу 1 режим выхода и включить ШИМ со скважностью 50%

gpio.pwmSetup(3, 32)
gpio.pwm(3, 255/100*50)

Библиотека AUDIO

Управление звуком

audio.playurl(url) -- проигрывание звука из URL
audio.geturl() -- возвращает текущий URL
audio.stop() -- остановить проигрывание
audio.setvolume(volume_percent) -- установить уровень громкости
audio.getvolume() -- возвращает текущий уровень громкости
audio.getstatus() -- возвращает текущий статус

Библиотека NET

net.localIP()

Возвращает адрес устройства SLS в локальной сети. Выполняется без параметров.

net.remoteIP()

Возвращает внешний адрес SLS в сети интернет (если доступен). Выполняется без параметров.

Библиотека Yeelight

Примеры

yeelight.send()

Управляет устройством Yeelight. Описание протокола.

result = yeelight.send(id, method, param)
-- id - STR, IP адрес устройства
-- method - STR, команда
-- param - STR, параметры команды
-- result - JSON строка, согласно описания протокола

Библиотека Cloud

cloud.isConnected()

Возвращает статус подключения к облаку SLS cloud.slsys.io

result = cloud.isConnected()
-- result - BOOL, true шлюз подключен к облаку SLS

Функции LUA SLS

Функции LUA, встроенные в прошивку SLS, которые не объединены той или иной библиотекой.

explode()

Разбивает строку с помощью разделителя. Результат помещает в таблицу.

explode(separator, string)
-- string - STR, строка, которую необходимо разбить
-- separator - STR, символ разделителя
-- пример:
local string = "param1|param2|param3"
local t = explode("|", string)
local param1 = t[1]
local param2 = t[2]
local param3 = t[3]

Обработка нажатий аппаратной кнопки шлюза

Многие ревизии шлюзов имеют кнопку, нажатия которой можно обрабатывать скриптами. Например, для включения “режима сопряжения” при нажатии на боковую кнопку шлюза Необходимо привязать скрипт btn_sw1.lua

zigbee.join(255, "0x0000")

и привязать его выполнение в init.lua

obj.setScript("io.input0.value", "btn_sw1.lua")
  • где io.input0.value - номер обрататываемого порта (в примере указана кнопка для круглого шлюза)

Более подробно вопрос с обрабокой событий gpio разобран в разделе Модуля ввода-вывода

Полезные ссылки

1) Примеры типовых сценариев 2) On-line учебник по lua 3) Генератор lua скриптов на основе Blockly