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

Smart Home Light Schema

Device TYPE

action.devices.types.LIGHT - This type indicates that the device gets the light bulb icon and some light synonyms/aliases.

action.devices.types.OUTLET - This type indicates that the device gets the plug icon and some outlet synonyms/aliases.

action.devices.types.SWITCH - This type indicates that the device gets the switch icon and some switch synonyms/aliases.

Device TRAITS

Trait Description
action.devices.traits.OnOff The basic on and off functionality, for lights but also for any device that has binary on and off, including plugs and switches as well as many future devices. Note that thermostats have an expanded 'mode' setting, which is a multi­way switch that includes on and off, but thermostats generally will not have this trait.
action.devices.traits.Brightness Absolute brightness setting in a normalized range from 0 to 100 (individual lights may not support every point in the range, based on their LED configuration).
action.devices.traits.ColorSpectrum 'Full' color bulbs that take RGB color ranges. Lights may have any combination of ColorSpectrum and ColorTemperature; accent lights and LED strips may just have Spectrum, whereas some reading bulbs just have Temperature. Basic bulbs, or dumb lights on smart plugs, have neither.
action.devices.traits.ColorTemperature 'Warmth' bulbs that take a color point in Kelvin. This is generally a separate modality from ColorSpectrum, and there may be white points available via Temperature that cannot be reached by Spectrum. Based on available traits, Google may pick the appropriate mode to use based on request and light type (e.g. 'make the living room lights white' might sent Temperature commands to some bulbs and Spectrum commands to LED strips.
  • TemperatureMinK
  • TemperatureMaxK

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.LIGHT",
            "traits": [
                "action.devices.traits.OnOff",
                "action.devices.traits.Brightness",
                "action.devices.traits.ColorTemperature",
                "action.devices.traits.ColorSpectrum"
            ],
            "name": {
                "defaultNames": ["OSRAM bulb A19 color hyperglow"],
                "name": "lamp1",
                "nicknames": ["reading lamp"]
            },
            "willReportState: false,
            "attributes": {
                "TemperatureMinK": 2000,
                "TemperatureMaxK": 6500
            },
            "roomHint": "living room",
            "config": {
                "manufacturer": "osram",
                "model": "hg11",
                "hwVersion": "1.2",
                "swVersion": "5.4"
            },
            "customData": {
                "fooValue": 12,
                "barValue": false,
                "bazValue": "dancing alpaca"
            }
        }]
    }
}

Device STATES

online boolean. Whether the device is connected to the partner cloud and believed to be reachable. A device would be offline if its hub is unreachable (if a hub system), or if the device is no longer connected to the partner cloud. Common reasons would be last-mile issues or a device powered off by a dumb wall switch.
on Boolean. Whether a device with an on/off switch is on.
brightness Integer. Current brightness level. Ideally this is the number that was set, vs the rounded point (e.g. if the user sets to 65%, but the device has to round to 10% increments, ideally this would still return 65%).
color Object. Current color setting. Since a given light is in spectrum OR temperature mode, this object includes the current color settings in the relevant mode.
  • name - String. If the color point (Spectrum or Temperature) matches a preset name on the partner's color list, return the name.
  • temperature - Integer. Color temp in Kelvin.
  • spectrumRGB - Integer. Spectrum value in RGB (hex value as integer).

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": {
            "123": {
                "online": true,
                "on": false,
                "brightness": 65
                "color": {
                    "name": "lamp1",
                    "temperature": 2000,
                    "spectrumRGB": 16510692
                }
            }
        }
    }
}

Device COMMANDS

Command Properties/Definition
action.devices.commands.OnOff on boolean. Required. Whether to turn the device on or off.
action.devices.commands.BrightnessAbsolute brightness integer. Required. New absolute brightness, from 0 to 100.
action.devices.commands.ColorAbsolute color object. Required. Will include RGB or Temperature and optionally name.
  • name String. Color name (in English) as provided in the user's command. Not always available (for relative commands).
  • temperature Integer. Color temp in Kelvin.
  • spectrumRGB Integer. Spectrum value in RGB (hex value as integer).

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.OnOff",
                    "params": {
                        "on": true
                    }
                }]
            }]
        }
    }]
}
Response
{
    "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "payload": {
        "commands": [{
            "ids": ["123"],
            "status": "SUCCESS"
            "states": {
                "on": true,
                "online": true
            }
        }]
    }
}