We want to hear your thoughts on the Google Smart Home platform. Join a user study and receive a gift for your input. Click here to sign up.

Smart Home Modes Trait Schema

action.devices.traits.Modes - This trait covers all available modes and mode-specific settings for a device.

This trait belongs to any devices with an arbitrary number of "n-way" modes in which the modes and settings for each mode are arbitrary and unique to each device or device type. Each mode has multiple possible settings, but only one can be selected at a time; a dryer cannot be in "delicate," "normal," and "heavy duty" mode simultaneously. A setting that simply can be turned on or off belongs in the Toggles trait.

For instance, a washing machine can have settings for load size and temperature. These would both be modes because they are independent of each other, but each can be in only one state at a time. The user can set a mode such as temperature explicitly with a command like Set the washer’s temperature to cold.

Some modes are "ordered" and can also be adjusted with up/down, increase/decrease verbiage. For example, load size (small, medium, large) and temperature are clearly ordered (note that temperature is not an actual thermostat with a numeric target, as on other devices), but load type (delicates, normal, wool, etc) may not be.

This trait covers one or more individual modes which users can set. In general, these modes should be used for functionality that is unlinked from other device behavior. Linked behavior, such as turning the device itself on or off, should use more specific traits (for example, the thermostatMode in the trait TemperatureSetting).

Device ATTRIBUTES

Devices with this trait may report the following attributes as part of the SYNC operation. To learn more about handling SYNC intents, see Intent fulfillment.

Attributes Type Description
availableModes Array <Object>

Properties:

name String

Internal name of the mode, which will be used in commands and states. This can be non-user-friendly, and will be shared across all languages.

name_values Array <Object>

Synonyms of the mode in each supported languages.

Properties:

Synonyms of the mode in a given language.

name_synonym Array <String>

Synonyms of the mode. The first string in this list is used as the canonical name of the level in that language.

Synonym name.

lang String

Language code (ISO 639-1). See supported languages.

Required:

  • lang
  • name_synonym
settings Array <Object>

Supported settings for this mode.

Properties:

Supported setting.

setting_name String

Internal name of the mode setting, which will be used in commands and states. This can be non-user-friendly, and will be shared across all languages.

setting_values Array <Object>

Synonyms of the setting in each supported languages.

Properties:

Synonyms of the setting in a given language.

setting_synonym Array <String>

Synonyms of the setting. The first string in this list is used as the canonical name of the level in that language.

Synonym name.

lang String

Language code (ISO 639-1). See supported languages.

Required:

  • lang
  • setting_synonym

Required:

  • setting_name
  • setting_values
ordered Boolean

(Default: false)

If this is set to true, additional grammar for increase/decrease logic will apply, in the order (increasing) of the settings array.

Required:

  • name
  • name_values
  • settings
commandOnlyModes Boolean

(Default: false)

Indicates if the device supports using one-way (true) or two-way (false) communication. Set this attribute to true if the device cannot respond to a QUERY intent or Report State for this trait.

queryOnlyModes Boolean

(Default: false)

Required if the device supports query-only execution. This attribute indicates if the device can only be queried for state information, and cannot be controlled.

Required:

  • availableModes
Examples

Device with multiple mode and settings.

{
  "availableModes": [
    {
      "name": "load_mode",
      "name_values": [
        {
          "name_synonym": [
            "load",
            "size",
            "load size"
          ],
          "lang": "en"
        }
      ],
      "settings": [
        {
          "setting_name": "small_load",
          "setting_values": [
            {
              "setting_synonym": [
                "small",
                "half"
              ],
              "lang": "en"
            }
          ]
        },
        {
          "setting_name": "medium_load",
          "setting_values": [
            {
              "setting_synonym": [
                "medium",
                "normal"
              ],
              "lang": "en"
            }
          ]
        },
        {
          "setting_name": "large_load",
          "setting_values": [
            {
              "setting_synonym": [
                "large",
                "full"
              ],
              "lang": "en"
            }
          ]
        }
      ],
      "ordered": true
    },
    {
      "name": "temp_mode",
      "name_values": [
        {
          "name_synonym": [
            "temperature",
            "temp"
          ],
          "lang": "en"
        }
      ],
      "settings": [
        {
          "setting_name": "hot_temp",
          "setting_values": [
            {
              "setting_synonym": [
                "hot",
                "white"
              ],
              "lang": "en"
            }
          ]
        },
        {
          "setting_name": "warm_temp",
          "setting_values": [
            {
              "setting_synonym": [
                "warm",
                "color"
              ],
              "lang": "en"
            }
          ]
        },
        {
          "setting_name": "cold_temp",
          "setting_values": [
            {
              "setting_synonym": [
                "cold",
                "delicate"
              ],
              "lang": "en"
            }
          ]
        }
      ],
      "ordered": false
    }
  ]
}

