Extending your smart home Actions with toggles and modes
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.
