Smart Home Light Guide

action.devices.types.LIGHT - Light devices can be turned on and off. They may have additional features, such as dimming and the ability to change color.

This type indicates that the device gets the Light icon and some related synonyms and aliases.

Device capabilities

Refer to the corresponding trait documentation for implementation details, such as attributes and states that your service should support, and how to build EXECUTE and QUERY responses.

Required traits

These traits and commands are required, if applicable to your device.

These traits are recommended, if applicable to your device. However, you are free to mix and match from all available traits to best match your existing product functionality.

Quality requirements

  • Latency: must be less than or equal to 700ms.
  • Reliability: must be more than or equal to 97%.

Example device: Simple light

This section contains example intent payloads representing a common "Light" based on the device type and traits above. If you add or remove traits in your implementation, modify your responses accordingly to reflect those changes.

Sample SYNC response

Request
{
  "requestId": "6894439706274654512",
  "inputs": [
    {
      "intent": "action.devices.SYNC"
    }
  ]
}
Response
{
  "requestId": "6894439706274654512",
  "payload": {
    "agentUserId": "user123",
    "devices": [
      {
        "id": "123",
        "type": "action.devices.types.LIGHT",
        "traits": [
          "action.devices.traits.ColorSetting",
          "action.devices.traits.Brightness",
          "action.devices.traits.OnOff"
        ],
        "name": {
          "name": "Simple light"
        },
        "willReportState": true,
        "attributes": {
          "colorTemperatureRange": {
            "temperatureMinK": 2000,
            "temperatureMaxK": 6500
          }
        },
        "deviceInfo": {
          "manufacturer": "smart-home-inc",
          "model": "hs1234",
          "hwVersion": "3.2",
          "swVersion": "11.4"
        }
      }
    ]
  }
}

Sample QUERY response

Request
{
  "requestId": "6894439706274654514",
  "inputs": [
    {
      "intent": "action.devices.QUERY",
      "payload": {
        "devices": [
          {
            "id": "123"
          }
        ]
      }
    }
  ]
}
Response
{
  "requestId": "6894439706274654514",
  "payload": {
    "devices": {
      "123": {
        "status": "SUCCESS",
        "online": true,
        "on": true,
        "brightness": 65,
        "color": {
          "temperatureK": 4000
        }
      }
    }
  }
}

Sample EXECUTE commands

ColorAbsolute

For additional details on the command parameters, see the action.devices.traits.ColorSetting reference.

Request
{
  "requestId": "6894439706274654520",
  "inputs": [
    {
      "intent": "action.devices.EXECUTE",
      "payload": {
        "commands": [
          {
            "devices": [
              {
                "id": "123"
              }
            ],
            "execution": [
              {
                "command": "action.devices.commands.ColorAbsolute",
                "params": {
                  "color": {
                    "name": "warm white",
                    "temperature": 3000
                  }
                }
              }
            ]
          }
        ]
      }
    }
  ]
}
Response
{
  "requestId": "6894439706274654520",
  "payload": {
    "commands": [
      {
        "ids": [
          "123"
        ],
        "status": "SUCCESS",
        "states": {
          "online": true,
          "color": {
            "temperatureK": 3000
          }
        }
      }
    ]
  }
}

BrightnessAbsolute

For additional details on the command parameters, see the action.devices.traits.Brightness reference.

Request
{
  "requestId": "6894439706274654518",
  "inputs": [
    {
      "intent": "action.devices.EXECUTE",
      "payload": {
        "commands": [
          {
            "devices": [
              {
                "id": "123"
              }
            ],
            "execution": [
              {
                "command": "action.devices.commands.BrightnessAbsolute",
                "params": {
                  "brightness": 65
                }
              }
            ]
          }
        ]
      }
    }
  ]
}
Response
{
  "requestId": "6894439706274654518",
  "payload": {
    "commands": [
      {
        "ids": [
          "123"
        ],
        "status": "SUCCESS",
        "states": {
          "online": true,
          "brightness": 65
        }
      }
    ]
  }
}

OnOff

For additional details on the command parameters, see the action.devices.traits.OnOff reference.

Request
{
  "requestId": "6894439706274654516",
  "inputs": [
    {
      "intent": "action.devices.EXECUTE",
      "payload": {
        "commands": [
          {
            "devices": [
              {
                "id": "123"
              }
            ],
            "execution": [
              {
                "command": "action.devices.commands.OnOff",
                "params": {
                  "on": true
                }
              }
            ]
          }
        ]
      }
    }
  ]
}
Response
{
  "requestId": "6894439706274654516",
  "payload": {
    "commands": [
      {
        "ids": [
          "123"
        ],
        "status": "SUCCESS",
        "states": {
          "online": true,
          "on": true
        }
      }
    ]
  }
}

Sample utterances

en-US

  • Turn on the lights
  • Turn on the {{devName}}
  • Turn on the {{roomName}} lights

  • Turn off the lights
  • Turn off the {{devName}}
  • Turn off the {{roomName}} lights
  • power off the {{devName}}
  • Turn the {{devName}} off in the {{roomName}}

  • Dim the lights
  • Dim the {{devName}}
  • Turn down the lights in the {{roomName}}

  • Brighten the lights
  • Brighten the {{devName}}

  • Change the lights to red
  • Change the {{devName}} to red
  • Make the {{roomName}} red

de-DE

  • Schalte das Licht an
  • Schalte das {{devName}} an
  • Schalte das {{roomName}} Licht ein

  • Schalte das Licht aus
  • Schalte das {{devName}} aus
  • Schalte das {{roomName}} aus
  • Schalte die {{devName}} aus
  • Schalte das {{devName}} im {{roomName}} aus

  • Dimme das Licht
  • Dimme das {{roomName}}
  • Dimme das Licht im {{roomName}}

  • Stell das Licht heller
  • Stell das {{devName}} heller

  • Ändere das Licht auf rot
  • Ändere das {{devName}} auf rot
  • Stell das Licht in der {{roomName}} auf rot

fr-FR

  • Allume la lumière
  • Allume la {{devName}}
  • Allume la lumière de la {{roomName}}

  • Éteins la lumière
  • Éteins la {{devName}}
  • Eteins la lumière dans le {{roomName}}
  • Eteins la {{devName}}
  • Eteins la {{devName}} dans le {{roomName}}

  • Tamise la lumière
  • Tamise la {{devName}}
  • Baisse les lumières dans la {{roomName}}

  • Augmente la luminosité
  • Augmente la {{devName}}

  • Mets la lumière en rouge
  • Mets la {{devName}} en rouge
  • Mets la lumière de la {{roomName}} rouge

Device ERRORS

See the full list of errors and exceptions.