Device with command-only modes.

{
  "availableModes": [
    {
      "name": "light_mode",
      "name_values": [
        {
          "name_synonym": [
            "light",
            "lighting"
          ],
          "lang": "en"
        }
      ],
      "settings": [
        {
          "setting_name": "day_light",
          "setting_values": [
            {
              "setting_synonym": [
                "day",
                "bright"
              ],
              "lang": "en"
            }
          ]
        },
        {
          "setting_name": "night_light",
          "setting_values": [
            {
              "setting_synonym": [
                "night",
                "dark"
              ],
              "lang": "en"
            }
          ]
        },
        {
          "setting_name": "reading_light",
          "setting_values": [
            {
              "setting_synonym": [
                "reading",
                "ambiant"
              ],
              "lang": "en"
            }
          ]
        }
      ],
      "ordered": false
    }
  ],
  "commandOnlyModes": true,
  "queryOnlyModes": false
}

Sample SYNC Request and Response

Request
{
    "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "inputs": [{
      "intent": "action.devices.SYNC"
    }]
}
Node.js
'use strict';

const {smarthome} = require('actions-on-google');
const functions = require('firebase-functions');

const app = smarthome();

app.onSync((body, headers) => {
  return {
    requestId: body.requestId,
    payload: {
      agentUserId: '1836.15267389',
      devices: [{
        id: '123',
        type: 'action.devices.types.WASHER',
        traits: [
          'action.devices.traits.Modes'
        ],
        name: {
          defaultNames: ['AAA Cybernetics Corporation Washer 3421'],
          name: 'Washer',
          nicknames: ['clothes washer']
        },
        willReportState: true,
        attributes: {
          availableModes: [{
            name: 'load',
            name_values: [{
              name_synonym: ['load', 'size', 'load size'],
              lang: 'en'
            }],
            settings: [{
              setting_name: 'small',
              setting_values: [{
                setting_synonym: ['small', 'half'],
                lang: 'en'
              }]
            }, {
              setting_name: 'large',
              setting_values: [{
                setting_synonym: ['large', 'full'],
                lang: 'en'
              }]
            }],
            ordered: true
          }]
        },
        deviceInfo: {
          manufacturer: 'AAA Cybernetics Corporation',
          model: '233451',
          hwVersion: '3.2',
          swVersion: '11.4'
        },
        customData: {
          fooValue: 74,
          barValue: true,
          bazValue: 'lambtwirl'
        }
      }]
    }
  };
});

// ...

