Automations

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.

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

View the full list of the actions.