Nick Felker
Nov 27, 2018 · 3 min read
Structures, rooms, and devices are represented in the home graph

If you have built a smart home Action for the Google Assistant, you may be familiar with the various traits, which define the set of capabilities your device can have. Your device may be able to turn on and off, change color, or have different speeds. At the same time, your device may have more advanced capabilities that can’t be defined by one of these traits.

To integrate these features with the Google Assistant, you can instead look at using the mode or toggle traits. They are very similar, as both are defined in key-value pairs.

Modes

A mode trait represents a parameter of the device that can be assigned to one of many settings. The settings for a mode can be ordered or unordered. For example, a washer can have a load of small, medium, or large, which has some incremental order. An oven may have settings which are unordered, such as bake, roast, or broil.

Each mode can only have one setting at a given time, and mode should always be assigned to one of these settings.

In your SYNC response, you can return the list of supported modes, as well as the settings that are available for the given mode. To see the available modes, you can consult this reference page, which shows the keys and synonyms.

In the example below, the washer has a single mode, called load, but it can also be called size or load size. The mode can have a setting of small or large. To change the setting, you can just say “Set the load to small on the washing machine”. You can see the entire response below:

Toggles

Toggles are similar to modes, except that, instead of a mode having one of multiple string values, a toggle will have a boolean value. This may be useful if your device has many settings that can be turned on or off, such as a night mode or quiet mode.

Each toggle should be considered independent of other toggles. For example, the night mode should not be affected by quiet mode, and vice versa. Each toggle must be either on or off and not in some intermediary state.

Just like with modes, all of the supported toggles can be returned in your SYNC response. This reference page shows all of the supported toggle names.

In the example below, the camera has two toggles. The first is called night. The second is called recording, but can also be called monitoring. To turn on one of the toggles, you can just say “Turn on recording for the front camera”. You can see the entire response below:

As you’re developing your Action, you may find it useful to use a combination of both modes and toggles. This will give users the flexibility they need to control your device through the Google Assistant.

Handling execute intents

When the user says “Set the load to small on the washing machine” or “Turn on recording on the camera”, your server will receive an EXECUTE intent with the modified mode settings or toggles listed in the updateModeSettings or updateToggleSettings object, as shown below:

New modes and toggles

The reference documentation for modes and toggles shows the full list of names that you can use. If you want a new item added to the list, you can file a feature request at the public issue tracker. Include the modes, mode settings, or toggles in the issue description. If your request is approved by Google, they will be added after a few days, allowing you to iterate quickly.

Learning more

These two traits can provide developers with a lot of flexibility in controlling their devices from the Google Assistant. To learn more about these traits and everything else about smart home, you can get started with this smart home codelab or visit our developer documentation.

What kinds of smart home Actions are you building? Tweet out your project with #AoGDevs to share it with the community.

Google Developers

Engineering and technology articles for developers, written and curated by Googlers. The views expressed are those of the authors and don't necessarily reflect those of Google.

Nick Felker

Written by

Social Media Expert -- Rowan University 2017 -- IoT & Assistant @ Google

Google Developers

Engineering and technology articles for developers, written and curated by Googlers. The views expressed are those of the authors and don't necessarily reflect those of Google.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade