Android DSL ガイド

以下のガイドでは、さまざまな Automation DSL ノードを使用して自動化を構築する方法について説明します。

すべての自動化 DSL は、単一の automation ノード内に配置されます。automation ノードは、外部の Kotlin 言語コンテキストと埋め込み DSL コンテキストの境界を形成します。

シーケンシャルフロー

シーケンシャルフローは、自動化フローのデフォルトのタイプです。

Sequential DSL の例

開始条件、条件、アクションで構成されるシーケンシャルフローを使用する、非常に基本的な自動化 DSL テンプレートを次に示します。


import com.google.home.automation.action
import com.google.home.automation.automation
import com.google.home.automation.condition
import com.google.home.automation.sequential
import com.google.home.automation.starter

...

automation {
  sequential {
    starter<_>(...)
    condition {...}
    action {...}
  }
}

これは、ノードを追加することで改善できます。

開始条件

開始条件ノードは、自動化を有効にする初期条件を定義します。たとえば、状態や値の変更などです。自動化には少なくとも 1 つの開始条件が必要です。そうでない場合、検証に失敗します。自動化に複数の開始条件を追加するには、select ノードを使用する必要があります。

トレイト属性に基づく開始条件

トレイト属性に基づく開始条件ノードを宣言する場合は、次のものを指定します。

デバイス
トレイトが属するデバイスタイプ
トレイト

starter<_>(thermostat, TemperatureSensorDevice, TemperatureMeasurement)

デバイスタイプパラメータは、自動化がデバイス内のどのデバイスタイプを対象とするかを指定できるため、必須です。たとえば、デバイスは FanDevice と HeatingCoolingUnitDeviceで構成され、どちらにも OnOff トレイトが含まれている場合があります。デバイスタイプを指定することで、デバイスのどの部分が自動化をトリガーするのかが明確になります。

イベントに基づく開始条件

イベントに基づく開始条件ノードを宣言する場合は、次のものを指定します。

デバイス
トレイトが属するデバイスタイプ
イベント

starter<_>(doorBell, GoogleDoorbellDevice, DoorbellPressed)

構造とイベントに基づく開始条件（パラメータ付き）

一部のイベントにはパラメータを含めることができるため、これらのパラメータも開始条件に含める必要があります。

たとえば、この開始条件では、 Time トレイトの ScheduledTimeEvent を使用して、午前 7 時に自動化を有効にします。

val earlyMorning = starter<_>(structure, Time.ScheduledTimeEvent) {
  parameter(Time.ScheduledTimeEvent.clockTime(
    LocalTime.of(7, 0, 0, 0)))
}

天気に基づく開始条件

天気トレイトを使用して、開始条件で現在または予測される気象条件を指定できます。

val weatherState = starter<_>(structure, trait = Weather)

例については、自動化の例ページの雨が降りそうな場合はブラインドを閉じるをご覧ください。

手動開始イベント

手動開始イベントは、ユーザーが自動化を手動で実行できる特別なタイプの開始条件です。

手動開始イベントを宣言する場合:

トレイトまたはデバイスタイプを指定しないでください。
`Automation.execute()` を呼び出す UI 要素を指定します Automation.execute()。

手動開始イベントを別の開始条件とともに select フローに配置すると、手動開始イベントが他の開始条件をオーバーライドします。

select {
  manualStarter()
  starter<_>(thermostat, TemperatureSensorDevice, TemperatureMeasurement)
}

手動開始イベントの後に続く condition ノードは評価され、condition 式によっては自動化の実行がブロックされる可能性があります。

手動スターターを条件付きスターターから分離する

手動開始イベントで有効になった自動化を condition ノードがブロックしないように自動化を構成する 1 つの方法は、他の開始条件をその condition とともに別のシーケンシャルフローに配置することです。

automation_graph {
  sequential {
    select {
      sequential {
        starter<_>(...)
        condition {...}
      }
      sequential {
        manualStarter()
      }
    }
    action {...}
  }
}

属性の値を参照する

式で属性の値を使用するには、次の構文を使用します。

