Инструкция по работе со сценарием 2

1. Что такое сценарии

Сценарии — это пользовательская логика работы контроллера: набор правил «при каком событии и при каких условиях что сделать». Они позволяют реализовать индивидуальный алгоритм, не меняя прошивку. В основе языка лежит выражение вида: «Если условие истинно — выполнить одно действие, иначе — другое».

Сценарий пишется в текстовом редакторе прямо в веб-интерфейсе устройства (вкладка «Сценарий») и сохраняется в файл /scenario.txt. При сохранении ядро заново загружает и разбирает его.

2. Главный принцип: событийность

Это самое важное для понимания. Сценарий не выполняется постоянно в цикле. Отдельное выражение проверяется только тогда, когда произошло событие с элементом, который в этом выражении упомянут.

Событие возникает каждый раз, когда какой-либо элемент регистрирует новое значение: датчик считал температуру, пользователь нажал кнопку в приложении, сработал таймер. Ядро берёт имя этого элемента и прогоняет через сценарий только те выражения, где оно встречается.

# это выражение проверится ТОЛЬКО когда обновится temp1
if (temp1 > 25) then relay1 = 0 else relay1 = 1

3. Основы синтаксиса

Выражение может состоять из перечисленных ниже элементов. Любое выражение при вычислении возвращает значение (число или строку).

Строки, кавычки и переносы

Строки заключаются в двойные кавычки. Если внутри строки нужна кавычка или перенос строки — их экранируют. В параметрах функций можно передавать любые допустимые выражения, включая другие функции и идентификаторы элементов.

4. Операторы и приоритеты

Ниже — полный список операторов, поддерживаемых движком, в порядке возрастания приоритета (чем выше приоритет, тем раньше выполняется). Значения приоритетов взяты напрямую из кода интерпретатора.

5. Ветвление if / then / else

Конструкция ветвления — основа сценариев. Формат:

if (условие) then действие_если_истина else действие_если_ложь

Ветка else необязательна. Действием может быть как одно выражение, так и блок в фигурных скобках:

if (temperature > 25) then {
    relay = 0                    # выключить нагрев
    telegram.sendMsg("Жарко")    # уведомить
} else {
    relay = 1                    # включить нагрев
}

Условие — это любое выражение. Ноль считается ложью, ненулевое значение — истиной. Логические условия можно комбинировать через & and |:

if (temp > 30 & humidity < 40) then fan = 1

Ветвления можно вкладывать друг в друга внутри блоков для более сложной логики.

6. Обращение к элементам и вызов функций

Значение элемента

Просто напишите ID элемента — подставится его текущее значение. Присваивание ID = значение отправляет элементу команду изменить значение (например, включить реле).

Два вида функций

В языке есть функции двух типов, и они вызываются по-разному:

Аргументы

В качестве аргументов можно передавать числа, строки, идентификаторы других элементов и даже вложенные функции. Многие функции, принимающие «сообщение» (например, Telegram), понимают как строку, так и ID элемента — тогда подставится его значение.

7. Рецепты: типовые примеры

Термостат с гистерезисом

# реле включается ниже 22, выключается выше 24
if (temp < 22) then heater = 1
if (temp > 24) then heater = 0

Уведомление в Telegram по событию

if (door == 1) then tlg.sendMsg("Открыта дверь!")

Работа по расписанию (привязка к таймеру)

# timer1 — элемент-таймер, генерирует событие ежеминутно и запускает проверку
if (timer1) then {
    if (getHours() == 22) then light = 0    # выключить свет в 22:00
    if (getHours() == 7)  then light = 1    # включить в 7:00
}

Вывод значения на дисплей

if (temp) then {
    lcd.prefix("T=")
    lcd.postfix(" C")
    lcd.id2show("temp")
    lcd.display()
}

Тихое обновление служебной переменной

# обновляем счётчик, но НЕ запускаем правила, где он используется
if (motion == 1) then counter := counter + 1

Реакция на диапазон времени

if (motion == 1) then {
    if (nowInTimePeriod("23:00", "06:00")) then light = 1
}

8. Справочник: системные функции

Системные функции вызываются глобально: функция(...). Функции даты/времени работают, только если время получено из интернета (NTP) или внешних часов RTC; иначе условие с ними пропускается.

Управление элементами и устройством

Работа с пинами (GPIO)

Сеть и MQTT

Дата и время

9. Справочник: функции модулей

Эти функции доступны, только если в конфигурации есть соответствующий элемент. Вызываются от его имени через точку: ID_элемента.функция(...). Разделы соответствуют категориям модулей. Нажмите на название модуля, чтобы раскрыть список его функций.

Исполнительные устройства

Экраны и индикация

Сенсоры

Виртуальные элементы

10. Частые ошибки