Before you start using the Automation API, you should design your automations.
| **Important:** All household members can see when these automations run. Automations are for convenience only, not safety- or security-critical use cases. Don't create automations that could result in injury or harm if they fail to start or stop. Automations can depend on working internet, Wi-Fi, and service availability from both Google and the third parties who manufacture the devices included in automations. Automations may not always work, and Google is not responsible for any harm or losses incurred as a result of any failed 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 on Android](https://developers.home.google.com/apis/android/automation/supported-traits).
- The traits that should activate the automation as starters. Starters are discussed in [Automation
  components on Android](https://developers.home.google.com/apis/android/automation/dsl#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](https://developers.home.google.com/apis/android/automation/build#code_examples) 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 for
Android](https://developers.home.google.com/apis/android/structure), the [Device API for Android](https://developers.home.google.com/apis/android/device),
and the Discovery API.

|      API      |                                                                             Information                                                                             |
|---------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 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 |
[*Table 1: Home APIs and the information they can provide*]