Android DSL のコンセプト

これは、Android の Automation DSL の基本的なコンセプトの概要です。

自動化のコンポーネント

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

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

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

開始条件 \- テレビの電源がオンになりました。これは、テレビのトレイトの状態の変化です。
条件— テレビがある家の現在の時刻が評価されます。
アクション \- テレビと同じ部屋の照明が暗くなります。

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

基本構造に加えて、Home APIs の自動化には、デベロッパーとユーザーが自動化を識別するために使用できるメタデータ（名前や説明など）も含まれています。

ノード

Home APIs では、自動化の論理構造はノード で構成されます。ノードは、エンティティの動作または実行フローを表す抽象的な再利用可能なユニットです。各ノードには入力変数と、他のノードで使用される出力変数を含めることができます。

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

行動ノード

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

行動ノードは通常、デバイスのトレイトに関連付けられ、他のノードの入力として使用するトレイトの状態を出力します。

実行フローノード

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

たとえば、順次フローには、順番に実行されるノードが含まれる場合があります。通常、これらは開始条件、条件、アクションです。

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

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

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

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

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

ネストされたフロー

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

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

*テーブル: ノードの組み合わせ方*
ノード	次のノードタイプとデータを含めることができます	次のいずれかのノードタイプ内に存在する必要があります
開始条件	Expression	選択、順次
ManualStarter		選択、順次
StateReader	式（通常はトレイト属性値で構成されます）	アクション、条件
アクション	コマンド、エンティティ、式	並列、選択、順次
順次	並列、選択、順次
並列	アクション	順次
条件	Expression	並列、順次
選択	条件、順次、開始条件、ManualStarter	順次。フローの最初のノードにする必要があります

Automation DSL

Home APIs では、自動化は Automation DSL（ドメイン固有言語）を使用して定義されます。Automation DSL は、 Kotlin DSL（ドメイン固有言語）として実装され、Kotlin タイプセーフビルダーを使用し、自動化テンプレートを定義するために特別に設計されています。

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

Automation DSL を使用すると、自動化の構築プロセスを簡素化して効率化できます。Device API で提供されている Matter 標準トレイトと 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 ノードで使用する変数に割り当てられます。

ブロックされる操作

基本的な自動化