Smart Home Toggles Trait Schema

action.devices.traits.Toggles - This trait belongs to any devices with settings that can only exist in one of two states.

This trait belongs to any devices with settings that can only exist in one of two states. These settings can represent a physical button with an on/off or active/inactive state, a checkbox in HTML, or any other sort of specifically enabled/disabled element.

These settings can represent a physical button with an on/off or active/inactive state, a checkbox in HTML, or any other sort of specifically enabled/disabled element. If the setting has more than two states, or has a state in which neither of the binary options is selected, it is better represented as a Toggles trait, which equates to multi-state dials, radio buttons (physical or HTML), or binary states that are not explicitly on/off (for example, "AM/FM" or "hot/cold").

This trait covers one or more individual toggles which users can set. In general, these toggles 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
availableToggles Array <Object>

List of available toggles.

Properties:

Available toggle.

name String

Internal name of the toggle, 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 toggle in each supported languages.

Properties:

Synonyms of the toggle in a given language.

name_synonym Array <String>

Synonyms of the toggle. 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

Required:

  • name
  • name_values
commandOnlyToggles 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.

queryOnlyToggles 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:

  • availableToggles
Examples

Device with multiple toggle.

{
  "availableToggles": [
    {
      "name": "sterilization_toggle",
      "name_values": [
        {
          "name_synonym": [
            "clean",
            "bio clean"
          ],
          "lang": "en"
        }
      ]
    },
    {
      "name": "energysaving_toggle",
      "name_values": [
        {
          "name_synonym": [
            "energy saving",
            "eco"
          ],
          "lang": "en"
        }
      ]
    }
  ]
}

Device with command-only toggles.

{
  "availableToggles": [
    {
      "name": "filter_toggle",
      "name_values": [
        {
          "name_synonym": [
            "filtered",
            "filter"
          ],
          "lang": "en"
        }
      ]
    }
  ],
  "commandOnlyToggles": true
}

Device with query-only toggles.

