Alexa.PowerController Interface

The PowerController interface describes the messages used to control and report on the power state of a device.

Directives

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

  • English - all locales
  • French (FR)
  • German
  • Italian
  • Japanese
  • Spanish (ES)

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

TurnOn

TurnOn

Request to turn on an endpoint.

User: Alexa, turn on device
User: Alexa, schalte Smart Home-Gerät ein
User: deviceをつけて
User: allume device s'il te plaît

Example Request:

{
  "directive": {
    "header": {
      "namespace": "Alexa.PowerController",
      "name": "TurnOn",
      "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": {}
  }
}

Payload details

Field Description Type Required
None No required or optional fields in the payload. N/A N/A

TurnOff

Request to turn off an endpoint.

User: Alexa, turn off device
User: Alexa, schalte Smart Home-Gerät aus
User: deviceを消して
User: Eteins device s'il te plaît

Example Request:

{
  "directive": {
    "header": {
      "namespace": "Alexa.PowerController",
      "name": "TurnOff",
      "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": {}
  }
}

Payload details

Field Description Type Required
None No required or optional fields in the payload. N/A N/A

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

When the power state changes, send a state report with a powerState property.

Property Name Type Description
powerState PowerState Indicates whether the device is powered on or off. Valid values are ON and OFF.

Response

Send an Response event when a power on or power off request successfully completes.

Response example for a TurnOn request

{
  "context": {
    "properties": [ {
      "namespace": "Alexa.PowerController",
      "name": "powerState",
      "value": "ON",
      "timeOfSample": "2017-02-03T16:20:50.52Z",
      "uncertaintyInMilliseconds": 500
    } ]
  },
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "payloadVersion": "3",
      "messageId": "abc-123-def-456",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-Amazon"
      },
      "endpointId": "appliance-001"
    },
    "payload": {}
  }
}

Response example for a TurnOff request

{
  "context": {
    "properties": [ {
      "namespace": "Alexa.PowerController",
      "name": "powerState",
      "value": "OFF",
      "timeOfSample": "2017-02-03T16:20:50.52Z",
      "uncertaintyInMilliseconds": 500
    } ]
  },
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "payloadVersion": "3",
      "messageId": "abc-123-def-456",
      "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 Alexa.ErrorResponse for more details.

Additional Sample Code

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

PowerController

Works with Amazon Alexa Guidelines

Description Requirement
Responses to user requests Should take less than 2 seconds. A response that takes longer than 5 seconds is recorded as a latency failure.
State reporting [All properties][alexa-reportableproperties] should be proactivelyReported and retrievable.
WWAA test cases WWAA PowerController tests
Interface Description
Alexa.PowerLevelController Defines messages to change the power level for an endpoint.