We are happy to announce tunable lighting control, a new feature in the Smart Home Skill API now available in the US with support for the UK and Germany coming soon. This is great news for those of you targeting color-changing lights or tunable white lights. Now you can enable customers to issue a voice command such as, “Alexa, change the living room light to blue” or “Alexa, set office light to daylight.” This feature is supported today with lights from Hue, LIFX, TP-Link, and lights controlled by SmartThings Hub.

Enable Tunable White Lighting Control

As customers play with tunable white lighting to set the ideal light for waking, reading, and sleeping, you can now support these requests through the SetColorTemperatureRequest directive. The payload of this request contains a colorTemperature object with a single property named value. The value property is an integer between 1,000 and 10,000 and represents Kelvin degrees.

For example, if a customer requests “Alexa, set table lamp to reading,” this will result in 2,700 for the value of the colorTemperature object. If the customer requests “Alexa, change the office light to daylight,” the resulting value is 5,500. You are responsible for converting the Kelvin value for devices that don’t support it directly. For a listing of common white colors and their Kelvin mapping, see SetColorTemperatureRequest in our API reference documentation.

You can also support increasing/decreasing the white temperature through the IncrementColorTemperatureRequest and DecrementColorTemperatureRequest directives. In both directives, no explicit value is passed into the payload of the request. It is up to you to implement how much to increase/decrease the Kelvin relative to the current device setting. If you receive either of these directives but the current state of the light is non-white (red, blue, orange, etc.) the skill adapter should return a NotSupportedInCurrentModeError.

Enable Color Lighting Control

To set a color explicitly, add code in your skill adapter to respond to the SetColorRequest directive. The payload of the request contains a color object with Hue, Saturation, and Brightness (HSB) which maps to the color requested by the customer. Here is an example of an incoming directive setting a light to red:

    {
      "header":{
        "namespace":"Alexa.ConnectedHome.Control",
        "name":"SetColorRequest",
        "payloadVersion":"2",
        "messageId":"271314cd-ca00-49ca-b99e-d6f65ac87414"
      },
      "payload":{
        "accessToken":"[OAuth Token here]",
        "appliance":{
          "applianceId":"[Device ID for color capable light]",
          "additionalApplianceDetails":{}
        },
        "color":{
          "hue": 0.0,
          "saturation": 1.00,
          "brightness": 1.00
        }
      }
    }

If the target device requires Red, Green, Blue (RGB) settings, convert from HSB to RGB in the skill adapter. The red example above converts to RGB as R=255, G=0, B=0. For help on this, search the web for HSB-to-RGB converters.

Please review our documentation on color and white lighting control for more technical details. To learn more about developing a smart home skill check out these resources:

• Understanding the Smart Home Skill API
• Five Steps Before Developing a Smart Home Skill
• Coding Smart Home Skill Directives Using Node.js
• Managing Device Discovery for Your Alexa Smart Home Skill
• Controlling the On/Off State of a Smart Home Device
• Scenes for Smart Home Home Skills

Build a Skill, Get a Shirt

The Alexa Skills Kit (ASK) enables developers to build capabilities, called skills, for Alexa. ASK is a collection of self-service APIs, documentation, templates, and code samples that make it fast and easy for anyone to add skills to Alexa. 

Developers have built more than 10,000 skills with ASK. Explore the stories behind some of these innovations, then start building your own skill. Once you publish your skill, mark the occasion with a free, limited-edition Alexa dev shirt. Quantities are limited.