Alexa.BrightnessController Interface
The Alexa.BrightnessController capability interface describes messages used to control the brightness of an endpoint such as a light bulb. Use this interface for devices that you know support brightness control instead of the more general Alexa.PercentageController interface. If you want to control the power level of an endpoint such as a dimmer switch, use the Alexa.PowerLevelController interface instead.
For the list of locales that are supported for the BrightnessController interface, see List of Capability Interfaces and Supported Locales.
Utterances
When you use the Alexa.BrightnessController interface, the voice interaction model is already built for you. The following examples show some customer utterances:
Alexa, dim the bathroom light.
Alexa, set the bedroom light to fifty percent.
アレクサ、浴室の照明を暗くして。
アレクサ、浴室の照明を50パーセント暗くして。
After the customer says an utterance, Alexa sends a corresponding directive to your skill.
Properties
The brightness property
The Alexa.BrightnessController interface uses the brightness property as the primary property. The property is an integer and valid values from 0 to 100 inclusive. If the brightness property is used to represent a change, then valid values are from -100 to 100 inclusive.
Discovery
You describe endpoints that support Alexa.BrightnessController using the standard discovery mechanism described in Alexa.Discovery.
Set retrievable to true for all of the interfaces and properties that you report when Alexa sends your skill a state report request. Set proactivelyReported to true for interfaces and properties that you proactively report to Alexa in a change report.
For the full list of display categories, see display categories.
Discover response example
The following example shows a Discover.Response message for an endpoint that supports the Alexa.BrightnessController and Alexa.ColorController interfaces.
{
"event": {
"header": {
"namespace": "Alexa.Discovery",
"name": "Discover.Response",
"payloadVersion": "3",
"messageId": "<message id>"
},
"payload": {
"endpoints":[
{
"endpointId": "<unique ID of the endpoint>",
"manufacturerName": "<the manufacturer name of the endpoint>",
"modelName": "<the model name of the endpoint>",
"description": "<a description that is shown in the Alexa app>",
"friendlyName": "<device name, displayed in the Alexa app>",
"displayCategories": ["LIGHT"],
"cookie": {},
"capabilities": [
{
"type": "AlexaInterface",
"interface": "Alexa.BrightnessController",
"version": "3",
"properties": {
"supported": [
{
"name": "brightness"
}
],
"proactivelyReported": true,
"retrievable": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.ColorController",
"version": "3",
"properties": {
"supported": [
{
"name": "color"
}
],
"proactivelyReported": true,
"retrievable": true
}
}
]
}
]
}
}
}
Directives
SetBrightness directive
Support the SetBrightness directive so that customers can set the brightness value of a device.
The following example shows a customer utterance:
Alexa, set the table light bulb to fifty percent.
Alexa, mettre le ampoule de cinquante pour cent
Alexa, stelle Glühbirne auf fünfzig prozent
アレクサ、浴室の照明を50パーセント暗くして。
SetBrightness directive payload details
| Field | Description | Type |
|---|---|---|
percentage |
The brightness to set the device to. | Integer |
SetBrightness directive example
{
"directive": {
"header": {
"namespace": "Alexa.BrightnessController",
"name": "SetBrightness",
"messageId": "<message id>",
"correlationToken": "<an opaque correlation token>",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "<an OAuth2 bearer token>"
},
"endpointId": "<endpoint id>",
"cookie": {}
},
"payload": {
"brightness": 50
}
}
}
SetBrightness response event
If you handle a SetBrightness directive successfully, respond with an Alexa.Response event. In the context object, include the values of all properties that changed. You can respond synchronously or asynchronously. If you respond asynchronously, include a correlation token and a scope with an authorization token.
SetBrightness response event example
{
"event": {
"header": {
"namespace": "Alexa",
"name": "Response",
"messageId": "<message id>",
"correlationToken": "<an opaque correlation token>",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "<an OAuth2 bearer token>"
},
"endpointId": "<endpoint id>"
},
"payload": {}
},
"context": {
"properties": [
{
"namespace": "Alexa.BrightnessController",
"name": "brightness",
"value": 50,
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 500
}
]
}
}
SetBrightness directive error handling
If you can't handle a SetBrightness directive successfully, respond with an Alexa.ErrorResponse event.
AdjustBrightness directive
Support the AdjustBrightness directive so that customers can adjust the brightness value of a device.
The following example shows a customer utterance:
Alexa, dim table light bulb twenty five percent.
Alexa, diminue le ampoule de vingt-cinq pour cent
Alexa, dimme Glühbirne fünfundzwanzig prozent
アレクサ、テーブルライトの電球を25パーセント暗くして。
AdjustBrightness directive payload details
| Field | Description | Type |
|---|---|---|
brightnessDelta |
The amount by which to change the brightness. | Integer |
AdjustBrightness directive example
{
"directive": {
"header": {
"namespace": "Alexa.BrightnessController",
"name": "AdjustBrightness",
"messageId": "<message id>",
"correlationToken": "<an opaque correlation token>",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "<an OAuth2 bearer token>"
},
"endpointId": "<endpoint id>",
"cookie": {}
},
"payload": {
"brightnessDelta": -25
}
}
}
AdjustBrightness response event
If you handle an AdjustBrightness directive successfully, respond with an Alexa.Response event. In the context object, include the values of all properties that changed. You can respond synchronously or asynchronously. If you respond asynchronously, include a correlation token and a scope with an authorization token.
AdjustBrightness response event example
{
"event": {
"header": {
"namespace": "Alexa",
"name": "Response",
"messageId": "<message id>",
"correlationToken": "<an opaque correlation token>",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "<an OAuth2 bearer token>"
},
"endpointId": "<endpoint id>"
},
"payload": {}
},
"context": {
"properties": [
{
"namespace": "Alexa.BrightnessController",
"name": "brightness",
"value": 75,
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 1000
}
]
}
}
AdjustBrightness directive error handling
If you can't handle an AdjustBrightness directive successfully, respond with an Alexa.ErrorResponse event.
State reporting
Alexa sends a ReportState directive to request information about the state of an endpoint. When Alexa sends a ReportState directive, you send a StateReport event in response. The response contains the current state of all of the retrievable properties in the context object. You identify your retrievable properties in your discovery response. For more information about state reports, see Understand State Reporting.
StateReport response event example
{
"event": {
"header": {
"namespace": "Alexa",
"name": "StateReport",
"messageId": "<message id>",
"correlationToken": "<an opaque correlation token>",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "<an OAuth2 bearer token>"
},
"endpointId": "<endpoint id>"
},
"payload": {}
},
"context": {
"properties": [
{
"namespace": "Alexa.BrightnessController",
"name": "brightness",
"value": 75,
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 1000
}
]
}
}
Change reporting
You send a ChangeReport event to proactively report changes in the state of an endpoint. You identify the properties that you proactively report in your discovery response. For more information about change reports, see Understand State Reporting.
ChangeReport event example
{
"event": {
"header": {
"namespace": "Alexa",
"name": "ChangeReport",
"messageId": "<message id>",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "<an OAuth2 bearer token>"
},
"endpointId": "<endpoint id>"
},
"payload": {
"change": {
"cause": {
"type": "PHYSICAL_INTERACTION"
},
"properties": [
{
"namespace": "Alexa.BrightnessController",
"name": "brightness",
"value": 75,
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
},
"context": {}
}
