Merci de votre visite. Cette page est disponible en anglais uniquement.

Alexa.PowerLevelController Interface

The Alexa.PowerLevelController interface describes the messages used to control the power level of an endpoint. Use this interface for devices such as a power dimmer that supports power-level control instead of the more general Alexa.PercentageController interface.

For the list of locales that are supported for the PowerLevelController interface, see List of Capability Interfaces and Supported Locales.

Utterances

When you use the Alexa.PowerLevelController interface, the voice interaction model is already built for you. The following examples show some customer utterances:

Alexa, increase the power level by 2 on the light switch.

After the customer says one of these utterances, Alexa sends a corresponding directive to your skill.

Directives

SetPowerLevel

Sets the power level value for an endpoint.

User: Alexa set the power to 40% on device

Example Request:

{
"directive": {
    "header": {
      "namespace": "Alexa.PowerLevelController",
      "name": "SetPowerLevel",
      "messageId": "abc-123-def-456",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-skill"
      },
      "endpointId": "appliance-001",
      "cookie": {}
    },
    "payload": {
      "powerLevel": 40
    }
  }
}

Payload details

Field Description Type Required
powerLevel Indicates the desired power level for the device. An integer between 0 and 100, inclusive. Yes

AdjustPowerLevel

Increases or decreases the power level of an endpoint by the specified percentage.

User: Alexa, increase the power level by 3 for device

Example Request:

{
  "directive": {
    "header": {
      "namespace": "Alexa.PowerLevelController",
      "name": "AdjustPowerLevel",
      "messageId": "abc-123-def-456",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-skill"
      },
      "endpointId": "appliance-001",
      "cookie": {}
    },
    "payload": {
      "powerLevelDelta": 3
    }
  }
}

Payload details

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

Properties and Events

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

Properties

Property Name Type Description
powerLevel Percentage The power level of an appliance such as a power dimmer expressed as a percentage value between 0 and 100.

Response

Send an Response event when a SetPowerLevel or AdjustPowerLevel request successfully completes.

Example Response

{
   "context":{
      "properties":[
         {
            "namespace":"Alexa.PowerLevelController",
            "name":"powerLevel",
            "value": 42,
            "timeOfSample":"2017-02-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 0
         }
      ]
   },
   "event":{
      "header":{
         "namespace":"Alexa",
         "name":"Response",
         "messageId":"abc-123-def-456",
         "correlationToken":"dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
         "payloadVersion":"3"
      },
      "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 Alexa.ErrorResponse for more details.

Additional Sample Code

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

PowerLevelController

Interface Description
Alexa.PowerController Defines messages to turn an endpoint on and off.