exports.smarthome = functions.https.onRequest(app);
Java
@NotNull
@Override
public SyncResponse onSync(@NotNull SyncRequest syncRequest, @Nullable Map<?, ?> headers) {
  Payload payload = new Payload();
  payload.setAgentUserId("1836.15267389");
  payload.setDevices(
      new SyncResponse.Payload.Device[] {
        new SyncResponse.Payload.Device.Builder()
            .setId("123")
            .setType("action.devices.types.WASHER")
            .addTrait("action.devices.traits.Modes")
            .setName(
                Collections.singletonList("AAA Cybernetics Corp Washer 3421"),
                "Washer",
                Collections.singletonList("clothes washer"))
            .setWillReportState(true)
            .setAttributes(
                new JSONObject()
                    .put(
                        "availableModes",
                        new JSONObject[] {
                          new JSONObject()
                              .put("name", "load")
                              .put(
                                  "name_values",
                                  new JSONObject[] {
                                    new JSONObject()
                                        .put(
                                            "name_synonym",
                                            new String[] {"load", "size", "load size"})
                                        .put("lang", "en")
                                  })
                              .put(
                                  "settings",
                                  new JSONObject[] {
                                    new JSONObject()
                                        .put("setting_name", "small")
                                        .put(
                                            "setting_values",
                                            new JSONObject[] {
                                              new JSONObject()
                                                  .put(
                                                      "setting_synonym",
                                                      new String[] {"small", "half"})
                                                  .put("lang", "en")
                                            }),
                                    new JSONObject()
                                        .put("setting_name", "large")
                                        .put(
                                            "setting_values",
                                            new JSONObject[] {
                                              new JSONObject()
                                                  .put(
                                                      "setting_synonym",
                                                      new String[] {"large", "full"})
                                                  .put("lang", "en")
                                            })
                                  })
                              .put("ordered", true)
                        }))
            .setDeviceInfo("AAA Cybernetics Corporation", "233451", "3.2", "11.4")
            .setCustomData(
                new JSONObject()
                    .put("fooValue", 74)
                    .put("barValue", true)
                    .put("bazValue", "lambtwirl")
                    .toString())
            .build()
      });
  return new SyncResponse(syncRequest.getRequestId(), payload);
}
JSON
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "agentUserId": "1836.15267389",
    "devices": [
      {
        "id": "123",
        "type": "action.devices.types.WASHER",
        "traits": [
          "action.devices.traits.Modes"
        ],
        "name": {
          "defaultNames": [
            "AAA Cybernetics Corporation Washer 3421"
          ],
          "name": "Washer",
          "nicknames": [
            "clothes washer"
          ]
        },
        "willReportState": true,
        "attributes": {
          "availableModes": [
            {
              "name": "load",
              "name_values": [
                {
                  "name_synonym": [
                    "load",
                    "size",
                    "load size"
                  ],
                  "lang": "en"
                }
              ],
              "settings": [
                {
                  "setting_name": "small",
                  "setting_values": [
                    {
                      "setting_synonym": [
                        "small",
                        "half"
                      ],
                      "lang": "en"
                    }
                  ]
                },
                {
                  "setting_name": "large",
                  "setting_values": [
                    {
                      "setting_synonym": [
                        "large",
                        "full"
                      ],
                      "lang": "en"
                    }
                  ]
                }
              ],
              "ordered": true
            }
          ]
        },
        "deviceInfo": {
          "manufacturer": "AAA Cybernetics Corporation",
          "model": "233451",
          "hwVersion": "3.2",
          "swVersion": "11.4"
        },
        "customData": {
          "fooValue": 74,
          "barValue": true,
          "bazValue": "lambtwirl"
        }
      }
    ]
  }
}
Validator

Device STATES

Devices with this trait may report the following states as part of the QUERY operation. To learn more about handling QUERY intents, see Intent fulfillment.

States Type Description
currentModeSettings Object

Key/value pair with the mode name of the device as the key, and the current setting_name as the value.

No properties.

Required:

  • currentModeSettings
Examples

What mode is the device in?

{
  "currentModeSettings": {
    "load_mode": "small_load",
    "temp_mode": "cold_temp"
  }
}

Sample QUERY Request and Response

User What mode is the dryer in?
Google Assistant The dryer is in permanent press mode.
Request
{
    "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "inputs": [{
      "intent": "action.devices.QUERY",
      "payload": {
        "devices": [{
          "id": "123",
          "customData": {
            "fooValue": 74,
            "barValue": true,
            "bazValue": "foo"
          }
        }, {
          "id": "456",
          "customData": {
            "fooValue": 12,
            "barValue": false,
            "bazValue": "bar"
          }
        }]
      }
    }]
}
Node.js
'use strict';

const {smarthome} = require('actions-on-google');
const functions = require('firebase-functions');

const app = smarthome();

app.onQuery((body, headers) => {
  return {
    requestId: body.requestId,
    payload: {
      devices: {
        123: {
          on: true,
          online: true,
          currentModeSettings: {
            drytype: 'permpress',
            load: 'large'
          },
          status: 'SUCCESS'
        },
        456: {
          on: true,
          online: true,
          isPaused: true,
          isRunning: false,
          currentModeSettings: {
            temperature: 'hot',
            load: 'large'
          },
          status: 'SUCCESS'
        }
      }
    }
  };
});

