Alexa.BrightnessController Interface
Implement the Alexa.BrightnessController interface in your Alexa skill so that users can control the brightness of devices such as light bulbs. For more information about Smart Home skills, see Understand the Smart Home Skill API.
Use the BrightnessController 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 languages that the BrightnessController interface supports, see List of Alexa Interfaces and Supported Languages.
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 a light 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
}
},
{
"type": "AlexaInterface",
"interface": "Alexa",
"version": "3"
}
]
}
]
}
}
}
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
The following example illustrates a SetBrightness directive that Alexa sends to your skill.
{
"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
The following example illustrates an AdjustBrightness directive that Alexa sends to your skill.
{
"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 details about state reports, see Understand State and Change 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 details about change reports, see Understand State and Change 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": {}
}
