Create a scripted automation

1. Introduction

What you'll learn

• How to plan and write a scripted automation.
• How to test a scripted automation.

What you'll need

• An Android or iOS phone running the Google Home app.
• A smart light or other device that is certified for Works With Google Home and can be turned on or off.

2. Set up your device

If your device is not already set up, go ahead and set it up in your home.

Confirm that the device appears in the Google Home app, and that you can turn it on and off using the Home app.

3. Plan your scripted automation

We'll start by thinking about what we want our scripted automation to do. This includes such considerations as:

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

For purpose of this codelab, our plan is to have the scripted automation do two things:

1. Turn on your light (or other smart device) at a specific time.
2. Turn off your device at a specific time.

Now that we are clear about exactly what we want our scripted automation to do, we will open the script editor and write the scripted automation.

4. Write the scripted automation

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

A scripted automation is composed of two primary sections:

1. Metadata - The name of the scripted automation and a description of what it does.
2. Automation rules — Defines the initiation logic and behavior of the automation.

Metadata

Our automation's metadata tells the user what the automation is called and what it does. Metadata is specified in the metadata block, which looks like this:

metadata:
  name: Scheduled light
  description: Turn the light on and off at specific times

Automation rules

An automation rule is where the real work takes place. It consists of three parts, starters, conditions, and actions, which are evaluated in order:

The automations block of our automation contains two rules:

automations:
  - starters:
      - type: time.schedule
        at: 1:00 PM
    actions:
      - type: device.command.OnOff
        devices: Desk light - Office
        on: true
  - starters:
      - type: time.schedule
        at: 1:05 PM
    actions:
      - type: device.command.OnOff
        devices: Desk light - Office
        on: false

Note the following:

1. There are two automations rules. The first turns on the light, and the second turns off the light.
2. Each rule has a single action.
3. on: true means turn the light on. Similarly, on: false means turn the light off.
4. Each rule has a single time.schedule starter that tells the automation what time to initiate the automation.
5. There are no conditions in this automation.

5. The full scripted automation

Putting all these pieces together, here's what the complete scripted automation looks like:

metadata:
  name: Scheduled light
  description: Turn the light on and off at specific times
automations:
  - starters:
      - type: time.schedule
        at: 1:00 PM
    actions:
      - type: device.command.OnOff
        devices: Desk light - Office
        on: true
  - starters:
      - type: time.schedule
        at: 1:05 PM
    actions:
      - type: device.command.OnOff
        devices: Desk light - Office
        on: false

1. Copy the automation (above).
2. Go to Google Home for web.
3. Select the automations tab, represented by an icon with three stars:
   
4. Click + Add new.
5. In the script editor, delete the automation template.
6. Paste your automation.
7. Replace Desk light - Office with the name and location of your device.
8. Click Validate. The script editor underlines sections of your scripted automation that contain errors. Resolve any errors that arise and keep validating and fixing until there are no more errors. For example, your device name may be different. If that's the case, you can use the autocomplete feature to pick a valid device name.
9. Click Save.
10. Make sure the Activate switch, beneath the text of your script, is in the on position:

6. Test the automation

1. Make sure your device is plugged in and visible in the Google Home app.
2. If the device is currently on, turn it off.
3. On the Automations page in the Google Home for web, click the ‘run' button next to your automation.
   
4. The device should come on.

Now, let's test the automation.

1. Turn off the device.
2. Edit the automation, and change the ‘device on' time on line 7 to a time five minutes in the future.
3. Change the ‘device off' time on line 14 to a time shortly after the ‘on time'.
4. Click Validate. Resolve any errors that may come up.
5. Click Save.
6. Make sure the Activate switch is in the on position.
7. Wait for the two starter times to pass. The device should come on and then go off at the times you specified.

7. Congratulations!

You've successfully created a scripted automation - awesome!

In this codelab you learned how to:

• How to design and write an automation.
• How to test an automation.

Next steps

In this codelab, we created a very simple automation. Automations can do much more than schedule the toggling of a power switch. Now that you understand the basics of creating an automation, you can explore the various types of starters, conditions, and actions that are available in the Google Home ecosystem.

Try the following exercises:

• Add more time.schedule starters to the automation.
• Modify the automation to turn another device on and off on the same schedule.
• Without removing the time.schedule starters, modify the automation to only turn on the devices when another device is powered on. Refer to the example scripts that use the condition clause.
• Modify the automation to only turn on the devices when someone is home.

Further reading

To learn more about Google Home automations, explore the Automations reference documentation:

• Quick start
• Supported starters, conditions and actions