stateReader を使用する場合:

val time = stateReader<_>(structure, Structure, Time)
val currTime = time.currentTime

starter を使用する場合:

val starterNode = starter<_>(device1, LaundryWasherDevice, OnOff)
condition() {
  expression = starterNode.onOff equals true
}

条件ノードと式

条件ノードは、自動化を続行するかどうかを決定する決定ポイントを表します。自動化には複数の condition ノードを含めることができます。いずれかの condition ノードの式が false と評価されると、自動化全体の実行が終了します。

condition ノード内では、式が単一のブール値に評価される限り、さまざまな演算子を使用して複数の条件基準を組み合わせることができます。結果の値が true の場合、条件が満たされ、自動化は次のノードの実行を続行します。false の場合、自動化はその時点で実行を停止します。

式は Kotlin の式と同様に形成され、数値、文字、文字列、ブール値などのプリミティブ値や Enum 値を含めることができます。サブ式をかっこでグループ化すると、評価順序を制御できます。

複数のサブ式を 1 つの式に結合する condition の例を次に示します。

condition() {
  val expr1 = starterNode.lockState equals DlLockState.Unlocked
  val expr2 = stateReaderNode.lockState equals true

  val expr3 = occupancySensingDevice.occupied notEquals 0
  val expr4 = timeStateReaderNode
    .currentTime
    .between(
      timeStateReaderNode.sunsetTime,
      timeStateReaderNode.sunriseTime)
  expression = (expr1 and expr2) or (expr3 and expr4)
}

開始条件を介してアクセスされるトレイトの値を参照できます。

val starterNode = starter<_>(device, OnOff)
condition() { expression = starterNode.onOff equals true }

stateReader

condition ノードでトレイト属性値を参照するもう 1 つの方法は、stateReader ノードを使用することです。

これを行うには、まず stateReader ノードでトレイト属性値をキャプチャします。stateReader は、structure とトレイトを引数として取ります。

import com.google.home.automation.stateReader
...
val filterMonitoringState = stateReader<_>(structure, ActivatedCarbonFilterMonitoring)

次に、condition ノードで stateReader を参照します。

condition() {
  expression =
    filterMonitoringState.changeIndication
      .equals(ChangeIndicationEnum.Warning)
}

比較演算子と論理演算子を使用すると、複数の stateReadersをconditionノードで使用できます。

val armState = stateReader<_>(doorLock, DoorLockDevice, ArmDisarm )
val doorLockState = stateReader<_>(doorLock, DoorLockDevice, DoorLock)
condition() {
  expression =
    (armState.armState equals true)
    and
    (doorLockState.lockState equals true)
}

条件の期間

条件のブール式に加えて、自動化を実行するために式が true になる必要がある期間を指定できます。たとえば、照明が 10 分間点灯している場合にのみトリガーされる条件を定義できます。

  condition {
    expression(lightStateReader.onOff == true)
    forDuration(Duration.ofMinutes(10))
  }

期間は 5 秒から 24 時間まで指定できます。

アクションノード

アクションノードは、自動化の処理が行われる場所です。この例では、アクションは AssistantBroadcast トレイトの broadcast() コマンドを呼び出します。

action(device, SpeakerDevice) {
  command(AssistantBroadcast.broadcast("Intruder detected!"))
}

インポートステートメント

自動化を開発する場合、Home API のさまざまな要素をコードにインポートする方法が明確でないことがあります。

トレイト属性は、トレイトの Companion オブジェクトからインポートされます。

import com.google.home.matter.standard.OnOff.Companion.onOff

トレイトによって定義されるデータ構造は、名前が「-Trait」で終わるトレイトクラスからインポートされます。

import com.google.home.matter.standard.MediaPlaybackTrait.PlaybackStateEnum

トレイトコマンドは、トレイトの Companion オブジェクトからインポートされます。

import com.google.home.matter.standard.Thermostat.Companion.setTemperatureSetpointHold

DSL のコンセプト

複雑な自動化

Android DSL ガイド コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

シーケンシャル フロー