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 namedthe_light
which specifies a device of typeLIGHT
. 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 namedtime_on
andtime_off
. These allow the user to specify when to start the automations.time_on
represents the time that the light is turned on, andtime_off
represents the time that the light is turned off. If the user does not set the value oftime_on
ortime_off
, the default values are used. - The
automations
section of our automation contains two automation rules. Each rule has a singletime.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 oflights
. 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 thetime_off
time to a time shortly after thetime_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.
Further reading
To learn more about Google Home automations, explore the Automations reference documentation: