Join the Actions on Google Developer Challenge to win a trip to Google I/O 2018 and more than 20 other prizes.

Smart Home Scene Schema

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"

Naming

Scenes should always have userprovided names, vs default 'BobCo Scene' naming. Each scene is its own virtual device, with its own name(s). Userprovided names may come in from SYNC.

Device TYPE

action.devices.types.SCENE - In the case of scenes, the type maps 1:1 to the trait, as scenes don't combine with other traits to form composite devices.

Device TRAITS

action.devices.traits.Scene

Device ATTRIBUTES

Devices with traits Scene may report the following attribute as part of SYNC:

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.

SYNC Sample

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"
      }
    }]
  }
}

Device STATES

QUERY Sample

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 // n.b. scenes can be online -- sc. available -- if their hub or devices are.
    }
  }
}

Device COMMANDS

Command Properties/Definition
action.devices.commands.ActivateScene deactivate: boolean (true if scene is reversible and should be reversed).

EXECUTE Sample

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