Alexa.ColorController Interface
The Alexa.ColorController
interface describes the messages used to change and report the color of an endpoint such as a color-changing light bulb.
Directives
The control and query directives in this interface are supported in skills that target the following languages:
- English - all locales
- French (FR)
- German
- Italian
- Japanese
- Spanish (ES)
See Develop Smart Home Skills in Multiple Languages for more information.
SetColor
Request to set the color of the light for an endpoint.
User: Alexa, set the device name to color
User: Alexa, set the bedroom light to red
User: Alexa, change the kitchen to the color blue
User: setze Wohnzimmerlicht auf rosa
Example Request:
{
"directive": {
"header": {
"namespace": "Alexa.ColorController",
"name": "SetColor",
"payloadVersion": "3",
"messageId": "abc-123-def-456",
"correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "access-token-from-skill"
},
"endpointId": "appliance-001",
"cookie": {}
},
"payload": {
"color": {
"hue": 350.5,
"saturation": 0.7138,
"brightness": 0.6524
}
}
}
}
Payload details
Field | Description | Type | Required |
---|---|---|---|
color |
Describes the color to set for the light. Specified in the hue, saturation, brightness (HSB) color model. | color object | Yes |
SetColor
directive will align to the customer's requested color, however, for the best customer experience when you make a color change, you should maintain the current brightness setting of the target endpoint. For example, if a bulb is set to white at 50% brightness (0.5), and a customer requests a color change to red, the SetColor
directive provides hue, saturation and brightness values of 0,1,1, respectively, which indicates full brightness. In this case, you should ignore the brightness value in the directive, and maintain the current brightness setting of 0.5.Properties and Events
For this capability, you must either reply:
- Synchronously, which means you send a Response event to Alexa from the Lambda function.
- Asynchronously, which means you send a Response event to the Alexa event gateway. When you reply asynchronously, you must include a
scope
with an authorization token to identify the customer, and a correlation token to identify the directive you are responding to.
When you send a Response
, you should include the state of the interface properties in the context
of the message.
For lighting endpoints that support the ColorController and ColorTemperatureController interfaces, report the state of color
when an endpoint is set to a color, and report the state of colorTemperatureInKelvin
when an endpoint is set to a shade of white.
Properties
Property Name | Type | Description |
---|---|---|
color |
Color | Describes the color to set for the light. The value is specified in the hue, saturation, brightness (HSB) color model. Report the color property only when the bulb is set to an HSB color. |
Response
If the SetColor
directive was successfully handled, you should respond with an Response
event and include the state of the color
property in the context
of the message.
Example Response
The following example shows a response for a endpoint that supports HSB colors or for a endpoint that supports HSB colors and color temperature, but is currently set to an HSB color.
{
"context": {
"properties": [ {
"namespace": "Alexa.ColorController",
"name": "color",
"value": {
"hue": 350.5,
"saturation": 0.7138,
"brightness": 0.6524
},
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 1000
} ]
},
"event": {
"header": {
"namespace": "Alexa",
"name": "Response",
"payloadVersion": "3",
"messageId": "abc-123-def-456",
"correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "access-token-from-Amazon"
},
"endpointId": "appliance-001"
},
"payload": {}
}
}
ErrorResponse
You should reply with an error if you cannot complete the customer request for some reason. See Alexa.ErrorResponse for more details.
Additional Sample Code
See the sample request and response messages in the Alexa smart home GitHub repo:
Related Interfaces
Interface | Description |
---|---|
Alexa.ColorTemperatureController | Sets the color temperature of a tunable light endpoint. |