// ...

exports.smarthome = functions.https.onRequest(app);
Java
@NotNull
@Override
public QueryResponse onQuery(@NotNull QueryRequest queryRequest, @Nullable Map<?, ?> map) {
  QueryResponse.Payload payload = new QueryResponse.Payload();
  payload.setDevices(
      new HashMap<String, Map<String, Object>>() {
        {
          put(
              "123",
              new HashMap<String, Object>() {
                {
                  put("on", true);
                  put("online", true);
                  put(
                      "currentModeSettings",
                      new HashMap<String, Object>() {
                        {
                          put("drytype", "permpress");
                          put("load", "large");
                        }
                      });
                  put("status", "SUCCESS");
                }
              });
          put(
              "456",
              new HashMap<String, Object>() {
                {
                  put("on", true);
                  put("online", true);
                  put("isPaused", true);
                  put("isRunning", false);
                  put(
                      "currentModeSettings",
                      new HashMap<String, Object>() {
                        {
                          put("temperature", "hot");
                          put("load", "large");
                        }
                      });
                  put("status", "SUCCESS");
                }
              });
        }
      });

  return new QueryResponse(queryRequest.getRequestId(), payload);
}
JSON
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "devices": {
      "123": {
        "on": true,
        "online": true,
        "currentModeSettings": {
          "drytype": "permpress",
          "load": "large"
        },
        "status": "SUCCESS"
      },
      "456": {
        "on": true,
        "online": true,
        "isPaused": true,
        "isRunning": false,
        "currentModeSettings": {
          "temperature": "hot",
          "load": "large"
        },
        "status": "SUCCESS"
      }
    }
  }
}

Device COMMANDS

Devices with this trait may respond to the following commands as part of the EXECUTE operation. To learn more about handling EXECUTE intents, see Intent fulfillment.

action.devices.commands.SetModes

Parameters

Parameters Type Description
updateModeSettings Object

Key/value pair with the mode name of the device as the key, and the new setting_name as the value.

No properties.

Required:

  • updateModeSettings
Examples

Set to large load.

{
  "updateModeSettings": {
    "load_mode": "large_load"
  }
}

Sample EXECUTE Request and Response

Set modes example

User Set the dryer to permanent press.
Google Assistant Sure, setting the dryer to permanent press.
Request
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123",
          "customData": {
            "fooValue": 74,
            "barValue": true,
            "bazValue": "lambtwirl"
          }
        }],
        "execution": [{
          "command": "action.devices.commands.SetModes",
          "params": {
            "updateModeSettings": {
              "drytype": "permpress"
            }
          }
        }]
      }]
    }
  }]
}
Node.js
'use strict';

const {smarthome} = require('actions-on-google');
const functions = require('firebase-functions');

const app = smarthome();

app.onExecute((body, headers) => {
  return {
    requestId: body.requestId,
    payload: {
      commands: [{
        ids: ['123'],
        status: 'SUCCESS',
        states: {
           currentModeSettings: {
             drytype: 'permpress',
             load: 'large'
           }
        }
      }]
    }
  };
});

// ...

exports.smarthome = functions.https.onRequest(app);
Java
@NotNull
@Override
public ExecuteResponse onExecute(
    @NotNull ExecuteRequest executeRequest, @Nullable Map<?, ?> map) {
  ExecuteResponse.Payload payload = new ExecuteResponse.Payload();

  payload.setCommands(
      new Commands[] {
        new Commands(
            new String[] {"123"},
            "SUCCESS",
            new HashMap<String, Object>() {
              {
                put(
                    "currentModeSettings",
                    new HashMap<String, Object>() {
                      {
                        put("drytype", "permpress");
                        put("load", "large");
                      }
                    });
              }
            },
            null,
            null)
      });
  return new ExecuteResponse(executeRequest.getRequestId(), payload);
}
JSON
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "123"
        ],
        "status": "SUCCESS",
        "states": {
          "currentModeSettings": {
            "drytype": "permpress",
            "load": "large"
          }
        }
      }
    ]
  }
}

Device ERRORS

See the full list of errors and exceptions.