Логические сценарии в Sprut.Hub

Введение простыми словами

Логические сценарии — это скрипты на JavaScript (движок Nashorn) и поддерживает только стандарт ES6 (ECMAScript 6), которые добавляют настраиваемую «логику» для выбранных типов устройств. Вы подключаете сценарий к устройству, выбираете триггер (событие), а код сценария реагирует и выполняет действия.

Сценарий появляется у подходящих устройств после сохранения и проверки его корректности.
Название пользовательского сценария должно отличаться от встроенных/существующих.
Срабатывает только от указанного триггера и только для поддерживаемых типов устройств.
Кнопка теста редактора не запускает логический сценарий (он зависит от события).

Быстрый старт

Откройте примерную структуру в ScenarioTemplate.
Создайте новый сценарий на его основе: задайте уникальное имя и целевые типы устройств/сервисов.
Определите триггер(ы) сценария (например, изменение характеристики сервиса).
Напишите логику на JavaScript: чтение/запись характеристик, условия, задержки и т.д.
Сохраните. Сценарий автоматически станет доступен в разделе «Логика» подходящих устройств, если корректен.
Подключите сценарий к нужному устройству: Настройки устройства → Логика → выбрать сервис → добавить логику.

Структура логического сценария

Структура приведена строго по README (раздел «Написание сценариев → Логические → Структура сценария») и примеру LogicScenarioTemplate.js.

info = {
  name: "Название сценария",
  description: "Описание сценария",
  version: "1.0",
  author: "@Author",
  onStart: true,
  sourceServices: [HS.Switch],
  sourceCharacteristics: [HC.On],
  options: {},
  variables: {}
}

function trigger(source, value, variables, options, context) {
}

function compute(source, value, variables, options, context) {
}

Объект info

name: название сценария.
description: описание сценария.
version: версия (строка).
author: автор сценария.
onStart: выполнять при старте (true/false).
sourceServices: массив типов сервисов (HS.*). Смотрите «Типы сервисов» в хабе/редакторе.
sourceCharacteristics: массив характеристик (HC.*).
options: объект опций сценария, доступных в коде.
variables: объект переменных сценария, доступных в коде.

Функция trigger(source, value, variables, options, context)

Назначение: Основная функция сценария.

Является главной функцией и точкой входа в сценарии. Вызывается системой после выполнения compute и фактической установки значения.
При включённом onStart в блоке info вызывается при запуске хаба и при сохранении сценария с текущим значением характеристики. Работает ассинхронно.

function trigger(source, value, variables, options, context) {
          // Код сценария
}

Вызывается после compute(source, value, variables, options, context).
Используется для выполнения основной логики (управление устройствами, записи характеристик и т.п.).
Используйте методы API хаба из раздела «Список доступных методов в коде» на вики.

Параметры

source: источник события — объект характеристики устройства, изменение которой привело к срабатыванию сценария.
value: новое значение характеристики (после применения compute, если оно меняло значение).
variables: объект переменных сценария (сохраняется между вызовами; можно читать и изменять).
options: объект опций сценария, заданных в info.options и настраиваемых в интерфейсе. Только для чтения.
context: контекст вызова события - откуда пришло событие и какой путь привёл к его вызову до сценария.

Функция compute(source, value, variables, options, context)

Назначение: Изменить устанавливаемое значение характеристики.

Вызывается при изменении характеристики. Результат устанавливается в характеристику.

function compute(source, value, variables, options, context) {
          return value;
}

Параметры соответствуют параметрам trigger: source, value, variables, options, context.
Вызывается первой для каждого события.
ВНИМАНИЕ! Функция выполняется синхронно и может замедлять работу хаба или приводить к неожиданному поведению. Применять только при острой необходимости и с особой осторожностью. Не выполнять в ней сложных вычислений или долгих операций.

Доступные методы в коде

Полный список методов и возможностей API логических сценариев смотрите в разделе «Список доступных методов в коде» на вики. Ориентируйтесь на статьи: Логические сценарии и Элементы управления сценарием.

Проверка и отладка

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

Логические сценарии