Create an automation template

1. Introduction

What you'll learn

How to design and write an automation template.
How to test an automation template using the Google Home Developer Console.

What you'll need

An Android or iOS phone running the Google Home app.
Either a smart light that is onboarded to your home, or a simulated device in the Google Home Playground.

Prerequisites

You should be familiar with how to write a Google Home automation. If you've never written an automation, consider doing the Create a scripted automation codelab before proceeding with this one.

2. Automation templates and instances

Developers create automation templates using the automation template editor in the Google Home Developer Console. Automation templates contain the essence of the script logic, referencing device types, but not specific devices.

Using the Google Home for web's automation script editor, end-users take an automation template and create a personalized instance that acts on the specific devices in their own home. Once saved, the instance appears under Household Routines in the Google Home app (GHA).

3. Plan your automation template

When creating an automation, one starts by thinking about the problem one is trying to solve, and what the automation will do to solve the problem. This includes such considerations as:

Which devices you want to automate.
What starter (or event) should trigger execution of the automation.
What additional conditions, if any, control whether or not the automation runs once it is triggered.
What actions are to be performed.

For purpose of this codelab, your the automation will do two things:

Turn on a light at a specific time.
Turn the same light off at a specific time.

With this in mind, you are ready to open the template editor and write the automation.

4. Write the automation template

Automations are written in a declarative fashion using the YAML data-serialization language.

An automation template has three primary sections:

Metadata - The name of the automation, a description of what it does, and optionally, some tags that are used to classify the automation. The keywords are:
- LIGHTING AND PLUGS
- CLIMATE AND ENERGY
- SECURITY AND AWARENESS
- ENTERTAINMENT
- APPLIANCES AND MORE
Input - Defines what kind of device(s) the automation is intended to control. The automation engine uses this information to know what kinds of actions are valid for the intended devices.
Automation rules — Defines the initiation logic and behavior of the automation.

This is the automation template that you'll be working with:

metadata:
  name:
    en: Scheduled light
  description:
    en: Turn the light on and off at specific times
  tags:
    - LIGHTING AND PLUGS
input:
  the_light:
    metadata:
      name:
        en: The light
      description:
        en: The light to be controlled
    selector:
      type: device
      multiSelect: true
      supportedTypes:
        - LIGHT
  time_on:
    metadata:
      name:
        en: Time to turn on the light.
      description:
        en: The time of day to turn on the selected light.
    selector:
      type: time
      default: sunset+30min
  time_off:
    metadata:
      name:
        en: Time to turn off the light.
      description:
        en: The time of day to turn off the selected light.
    selector:
      type: time
      default: 10:00 pm
automations:
  - name: Turn on the light
    starters:
      - type: time.schedule
        at: $time_on
    actions:
      - type: device.command.OnOff
        devices: $the_light
        on: true
  - name: Turn off the light
    starters:
      - type: time.schedule
        at: $time_off
    actions:
      - type: device.command.OnOff
        devices: $the_light
        on: false

Read through the template and note the following:

The metadata section contains the name and description of this automation.
The input section defines a variable named the_light which specifies a device of type LIGHT. This means that this template may only be used for lights, not for other types of devices. In other words, when a user, setting up your automation in their home, is prompted to select a device for $the_light, their choice of device is restricted to devices of the type that you specified.
Also defined in the input section are two variables named time_on and time_off. These allow the user to specify when to start the automations. time_on represents the time that the light is turned on, and time_off represents the time that the light is turned off. If the user does not set the value of time_on or time_off, the default values are used.
The automations section of our automation contains two automation rules. Each rule has a single time.schedule starter that tells the automation what time to initiate that automation.

The template editor

The automations template editor is the tool you use to write automation templates.

Go to the Google Home Developer Console.
Sign in with the same account that your device is set up with in the Google Home app.
Create or select an existing project.
Under Automations, click Develop.
Click Create a template.
Copy the "Scheduled light" automation template.
Paste the "Scheduled light" automation template into the template editor.
Click Validate. Resolve any errors that may come up and keep validating and fixing until no errors are raised.
Click Save to save the template.

5. Test the template

Now you can test the template in the Console.

Make sure your light is plugged in and visible in the Google Home app.
If the light is on, turn it off.
Go to the Google Home Developer Console.
Open the project where you created your template.
Select Automations, then select the Test tab.
Click Open next to the "Scheduled light" automation template.
Select the structure in which you want to test the template, then click Next.
In the InputValue editor, specify the name of your light. For example, if your light is named "Desk light - Office", you'd select Desk light - Office from the drop-down menu that appears when you click to the right of lights. Or you may type the name of the device.
Also in the InputValue editor, specify the time_on time to a time say, five minutes in the future, and change the time_off time to a time shortly after the time_on.

When you're done, the InputValue editor should look something like this:

inputValue:
 #add value
 the_light: Desk light - Office
 #add value
 time_off: 11:45 am
 #add value
 time_on: 11:40 am

Click Activate test.
Wait for the two starter times to pass. The light should come on and then go off at the specified times.

Once you've successfully tested your template, you know your automation is functionally sound.

6. Congratulations!

You've successfully created an automation template. Awesome!

In this codelab you learned how to:

How to design and write an automation template.
How to test it in the Google Home Developer Console.

Next steps

In this codelab, you created a very simple automation. Automations can do much more than schedule the toggling of a light. Now that you understand the basics of creating and testing an automation template, you can try creating automation templates other types of devices, using different starters, conditions, and actions.