{
  "availableToggles": [
    {
      "name": "filter_toggle",
      "name_values": [
        {
          "name_synonym": [
            "filtered",
            "filter"
          ],
          "lang": "en"
        }
      ]
    }
  ],
  "queryOnlyToggles": true
}

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.DRYER',
        traits: [
          'action.devices.traits.Toggles'
        ],
        name: {
          defaultNames: ['AAA Super Dryer'],
          name: 'Dryer',
          nicknames: ['clothes dryer']
        },
        willReportState: true,
        attributes: {
          availableToggles: [{
            name: 'sterilization',
            name_values: [{
              name_synonym: ['clean', 'bio clean', 'ultrasound'],
              lang: 'en'
            }]
          }, {
            name: 'energysaving',
            name_values: [{
              name_synonym: ['energy saving', 'eco'],
              lang: 'en'
            }]
          }]
        },
        deviceInfo: {
          manufacturer: 'AAA Corporation',
          model: '492134',
          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.setAgentUserId("1836.15267389");
  payload.setDevices(
      new SyncResponse.Payload.Device[] {
        new SyncResponse.Payload.Device.Builder()
            .setId("123")
            .setType("action.devices.types.DRYER")
            .addTrait("action.devices.traits.Toggles")
            .setName(
                Collections.singletonList("AAA Super Dryer"),
                "Dryer",
                Collections.singletonList("clothes dryer"))
            .setWillReportState(true)
            .setAttributes(
                new JSONObject()
                    .put(
                        "availableToggles",
                        new JSONObject[] {
                          new JSONObject()
                              .put("name", "Sterilization")
                              .put(
                                  "name_values",
                                  new JSONObject[] {
                                    new JSONObject()
                                        .put(
                                            "name_synonym",
                                            new String[] {"Clean", "Bio Clean", "Ultrasound"})
                                        .put("lang", "en")
                                  }),
                          new JSONObject()
                              .put("name", "Energy Saving")
                              .put(
                                  "name_values",
                                  new JSONObject[] {
                                    new JSONObject()
                                        .put(
                                            "name_synonym", new String[] {"energy saving", "eco"})
                                        .put("lang", "en")
                                  })
                        }))
            .setDeviceInfo("AAA Corporation", "492134", "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.DRYER",
        "traits": [
          "action.devices.traits.Toggles"
        ],
        "name": {
          "defaultNames": [
            "AAA Super Dryer"
          ],
          "name": "Dryer",
          "nicknames": [
            "clothes dryer"
          ]
        },
        "willReportState": true,
        "attributes": {
          "availableToggles": [
            {
              "name": "sterilization",
              "name_values": [
                {
                  "name_synonym": [
                    "clean",
                    "bio clean",
                    "ultrasound"
                  ],
                  "lang": "en"
                }
              ]
            },
            {
              "name": "energysaving",
              "name_values": [
                {
                  "name_synonym": [
                    "energy saving",
                    "eco"
                  ],
                  "lang": "en"
                }
              ]
            }
          ]
        },
        "deviceInfo": {
          "manufacturer": "AAA Corporation",
          "model": "492134",
          "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
currentToggleSettings Object

Key/value pair with the toggle name of the device as the key, and the current state as the value.

No properties.

Required:

  • currentToggleSettings
Examples

Is sterilization on?

{
  "currentToggleSettings": {
    "sterilization_toggle": true,
    "energysaving_toggle": false
  }
}

Sample QUERY Request and Response

User Is my dryer sterilization on??
Google Assistant The dryer sterilization is on.
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: {
          online: true,
          currentToggleSettings: {
            sterilization: true
          },
          status: 'SUCCESS'
        },
        456: {
          online: true,
          currentToggleSettings: {
            sterilization: false
          },
          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("online", true);
                  put(
                      "currentToggleSettings",
                      new HashMap<String, Object>() {
                        {
                          put("sterilization", true);
                        }
                      });
                  put("status", "SUCCESS");
                }
              });
          put(
              "456",
              new HashMap<String, Object>() {
                {
                  put("online", true);
                  put(
                      "currentToggleSettings",
                      new HashMap<String, Object>() {
                        {
                          put("sterilization", false);
                        }
                      });
                  put("status", "SUCCESS");
                }
              });
        }
      });

  return new QueryResponse(queryRequest.getRequestId(), payload);
}
JSON
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "devices": {
      "123": {
        "online": true,
        "currentToggleSettings": {
          "sterilization": true
        },
        "status": "SUCCESS"
      },
      "456": {
        "online": true,
        "currentToggleSettings": {
          "sterilization": false
        },
        "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.SetToggles

Parameters

Set a given toggle state.

Parameters Type Description
updateToggleSettings Object

Key/value pair with the toggle name of the device as the key, and the new state as the value.

No properties.

Required:

  • updateToggleSettings
Examples

Turn on energy saving.

{
  "updateToggleSettings": {
    "energysaving_toggle": true
  }
}

Turn off filter.

{
  "updateToggleSettings": {
    "filter_toggle": false
  }
}

Sample EXECUTE Request and Response

Set toggles example

User Turn on sterilization for the dryer.
Google Assistant Sure, turning on sterilization for dryer.
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.SetToggles",
          "params": {
            "updateToggleSettings": {
              "sterilization": true
            }
          }
        }]
      }]
    }
  }]
}
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: {
           currentToggleSettings: {
             sterilization: true,
             energysaving: false
           }
        }
      }]
    }
  };
});

// ...

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(
                    "currentToggleSettings",
                    new HashMap<String, Object>() {
                      {
                        put("sterilization", true);
                        put("energysaving", false);
                      }
                    });
              }
            },
            null,
            null)
      });
  return new ExecuteResponse(executeRequest.getRequestId(), payload);
}
JSON
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [
      {
        "ids": [
          "123"
        ],
        "status": "SUCCESS",
        "states": {
          "currentToggleSettings": {
            "sterilization": true,
            "energysaving": false
          }
        }
      }
    ]
  }
}

Device ERRORS

See the full list of errors and exceptions.