Это обзор фундаментальных концепций Automation DSL.
Компоненты автоматизации
Автоматизация состоит из следующих основных компонентов, которые обычно оцениваются в следующем порядке:
- Стартер — определяет начальные условия, которые активируют автоматизацию, например изменение признака. Автоматика должна иметь стартер.
- Условие — любые дополнительные ограничения, которые необходимо оценить после активации автоматизации. Выражение в условии должно иметь значение
true, чтобы действия автоматизации продолжались. - Действие — команды или обновления состояния, которые выполняются при выполнении всех условий.
Например, возможно, у вас есть автоматика, которая приглушает свет в комнате, когда телевизор в этой комнате включается между закатом и восходом солнца. В этом примере:
- Стартер — Телевизор был включен, что является изменением состояния характеристики телевизора.
- Состояние — оценивается текущее время дома, в котором находится телевизор.
- Действие — Свет в той же комнате, где находится телевизор, приглушен.
Автоматизация активируется при включении телевизора в комнате, но автоматизация срабатывает только в том случае, если соблюдено условие «время между закатом и восходом солнца».
Помимо базовой структуры, автоматизации в Home API также содержат метаданные, такие как имя и описание , которые могут использоваться для их идентификации разработчиками и пользователями.
Узлы
В Home API логическая структура автоматизации состоит из узлов . Узлы — это абстрактные, повторно используемые единицы, которые представляют поведение сущностей или потоки выполнения. Каждый узел может иметь входные переменные, а также выходные переменные, которые могут использоваться другими узлами.
| Узел | Тип узла | Котлин-реализация | Описание |
|---|---|---|---|
| Стартер | Поведенческий | StarterNodeDsl | Запускает автоматизацию при изменении состояния признака (любого атрибута). |
| StateReader | Поведенческий | StateReaderNodeDsl | Считывает атрибут типажа и позволяет захватить его значение для использования в узлах условий. |
| Действие | Поведенческий | ActionNodeDsl | Вызывает команды типажа. |
| Последовательный | Поток выполнения | SequentialFlow | Последовательно выполняет вложенные узлы действий. Это поведение выполнения по умолчанию. |
| Параллельно | Поток выполнения | ParallelFlow | Выполняет вложенные узлы действий параллельно. |
| Состояние | Поток выполнения | ConditionNodeDsl | Условно изменить поток выполнения на основе оценок логических выражений. Условия могут быть связаны со стартером (специальные условия для стартера) или быть глобальными (применяться ко всем стартерам). |
| Выбирать | Поток выполнения | SelectFlow | Позволяет более чем одному пусковому устройству активировать автоматику. |
| Выражение | Ценить | Expression | Может быть значением атрибута признака, константой или литеральным значением и должно оцениваться как список, число, логическое значение или строка. |
Поведенческие узлы
Такие узлы, как стартеры и действия, являются поведенческими узлами. Стартеры активируют автоматизацию на основе изменений атрибутов устройства. Действия выдают команды устройству или обновляют атрибуты.
Поведенческие узлы обычно привязаны к характеристикам устройства и состоянию выходных характеристик для использования в качестве входных данных в других узлах.
Узлы потока выполнения
Некоторые узлы представляют потоки выполнения, например последовательные и параллельные. Каждый из этих узлов содержит поведенческие узлы, определяющие автоматизацию.
Например, последовательный поток может содержать узлы, которые выполняются в последовательном порядке. Обычно это стартер, условие и действие.
В параллельном потоке может одновременно выполняться несколько узлов действий, например одновременное включение нескольких источников света. Узлы, следующие за параллельным потоком, не будут выполняться, пока не завершатся все ветви параллельного потока.
Другой тип потока выполнения — это поток условий , который может изменять поток выполнения на основе оценки выражения.
Например, возможно, у вас есть автоматизация, которая выполняет действие в зависимости от того, наступила ночь или нет. Узел условия проверяет время суток, а затем следует соответствующему пути выполнения на основе этой оценки.
Поток выбора полезен, когда вы хотите иметь более одного стартера, который может активировать вашу автоматизацию. Когда вы объединяете два или более стартеров в поток select , любой из стартеров может активировать автоматизацию.
Например, вы можете написать автоматику, которая опускает жалюзи на закате, если температура поднимается выше определенного порога или если яркость превышает порог. Каждый из этих сценариев обрабатывается тремя отдельными запускателями, и все три будут заключены в поток select .
Вложенные потоки
В сложных системах автоматизации узлы потока выполнения также могут быть вложенными. Например, у вас может быть последовательный поток, который выполняет параллельный поток.
Узлы DSL могут быть вложены и объединены различными способами в соответствии с вашими конкретными потребностями в соответствии с ограничениями, изложенными в следующей таблице. Столбец «Builder» ссылается на документацию по типобезопасному сборщику Kotlin, в которой подробно описано, что разрешено для использования в каждом типе узла.
| Узел | Строитель | Может содержать следующий тип узла и данные | Должен находиться в одном из следующих типов узлов. |
|---|---|---|---|
| Стартер | AutomationBuilder | Выражение | Выбор, Последовательный |
| Ручной Стартер | AutomationBuilder | Выбор, Последовательный | |
| StateReader | AutomationBuilder | Выражение (обычно состоящее из значения атрибута признака) | Действие, Состояние |
| Действие | ActionBuilder | Команда, Сущность, Выражение | Параллельный, Выборочный, Последовательный |
| Последовательный | SequentialFlowBuilder | Параллельный, Выборочный, Последовательный | |
| Параллельно | ParallelFlowBuilder | Действие | Последовательный |
| Состояние | ConditionBuilder | Выражение | Параллельный, Последовательный |
| Выбирать | AutomationBuilder | Состояние, Последовательный, Стартер, Ручной Стартер | Последовательный и должен быть первым узлом в потоке. |
Автоматизация DSL
В домашних API автоматизация определяется с помощью Automation DSL (язык, специфичный для предметной области). Automation DSL реализован как Kotlin DSL (предметно-ориентированный язык) с использованием типобезопасных сборщиков Kotlin и специально разработан для определения шаблонов автоматизации.
При компиляции автоматизации типобезопасные сборщики Kotlin генерируют классы данных Kotlin, которые затем сериализуются в буфер протокола JSON, который используется для вызовов служб автоматизации Google.
Automation DSL упрощает и оптимизирует процесс автоматизации зданий. Изначально он использует ту же модель данных , что и стандартные характеристики Matter и характеристики smart home представленные в API устройства.
Automation DSL также определяет логику автоматизации с точки зрения абстрактных типов устройств, а не конкретных экземпляров устройств, расположенных в доме пользователя. Это позволяет разработчику предоставлять входные параметры, которые могут использоваться во время выполнения для указания реальных экземпляров устройства, а также других важных значений параметров.
Синтаксис DSL аналогичен синтаксису Kotlin и в равной степени типобезопасен, но автоматизация, написанная на Automation DSL, проще и лаконичнее, чем та же автоматизация, написанная на чистом Kotlin.
Пример
Ниже приведен пример автоматизации, которая включает устройство, написанный с использованием Automation DSL:
val automation = automation {
name = "MyFirstAutomation"
description = "If light1 is on, turn on light2."
isActive = true
sequential {
val onOffTrait = starter<_>(device1, OnOffLightDevice, OnOff)
condition() { expression = onOffTrait.onOff equals true }
action(device2, OnOffLightDevice) { command(OnOff.on()) }
}
}
Эта автоматизация очень проста: когда включается индикатор device1 (атрибут onOff меняется на true ), затем отправляется команда on() для включения device2 .
Автоматизация использует sequential узел, что указывает на то, что его узлы будут работать в последовательном порядке.
Внутри sequential узла находятся поведенческие узлы, такие как starter , condition и action . Выход starter узла присваивается переменной для использования в узле condition .