The automations Struct is the core of an automation script. This is where the
automation behavior is specified, including starters, conditions, and actions.
Collectively these are also referred to as an automation rule.
An automations Struct contains one or more automation rules, and each rule
always contains a set of starters and actions. A rule may optionally contain
conditions, which are additional qualifiers that must be in place in order for
the script to be executed.
| Key | Type | Description |
|---|---|---|
|
|
Optional Name of the automation. This is not shown to users, it is for developer reference only. |
|
|
|
[Starter] |
Required A list of starters. |
|
|
Optional Condition |
|
|
|
[Action] |
Required A list of actions |
Examples
Following are two introductory examples of automations Structs.
In the first example, the automation is started when a
TV named "My TV" is turned on.
Once triggered, the following actions are performed:
Two LIGHT
devices, named "Light A" and "Light B", are turned on and set to
brightness level 50.
automations:
- name: Dim the lights
starters:
- type: device.state.OnOff
device: My TV - Living Room
state: on
is: true
actions:
- type: device.command.OnOff
devices:
- Light A - Living Room
- Light B - Living Room
on: true
- type: device.command.BrightnessAbsolute
devices:
- Light A - Living Room
- Light B - Living Room
brightness: 50
In the second example, the same automation is started at sunset each Monday and Thursday:
automations:
- name: Dim the lights
starters:
- type: time.schedule
at: SUNSET
weekday:
- MONDAY
- THURSDAY
state: on
is: true
actions:
- type: device.command.OnOff
devices:
- Light A - Living Room
- Light B - Living Room
on: true
- type: device.command.BrightnessAbsolute
devices:
- Light A - Living Room
- Light B - Living Room
brightness: 50
Starters
The Starter Struct is where you specify the starters that cause the
Automation script to be executed. Each automation may contain one or more starters, and at least one starter must evaluate to true for subsequent conditions to be evaluated.
An example of a time.schedule starter:
type: time.schedule
at: sunrise+30min
weekdays:
- MON
- TUE
An example of a starter on device state changes:
type: device.state.Volume
device: My TV - Living Room
state: currentVolume
greaterThan: 1
lessThan: 10
An example of a starter on a device event:
type: device.event.DoorbellPress
device: My doorbell - Frontdoor
An example of a starter on home presence mode changes:
type: home.state.HomePresence
state: homePresenceMode
is: HOME
View the full list of starters.
Condition
Conditions can be combined with logical operators and, or, and not to
express more complex logic.
In the following example, there is a condition Struct with one time
condition and one device.state condition. This Struct allows the script to
run if it's between sunset and sunrise on a Monday or Tuesday, or, if the TV
volume is between 1 and 10:
type: or
conditions:
- type: time.between
before: sunrise
after: sunset
weekdays:
- MON
- TUE
- type: device.state
device: My TV - Living Room
trait: Volume
state: currentVolume
greaterThanOrEqualTo: 1
lessThanOrEqualTo: 10
A basic time condition example that limits execution of an Automation script
to weekends before 10:00 in the morning:
type: time.between
before: 10am
weekdays:
- SAT
- SUN
A thermostat device sensor temperature condition:
type: device.state.TemperatureSetting
device: My Thermostat - Living Room
state: thermostatTemperatureAmbient
greaterThan: 65F
An example of a home.state.HomePresence condition:
type: home.state.HomePresence
state: homePresenceMode
is: AWAY
View the full list of conditions.
Actions
Like starters and conditions, each action has a type which indicate what kind
of action is being specified.
The most important and the
most useful ones are the device.command command types. An action example of turning off lights.
type: device.command.OnOff
devices:
- Light A - Living Room
on: false
An action to add a delay between multiple other actions.
type: time.delay
for: 5min