Smart Home Scene Trait Schema

action.devices.traits.Scene - Scenes for the purpose of this document are partner scenes, implemented as virtual devices and activated by name. For example, if a partner allows users to configure one-touch grouping of commands — setting lights to specific colors, or sequencing various security features, or any other combination of activities — this configuration can be exposed through SYNC as a named scene, and the Assistant will make these scenes available to users through simple activation grammar:

  • Start Party Mode.
  • Activate midnight scene.

As virtual objects, scenes can be placed in rooms (if relevant) for disambiguation:

  • Start party time in the kitchen.
  • Activate nightlight mode in the bedrooms.

One difference between scenes and physical targets is that the Assistant will automatically apply plural effects to Scene commands, allowing users to trigger scenes across multiple partners. For example, if a user has a "party mode" scene on two different partners, one for security and one for lights, Activate party mode will trigger both.

Scenes will interact well with upcoming Personal Actions for custom grammar (for example, Activate Party Mode -> Let's get the party started!).

Scenes should always have user-provided names versus default "BobCo Scene" naming. Each scene is its own virtual device, with its own name(s). User-provided names may come in from SYNC.

Device ATTRIBUTES

Attribute Definition
sceneReversible Boolean, indicating that this scene may be reversed. This is only relevant for scenes that modify state and remember previous state. Obviously, scenes that fire specific actions may not be reversible — the bell cannot be unrung. If true, Deactivate Party Mode will function as expected.

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.SCENE",
      "traits": [
        "action.devices.traits.Scene"
      ],
      "name": {
        "defaultNames": [],
        "name": "Party Mode",
        "nicknames": []
      },
      "willReportState": false,     // should be false, as there's no state
      "attributes": {
        "sceneReversible": true
      },
      // Note -- probably no device info for virtual devices.
      "customData": {
        "fooValue": 74,
        "barValue": true,
        "bazValue": "lambtwirl"
      }
    }]
  }
}
Validator

Device STATES

None

Sample QUERY Request and Response

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": {
      "online": true
    }
  }
}

Device COMMANDS

Command Parameters/Definition
action.devices.commands.ActivateScene deactivate Boolean. True if scene is reversible and should be reversed.

Sample EXECUTE Request and Response

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.ActivateScene",
          "params": {
            "deactivate": false
          }
        }]
      }]
    }
  }]
}
Response
{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "SUCCESS",
      "states": {
          // Note -- scenes are stateless.
      }
    }]
  }
}