Design an automation

Before you start using the Automation API, you should design your automations.

Determine the following parameters for each automation:

  • The circumstances under which the automation should be suggested to the user. For example, if the user has just added three new lights to their home, they might be interested in a particular automation tailored to controlling lights.
  • Which device types are required for the automation. For example, if the user has just added three new lights to their home, they might be interested in a particular automation tailored to controlling lights. Example light device types include OnOffLightDevice, ColorTemperatureLightDevice, DimmableLightDevice, or ExtendedColorLightDevice.
  • Which trait attributes and commands are required for the automation, and whether they are supported by the Automation API.
  • The traits that should activate the automation as starters. Starters are discussed in Automation components.
  • Additional conditions that determine whether the automation should actually run, and which actions are to be performed.
  • The execution flow for the automation. Should it execute sequentially or in parallel? Do you require multiple logic paths?

When designing, it may be useful to diagram the flow of the automation, node by node, with the logic required at each step.

Once you have designed an automation, use the Automation DSL to build it. The automation you build is essentially a "template" — any structures and devices in it are placeholders and populated with each user's specific structure and devices when they "adopt" the automation for their own use.

The following are different kinds of automations that an app could create using the Home APIs. See the Build an automation page for code excerpts pertaining to these examples.

Simple automation

Say you needed to write an app that creates an automation that raises the blinds at 8:00am. To accomplish this, the app needs a list of the blinds (devices with the WindowCoveringDevice device type) present in the structure that support automations, which can be provided by the Discovery API.

For automations that need to run at a certain time, you also need to ensure that the user has assigned a street address for their chosen structure in the Google Home app (GHA), otherwise, the automation doesn't know the time zone where it will run. The Discovery API can help you determine whether or not an address was assigned to the structure.

So the execution flow would appear something like this:

  1. Using the Discovery API, gather the list of WindowCoveringDevice devices.
  2. If the street address isn't populated, notify the user that they need to provide a street address, and halt execution.
  3. Othewrwise, define the automation:
    1. Start the automation at 8:00am.
    2. For each of the blinds, call the WindowCovering trait's upOrOpen command.

Complex automation

Imagine an app that builds an automation that triggers blinking lights when motion is detected.

One of the first tasks in implementing this app is to find out what lights are available in the user's home using the Discovery API. Withthis information, your app can now display the available lights and perhaps allow the user to select which lights they want to blink.

The execution flow:

  1. Using the Discovery API, gather the list of light devices present in the structure, which would be any devices with a device type of OnOffLightDevice, ColorTemperatureLightDevice, DimmableLightDevice, or ExtendedColorLightDevice.
  2. Provide a way to select the lights that blink, perhaps through a custom Settings panel.
  3. Define the automation:
    1. Start the automation whenever someone leaves or arrives at the premises, by monitoring AreaPresenceState.
    2. If the presenceState indicates the structure is occupied, blink the chosen lights.

Generic automation

For an example of a more sophisticated automation, consider one that guides the user through creating an open-ended automation, based on any or all the devices they have in their home.

The automation might first prompt the user to select a structure.

Then the automation could display all the rooms in the structure in expandable outline view, where expanding a room shows the devices in it. Further expanding a device lists the starters, and commands supported by that device.

The user could choose the devices, starters, and commands they want to use, and the automation would walk the user through assembling an automation.

When all the user's choices and decisions are final, the automation would generate the automation and save it to their chosen structure.

At a high level, such an automation would need to gather several sets of data about the user's home using the Structure API, the Device API, and the Discovery API.

Table 1: Home APIs and the information they can provide
APIInformation
Structure API
  • What structures are available
  • What rooms are in the structure
Device API
  • What devices are in the chosen structure
  • Where those devices are located (which room)
Discovery API
  • What traits are supported by the devices
  • What starters and commands are available on those traits
  • What constraints exist on the parameters for these commands
Previous
Automation API overview
Next
Build an automation