Your Alexa Dashboards Settings

Build Smart Home Skills for Lights

Smart home skills created for lights give customers voice access to their bulbs, lights and switches in new ways. For example, a customer can say, “Alexa, turn the family room light to 50%” and the brightness level of the light will change. Smart home skills for Alexa enable customers to use their voice to do the following:

  • Turn lights on and off
  • Set light level and power percentages
  • Change the color of color-capable bulbs
  • Change the color temperature of tunable white lights

These skills also enable a customer to see the current status of their cloud-connected lights in the Alexa app.

This document provides a overview of the concepts as well as specific directives and error messages for smart home skills that target lighting devices.

To create a smart home skill, you provide configuration information in the Amazon Developer Portal and code, which is hosted as an AWS Lambda function (an Amazon Web Services offering). The skill responds to messages, called directives, from Alexa, and communicates with connected devices, such as lights and switches, and sends response events back to the the Alexa.

You should be familiar with the steps to create a smart home skill. For more information see:

Identify a lighting endpoint

Alexa sends a discovery request when your skill is enabled and in the response, you describe an endpoint as a lighting device by listing the appropriate capabilities associated with the device and the properties that you support for each capability. In addition, you should provide the displayCategory for the device, which enables it to display properly in the Alexa app. For lighting endpoints this could be one of the following:

  • LIGHT - Indicates a light source or fixture
  • SWITCH - Indicates in-wall switches wired to the electrical system.

The following code example shows how you might describe a lighting device in a discovery response event.

Example discovery response for a lighting device

{
   "event":{
      "header":{
         "namespace":"Alexa.Discovery",
         "name":"Discover.Response",
         "payloadVersion":"3",
         "messageId":"5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4"
      },
      "payload":{
         "endpoints":[
            {
               "endpointId":"appliance-001",
               "friendlyName":"Living Room Light",
               "description":"Smart Light by Sample Manufacturer",
               "manufacturerName":"Sample Manufacturer",
               "displayCategories":[
                  "LIGHT"
               ],
               "cookie":{
                  "extraDetail1":"optionalDetailForSkillAdapterToReferenceThisDevice",
                  "extraDetail2":"There can be multiple entries",
                  "extraDetail3":"but they should only be used for reference purposes",
                  "extraDetail4":"This is not a suitable place to maintain current device state"
               },
               "capabilities":[
                  {
                     "type":"AlexaInterface",
                     "interface":"Alexa.ColorTemperatureController",
                     "version":"3",
                     "properties":{
                        "supported":[
                           {
                              "name":"colorTemperatureInKelvin"
                           }
                        ],
                        "proactivelyReported":true,
                        "retrievable":true
                     }
                  },
                  {
                      "type": "AlexaInterface",
                      "interface": "Alexa.PowerController",
                      "version": "3",
                      "properties": {
                        "supported": [ {
                          "name": "powerState"
                        } ],
                        "proactivelyReported": true,
                        "retrievable": true
                     }
                  },
                  {
                     "type":"AlexaInterface",
                     "interface":"Alexa",
                     "version":"3"
                  },
                  {
                     "type":"AlexaInterface",
                     "interface":"Alexa.ColorController",
                     "version":"3",
                     "properties":{
                        "supported":[
                           {
                              "name":"color"
                           }
                        ],
                        "proactivelyReported":true,
                        "retrievable":true
                     }
                  }
               ]
            }
         ]
      }
   }
}

Choose capabilities

To act on customer requests to turn on or change a light, you will need to choose the correct capabilities. The capability interfaces that describe lighting device actions are described in the following table. These interfaces are supported in all languages.

Operation Capability Interface
Turn a light on or off Alexa.PowerController
Set the power level of an endpoint Alexa.PowerLevelController
Change the brightness of a light by percentage or to a specific value Alexa.BrightnessController
Change the color of a light Alexa.ColorController
Change the shade of white for a tunable light Alexa.ColorTemperatureController

Report errors

Most of the error messages you might send in response to a lighting control directive such as an endpoint is unavailable or a security token has expired, are straightforward and can be referenced in the ErrorResponse topic.

The following error scenarios are unique to lighting endpoints.

Scenario Error message type Notes
A directive with a tunable white light setting is sent to an endpoint that is currently set to a color. NOT_SUPPORTED_IN_CURRENT_MODE Requires a currentDeviceMode field set to COLOR. See the example in ColorTemperatureController for more information.