次のガイドでは、さまざまな Automation DSL ノードを使用して自動化を構築する方法について説明します。
すべての自動化 DSL は、単一の automation ノード内に配置されます。automation ノードは、外部の Kotlin 言語コンテキストと埋め込み DSL コンテキストの境界を形成します。
シーケンシャル フロー
シーケンシャル フローは、デフォルトの自動化フローのタイプです。
開始条件、条件、アクションで構成されるシーケンシャル フローを使用する、非常に基本的な Automation 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 {...}
}
}
ノードを追加することで、これを改善できます。
Starter
開始ノードは、自動化を有効にする初期条件を定義します。たとえば、状態や値の変化などです。自動化には少なくとも 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)))
}
手動スターター
手動開始条件は、ユーザーが自動化を手動で実行できる特別なタイプの開始条件です。
手動スターターを宣言する場合:
- トレイトまたはデバイスタイプを指定しないでください。
Automation.execute()を呼び出す UI 要素を提供します。
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 の式と同様に形成され、数値、文字、文字列、ブール値などのプリミティブ値や、列挙型値を含めることができます。部分式をかっこでグループ化すると、評価の順序を制御できます。
複数のサブ式を 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)
}
比較演算子と論理演算子を使用して、condition ノードで複数の stateReaders を使用できます。
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))
}
期間は 1 ～ 30 分の範囲で指定できます。
アクション ノード
アクションノードは、自動化の作業が行われる場所です。この例では、アクションは 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