Your Alexa Dashboards Settings

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

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

  • English - all locales
  • German
  • Japanese

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.

User: 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": "access-token-from-Amazon"
      },
      "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": "access-token-from-skill"
      },
      "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": "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 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.