このページは Cloud Translation API によって翻訳されました。

DSL のコンセプト

Automation DSL の基本コンセプトの概要について説明します。

自動化コンポーネント

自動化は次の基本コンポーネントで構成され、通常は次の順序で評価されます。

開始条件 - 自動化を有効にする初期条件（特徴の変更など）を定義します。自動化には開始条件が必要です。
条件 - 自動化が有効になった後に評価する追加の制約。自動化のアクションを続行するには、条件の式が true に評価される必要があります。
アクション - すべての条件が満たされたときに実行されるコマンドまたは状態の更新。

たとえば、日の入りから日の出までの間に部屋のテレビの電源がオンになったときに、その部屋の照明を暗くする自動化を設定できます。この例では、次のようになります。

Starter - テレビがオンになった。これは、テレビの特徴の状態の変化である。
条件 - テレビが設置されている家の現在の時刻が評価されます。
アクション - テレビと同じ部屋の照明が暗くなります。

自動化は部屋のテレビの電源がオンになると有効になりますが、「日の入りから日の出まで」の条件が満たされた場合にのみ実行されます。

Home API の自動化には、基本構造に加えて、name や description などのメタデータも含まれます。これは、デベロッパーとユーザーが自動化を識別するために使用できます。

ノード

Home API では、自動化の論理構造はnodesで構成されます。ノードは、エンティティの動作や実行フローを表現する抽象的な再利用可能な単位です。各ノードには、入力変数と、他のノードで使用される出力変数を設定できます。

*表: 自動化ノードのタイプ*
ノード	ノードタイプ	Kotlin の実装	説明
Starter	行動	`StarterNodeDsl`	特徴の状態（任意の属性）が変更されたときに自動化を開始します。
StateReader	行動	`StateReaderNodeDsl`	特徴属性を読み取り、その値をキャプチャして条件ノードで使用できるようにします。
アクション	行動	`ActionNodeDsl`	トレイトコマンドを呼び出します。
順次	実行フロー	`SequentialFlow`	ネストされたアクションノードを順番に実行します。これはデフォルトの実行動作です。
並列	実行フロー	`ParallelFlow`	ネストされたアクションノードを並列で実行します。
条件	実行フロー	`ConditionNodeDsl`	論理式の評価に基づいて実行フローを条件付きで変更します。条件は開始条件に関連付けることも（開始条件固有の条件）、グローバルに設定することも（すべての開始条件に適用）できます。
選択	実行フロー	`SelectFlow`	複数の開始条件で自動化を有効にできます。
Expression	値	`Expression`	トレイトの属性、定数、リテラル値の値にできます。リスト、数値、ブール値、文字列に評価される必要があります。

行動ノード

開始条件やアクションなどのノードは、動作ノードです。開始条件は、デバイスの属性の変化に基づいて自動化を有効にします。アクションは、デバイスコマンドを実行するか、属性を更新します。

動作ノードは通常、デバイスの特性と出力特性の状態に関連付けられ、他のノードで入力として使用されます。

実行フローノード

一部のノードは、順序実行や並列実行などの実行フローを表します。これらのノードには、自動化を定義する動作ノードが含まれています。

たとえば、順序型のフローには、順序どおりに実行されるノードが含まれます。通常、これらは開始条件、条件、アクションです。

並列フローでは、複数の照明を同時にオンにするなど、複数のアクションノードが同時に実行される場合があります。並列フローに続くノードは、並列フローのすべてのブランチが完了するまで実行されません。

実行フローのもう 1 つのタイプは、条件フローです。これは、式の評価に基づいて実行フローを変更できます。

たとえば、夜間かどうかに基づいてアクションを実行する自動化があるとします。条件ノードは時刻を確認し、その評価に基づいて適切な実行パスをたどります。

選択フローは、自動化を有効にできる開始条件を複数用意する場合に便利です。2 つ以上の開始条件を select フロー内に含めると、いずれかの開始条件で自動化を有効にできます。

たとえば、日没時、温度が特定のしきい値を超えた場合、または明るさがしきい値を超えた場合にブラインドを下げる自動化を作成できます。これらのシナリオはそれぞれ 3 つの個別の開始条件で処理され、3 つすべてが select フロー内にラップされます。

ネストされたフロー

複雑な自動化では、実行フローノードをネストすることもできます。たとえば、並列フローを実行する順次フローがあります。

DSL ノードは、次の表に示す制約に従って、特定のニーズに合わせてさまざまな方法でネストして組み合わせることができます。ビルダー列は、Kotlin のタイプセーフビルダーのドキュメントにリンクしています。このドキュメントには、各タイプのノードで使用できる内容が詳しく記載されています。

*表: ノードを組み合わせる方法*
ノード	Builder	次のノードタイプとデータが含まれている場合があります。	次のいずれかのノードタイプ内にある必要があります。
Starter	`AutomationBuilder`	式	選択、順次
ManualStarter	`AutomationBuilder`		選択、順次
StateReader	`AutomationBuilder`	式（通常は特徴属性値で構成）	アクション、条件
アクション	`ActionBuilder`	コマンド、エンティティ、式	並列、選択、順次
順次	`SequentialFlowBuilder`	並列、選択、順次
並列	`ParallelFlowBuilder`	アクション	順次
条件	`ConditionBuilder`	式	並列、順次
選択	`AutomationBuilder`	Condition、Sequential、Starter、ManualStarter	順序型で、フロー内の最初のノードにする必要があります

自動化 DSL

Home API では、自動化は Automation DSL（ドメイン固有言語）を使用して定義されます。Automation DSL は、Kotlin の型安全なビルダーを使用して Kotlin DSL（ドメイン固有言語）として実装され、自動化テンプレートの定義用に特別に設計されています。

自動化がコンパイルされると、Kotlin の型安全ビルダーが Kotlin データクラスを生成し、プロトコルバッファ JSON にシリアル化します。この JSON は、Google の自動化サービスへの呼び出しに使用されます。

Automation DSL は、自動化の構築プロセスを簡素化し、効率化します。Matter 標準の特徴と Device API の smart home 特徴の同じデータモデルをネイティブに使用します。

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 ノードで使用するために変数に割り当てられます。