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. In other words, this trait covers all available custom binary settings on a device.

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 Modes 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

Attribute Definition
availableToggles Contains the following:
  • 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. Currently, you must submit names to us so we can add support for them.
  • name_values Contains names and supported languages:
    • name_synonym Strings. User-friendly names for the toggle, in each language supported; the first name will be used in TTS as needed. Currently, you must submit name synonyms to us so we can add support for them.
    • lang String. Supported language for the names. Acceptable language codes are en (English), de (German), and fr (French).
The following is an example for a refrigerator:
"availableToggles": [{
    "name": "powercool",
    "name_values": [ {  "name_synonym": [ "powercool", "power cool", ... ],
          "lang": "en"  }, … ]
  },
  {
    "name": "quiet",
    "name_values": [ {  "name_synonym": [ "quiet", "silent", ...  ],
          "lang": "en"  }, … ]
  }
]

Sample SYNC Request and Response

Request
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.SYNC",
  }]
}
Response
{
  "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": "Washer",
        "nicknames": ["clothes dryer"]
      },
      "willReportState": true,
      "attributes": {
          "availableToggles": [{
              "name": "sterilization",
              "name_values": [ {  "name_synonym": [ "bio-clean", "ultrasound"],
              "lang": "en"  }]
            },
            {
              "name":  "energysaving",
              "name_values": [ {  "name_synonym": [ "normal", "medium", "high"],
              "lang": "en"  }]
            }]
      },
      "deviceInfo": {
        "manufacturer": "AAA Corporation",
        "model": "492134",
        "hwVersion": "3.2",
        "swVersion": "11.4"
      },
      "customData": {
        "fooValue": 74,
        "barValue": true,
        "bazValue": "lambtwirl"
      }
    }]
  }
}
Validator

Device STATES

State Definition
currentToggleSettings Array of objects containing one element for each toggle defined on the object, as a boolean. One object per language. For example:
"currentToggleSettings": {
     "sterilization": true,
     "energysaving": false
}

Sample QUERY Request and Response

Is my dryer sterilization on?
Request
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.QUERY",
    "payload": {
      "devices": [{
        "id": "123",
        "customData": {
          "fooValue": 74,
          "barValue": true,
          "bazValue": "lambtwirl"
        }
      }]
    }
  }]
}
Response
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "devices": {
      "123": {
        "on": true,
        "online": true
        "currentToggleSettings": {
          "sterilization ": true
        }
      },
      "456": {
        "on": true,
        "online": true,
        "currentToggleSettings": {
          "sterilization ": false
        }
      }
    }
  }
}

Device COMMANDS

Command Parameters/Definition
action.devices.commands.SetToggles updateToggleSettings Object containing the new boolean value for each toggle that's being set.

Sample EXECUTE Request and Response

Turn on sterilization for the 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
            }
          }
        }]
      }]
    }
  }]
}
Response
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "SUCCESS",
      "states": {
         "currentToggleSettings": [{
           "sterilization ": true,
           "energysaving": false,
           "lang":"en"
         }]
      }
    }]
  }
}