Alexa.BrightnessController

The Alexa.BrightnessController interface describes messages used to control and report on the brightness of an endpoint such as a light bulb. You should use this interface for appliances that you know support the brightness control over the more general Alexa.PercentageController interface. If you want to handle requests specific to the power level of an endpoint such as a dimmer switch, see Alexa.PowerLevelController.

Directives
- AdjustBrightness
- SetBrightness
Properties and Events
Additional Sample Code
Related Interfaces

Directives

This control and query directives in this interface are supported in skills that target the following languages:

English (US)
English (UK)
English (India)
German

See Develop Smart Home Skills in Multiple Languages for more information.

AdjustBrightness

Adjusts the brightness of an endpoint either up or down, depending on whether a positive or negative value is specified.

“Alexa, dim device ##%”

“Alexa, dimme Smart Home-Gerät ##%.”

Example Request:


{
  "directive": {
    "header": {
      "namespace": "Alexa.BrightnessController",
      "name": "AdjustBrightness",
      "payloadVersion": "3",
      "messageId": "1bd5d003-31b9-476f-ad03-71d471922820",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "Alexa-access-token"
      },
      "endpointId": "appliance-001",
      "cookie": {}
    },
    "payload": {
      "brightnessDelta": 3
    }
  }
}

Payload details

Field	Description	Type	Required
`brightnessDelta`	The desired change in brightness as percentage points. A positive or negative integer value used to increase or decrease the percentage. For example, a starting value of 97 with a brightness delta of 3 would result in a final value of 100.	integer from -100 to 100, inclusive.	Yes

SetBrightness

Sets the brightness value for an endpoint.

“Alexa, set the device to ##%”

“Alexa, stelle Smart Home-Gerät auf *##%.”

Example Request:

{
  "directive": {
    "header": {
      "namespace": "Alexa.BrightnessController",
      "name": "SetBrightness",
      "payloadVersion": "3",
      "messageId": "1bd5d003-31b9-476f-ad03-71d471922820",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "some-access-token"
      },
      "endpointId": "appliance-001",
      "cookie": {}
    },
    "payload": {
      "brightness": 42
    }
  }
}

Payload details

Field	Description	Type	Required
`brightness`	A value that indicates the desired brightness as a percentage.	integer from 0-100, inclusive.	Yes

Properties and Events

For this interface, 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 reportable properties in the context of the message.

Reportable Properties

Property Name	Type	Description
`brightness`	See Brightness	The brightness of an appliance such a smart light bulb as an integer from 0-100, inclusive.

Response

If the brightness controller directive was successfully handled, you should respond with an Response event.

Example Response

{
  "context": {
    "properties": [ {
      "namespace": "Alexa.BrightnessController",
      "name": "brightness",
      "value": 42,
      "timeOfSample": "2017-02-03T16:20:50.52Z",
      "uncertaintyInMilliseconds": 1000
    } ]
  },
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "payloadVersion": "3",
      "messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "Alexa-access-token"
      },
      "endpointId": "appliance-001"
    },
    "payload": {}
  }
}

ErrorResponse

You should reply with an error if you cannot complete the customer request for some reason. See Error.Response for more details.

Additional Sample Code

See the sample request and response messages in the Alexa smart home GitHub repo:

BrightnessController

Interface	Description
Alexa.PercentageController	Sets a percentage.
Alexa.ColorController	Sets the color of a light endpoint.
Alexa.PowerLevelController	Controls the power level of an endpoint.