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 details 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.

Copied to clipboard.

{
  "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",
          "description": "a description that is shown in the Alexa app",
          "friendlyName": "Living Room Light",
          "displayCategories": ["LIGHT"],
          "additionalAttributes":  {
            "manufacturer": "the manufacturer name of the endpoint",
            "model" : "the model of the device",
            "serialNumber": "the serial number of the device",
            "firmwareVersion" : "the firmware version of the device",
            "softwareVersion": "the software version of the device",
            "customIdentifier": "your custom identifier for the device"
          },
          "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

Copied to clipboard.

{
  "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

Copied to clipboard.

{
  "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

Copied to clipboard.

{
  "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

Copied to clipboard.

{  
  "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": {}
}