Alexa.PowerController Interface

    The Alexa.PowerController capability interface comprises the mechanics related to control and reporting on the power state of an endpoint.

    It defines reportable state properties and uses the centralized Alexa interface for state reporting.

    You can think of Alexa.PowerController as a pre-built, named instance of the Alexa.ToggleController capability primitive.

    Dependencies

    An endpoint for which support for Alexa.PowerController 3.0 is asserted must also have Alexa 3.0 or higher implemented on its behalf.

    A device maintaining an HTTP/2 connection that implements the Alexa.PowerController 3.0 capability on its own behalf or on behalf of other connected endpoints must also implement support for Alexa.Discovery 3.0 or higher.

    Capability Assertion

    To use the Alexa.PowerController capability, it must be asserted in the capabilities list of a Discover.Response or AddOrUpdateReport event in the Alexa.Discovery interface.

    The device maintaining the HTTP/2 connection may implement the Alexa.PowerController capability both on its own behalf as an endpoint and on behalf of other endpoints. The device must assert support for the Alexa.PowerController capability and its dependencies in the capabilities list for each endpoint that leverages it.

    Sample Object

    {
      "type": "AlexaInterface",
      "interface": "Alexa.PowerController",
      "version": "3",
      "properties": {
        "supported": [
          {
            "name": "powerState"
          }
        ],
        "proactivelyReported": {{BOOLEAN}},
        "retrievable": {{BOOLEAN}}
      }
    },
    {
      "type": "AlexaInterface",
      "interface": "Alexa",
      "version": "3"
    }
    

    Object Parameters

    Parameter Description Type
    properties.
      proactivelyReported
    Whether changes in values of the reportable state properties for this capability on this endpoint can be reported by the device through the ChangeReport event. boolean
    properties.
      retrievable
    Whether the values of the reportable state properties for this capability on this endpoint will be reported by the device through the StateReport event in response the ReportState directive. boolean

    Reportable State Properties

    powerState

    Alexa.PowerController 3.0 defines the powerState property, an instance of the PowerState property schema.

    Sample Object

    {
      "namespace": "Alexa.PowerController",
      "name": "powerState",
      "value": "{{STRING}}",
      "timeOfSample": "{{STRING}}",
      "uncertaintyInMilliseconds": {{LONG}}
    }
    

    Object Parameters

    Parameter Description Type
    value The value of the powerState property.

    Accepted Values: ON, OFF
    string
    timeOfSample The UTC timestamp corresponding to when the property value was recorded, in ISO 8601 YYYY-MM-DDThh:mm:ssZ format. string
    uncertaintyInMilliseconds The number of milliseconds that have elapsed since the property value was last confirmed. For example, if the device sampled the property value from the endpoint 60 seconds ago, the uncertaintyInMilliseconds would be 60000. long

    Directives

    TurnOn

    AVS will send the TurnOn directive to instruct the device to send a "turn on" signal to the specified endpoint.

    The device must send the Response event in the Alexa namespace in response. The DeferredResponse event is not supported as an alternative to sending an immediate Response event.

    If the TurnOn directive cannot be successfully executed, the device should send the ErrorResponse event instead.

    Sample Message

    {
      "directive": {
        "header": {
          "namespace": "Alexa.PowerController",
          "name": "TurnOn",
          "payloadVersion": "3",
          "messageId": "{{STRING}}",
          "correlationToken": "{{STRING}}"
        },
        "endpoint": {
          "endpointId": "{{STRING}}"
        }
        "payload": {
        }
      }
    }
    

    Message Parameters

    Parameter Description Type
    directive.
      header.
        messageId
    A universally unique identifier (UUID) generated to the RFC 4122 specification. string
    directive.
    header.
        correlationToken
    An opaque token that must be included in any events responding to this directive. string
    directive.
      endpoint.
        endpointId
    The identifier of the endpoint for which the state is being set. string

    Note: The payload is an empty object.

    TurnOff

    AVS will send the TurnOff directive to instruct the device to send a "turn off" signal to the specified endpoint.

    The device must send the Response event in the Alexa namespace in response. The DeferredResponse event is not supported as an alternative to sending an immediate Response event.

    If the TurnOff directive cannot be successfully executed, the device should send the ErrorResponse event instead.

    Sample Message

    {
      "directive": {
        "header": {
          "namespace": "Alexa.PowerController",
          "name": "TurnOff",
          "payloadVersion": "3",
          "messageId": "{{STRING}}",
          "correlationToken": "{{STRING}}"
        },
        "endpoint": {
          "endpointId": "{{STRING}}"
        }
        "payload": {
        }
      }
    }
    

    Message Parameters

    Parameter Description Type
    directive.
      header.
        messageId
    A universally unique identifier (UUID) generated to the RFC 4122 specification. string
    directive.
    header.
        correlationToken
    An opaque token that must be included in any events responding to this directive. string
    directive.
      endpoint.
        endpointId
    The identifier of the endpoint for which the state is being set. string

    Note: The payload is an empty object.

    Events

    Alexa.PowerController does not define any events within its namespace. Interactions involving power control leverage the centralized state change and reporting mechanisms defined in the Alexa interface:

    • Responses to Alexa.PowerController directives use the Response and ErrorResponse events.
    • Changes to Alexa.PowerController's reportable state properties detected by the device use the ChangeReport event.
    • The device must use the StateReport event to respond to the cloud's interrogation of Alexa.PowerController's reportable state properties' values via the ReportState directive.

    Additional Resources

    The Alexa.PowerController 3.0 capability has its origins in the Alexa Smart Home Skills API. It is now available directly to AVS devices with an HTTP/2 connection, without requiring an AWS Lambda or maintaining a separate cloud service. The following resources provide additional context and examples: