The Automation DSL can be used to create automations that are more complex than those discussed in DSL guide - basic automations on Android.
Sequential with multiple actions
An automation can do more than one thing. For example, in place of the single
action
node, you could have multiple action
nodes, which run in sequential
order:
automation {
sequential {
starter<_>(...)
condition {...}
action {...}
action {...}
action {...}
}
}
Sequential with multiple parallel actions
If you place multiple action
nodes in a parallel
node, the actions execute
concurrently.
automation {
sequential {
starter<_>(...)
condition {...}
parallel {
action {...}
action {...}
action {...}
}
}
}
If there are action
nodes in the sequential
node that come after the
parallel
node, they wait to execute until all the nodes within the parallel
node have finished executing.
Delays
You can introduce pauses in your automations using the
delayFor
keyword, which takes a
java.time.Duration
argument representing how long to pause before continuing execution. The pause
duration may be as short as five seconds or as long as 24 hours.
For example, to toggle a light four times with a five-second pause between each toggle:
sequential {
action(light, OnOffLightDevice) { command(OnOff.toggle()) }
delayFor(Duration.ofSeconds(5))
action(light, OnOffLightDevice) { command(OnOff.toggle()) }
delayFor(Duration.ofSeconds(5))
action(light, OnOffLightDevice) { command(OnOff.toggle()) }
delayFor(Duration.ofSeconds(5))
action(light, OnOffLightDevice) { command(OnOff.toggle()) }
}
Trigger suppression
Trigger suppression is a capability that allows your automation to ignore a
starter
for a specified period of time after the initial triggering event. For
example, if the automation has a starter
that's triggered by motion detection,
and if you specify a trigger suppression duration of five minutes, then when the
starter
triggers, it won't trigger again for the next five minutes. This
prevents the automation from rapidly triggering over and over.
To apply trigger suppression to your automation, use the
suppressFor
keyword with a
java.time.Duration
argument representing how long to wait before responding to subsequent triggers.
The suppression duration may be as short as five seconds or as long as 24 hours.
automation {
sequential {
val starterNode = starter<_>(device, OccupancySensor, MotionDetection)
suppressFor(Duration.ofMinutes(30))
action(light, OnOffLightDevice) { command(OnOff.toggle()) }
}
Note that trigger suppression affects all starters
in an automation that
precede the suppressFor
.
Limit the number of executions
You can limit the number of times an automation is permitted to run.
For example, you might want to set up a one-time automation that runs the vacuum while you're away from home for the day.
To do this, set the automation's
maxExecutionCount
metadata field.
The following example is an automation that can only execute once:
automation { // The automation can only be executed once. maxExecutionCount = 1 // When the door lock state changes sequential { val doorLockEvent = starter<_>(doorLock, DoorLockDevice, LockOperationEvent) // if the door is unlocked condition() { expression = (doorLockEvent.lockOperationType equals LockOperationTypeEnum.Unlock) } // turn the light on action(light, DimmableLightDevice) { command(OnOff.on()) } } }
The automation is immediately deleted once it completes execution for the last
time and maxExecutionCount
is reached. The automation's history entry remains
in the Google Home app (GHA) Activity tab, including the automation_id
.
Set trait attributes in an action
To set the value of a trait attribute:
- Create an
update
node within anaction
node, including the relevant trait as an argument to theupdate
node:action(deviceReference, deviceType) { update(trait) { } }
- Within the
update
node, for each attribute to be modified, use a mutator function, and pass it the new value. To form the name of the mutator function:- Capitalize the name of the attribute
- Prefix it with the word
set
.
defaultMoveRate
, you'd use a mutator function calledsetDefaultMoveRate
.
Note that an update
node can have multiple mutator functions. Here's an
example where two attributes are updated:
action(device, Fan) {
update(FanControl) {
setPercentSetting(50u)
setRockSetting(FanControlCluster.RockBitmap.rockUpDown)
}
}