Alexa.ModeController Interface

    The Alexa.ModeController capability interface comprises the mechanics related to control and reporting on the properties of an endpoint that can be set to a discrete value among a defined set of ordered or unordered values.

    Alexa.ModeController is an example of a capability primitive, a type of interface that can be implemented multiple times for the same endpoint. The instance field in its capability assertion differentiates between the different endpoint functionalities that leverage Alexa.ModeController.

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

    Dependencies

    An endpoint for which support for Alexa.ModeController 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.ModeController 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.ModeController 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.ModeController capability both on its own behalf as an endpoint and on behalf of other endpoints. The device must assert support for the Alexa.ModeController capability and its dependencies in the capabilities list for each endpoint that leverages it.

    Sample Object

    {
      "type": "AlexaInterface",
      "interface": "Alexa.ModeController",
      "version": "3",
      "instance": "{{STRING}}",
      "properties": {
        "supported": [
          {
            "name": "mode"
          }
        ],
        "proactivelyReported": {{BOOLEAN}},
        "retrievable": {{BOOLEAN}},
        "nonControllable": {{BOOLEAN}}
      },
      "configuration": {
        "ordered": {{BOOLEAN}},
        "supportedModes": [
          {
            "value": "{{STRING}}",
            "modeResources": {
              "friendlyNames": [
                // label objects representing
                // friendly names for the mode
              ]
            }
          },
          ...
        ]
      }
      "capabilityResources": {
        "friendlyNames" [
          // label objects representing
          // friendly names for the instance
        ]
      },
      "semantics": {
        "actionMappings": [
          {
            "@type": "ActionsToDirective",
            "actions": ["{{STRING}}", ...],
            "directive": {
              "name": "{{STRING}}",
              "payload": {{OBJECT}}
            }
          },
          ...
        ],
        "stateMappings": [
          {
            "@type": "StatesToValue",
            "states": ["{{STRING}}", ...],
            "value": "{{STRING}}"
          },
          ...
        ]
      }
    },
    {
      "type": "AlexaInterface",
      "interface": "Alexa",
      "version": "3"
    }
    

    Object Parameters

    Parameter Description Type
    instance The identifier of this instance of Alexa.ModeController on this endpoint. string
    properties.
      proactivelyReported
    Whether changes in values of the reportable state properties for this instance of 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 instance of this capability on this endpoint will be reported by the device through the StateReport event in response the ReportState directive. boolean
    properties.
      nonControllable
    Whether the values of the reportable state properties for this instance of this capability on this endpoint are non-controllable by the end user.

    false is the default, which allows users to control the properties by voice and through the Alexa app.

    true allows the endpoint to report the state, but will prevent Alexa from sending the SetMode and AdjustMode directives.
    boolean
    configuration.
      ordered
    Whether the modes are ordered, enabling iteration through them using the AdjustMode directive. long
    configuration.
      supportedModes
    A list of objects describing the available modes. If ordered is true, the order of the objects in this list will imply the ordering of the modes. list
    configuration.
      supportedModes[i].
        value
    The identifier of the mode, which is referenced by the mode property. string
    configuration.
      supportedModes[i].
        modeResources.
          friendlyNames
    A list of label objects to describe the possible friendly names for the mode. list
    capabilityResources.
      friendlyNames
    A list of label objects to describe the possible friendly names for this instance of this capability on this endpoint.

    Examples are available in the capability resources section of the Smart Home Skills Kit documentation.
    list
    semantics Semantic annotations that allow mapping user utterances with capability directives and states. object
    semantics.
      actionMappings[i].
        actions[j]
    The identifiers of the utterances that should trigger the directive.

    Accepted Values:
    Alexa.Actions.Open: "open {endpoint}"
    Alexa.Actions.Close: "close {endpoint}"
    Alexa.Actions.Raise: "raise {endpoint}"
    Alexa.Actions.Lower: "lower {endpoint}"
    string
    semantics.
      actionMappings[i].
        directive.
          name
    Accepted Values:

    SetMode: The identified actions should trigger the SetMode directive with the specified payload.
    AdjustMode: The identified actions should trigger the AdjustMode directive with the specified payload.
    string
    semantics.
      actionMappings[i].
        directive.
          payload
    If name is SetMode, this must be the SetMode payload object that contains the mode property and the corresponding value from configuration.supportedModes[].value.

    If name is AdjustMode, this must be the AdjustMode payload object that contains the modeDelta field and the corresponding number of modes to advance.
    object
    semantics.
      stateMappings[i].
        states[j]
    The identifiers of the utterances that reflect the specified states.

    Accepted Values:
    Alexa.States.Open: "is {endpoint} open"
    Alexa.States.Closed: "is {endpoint} closed"
    string
    semantics.
      stateMappings[i].
        value
    The value from configuration.supportedModes[].value that corresponds to the identified states. string

    Reportable State Properties

    mode

    Alexa.ModeController 3.0 defines the mode property.

    Sample Object

    {
      "namespace": "Alexa.ModeController",
      "instance": "{{STRING}}",
      "name": "mode",
      "value": {{STRING}},
      "timeOfSample": "{{STRING}}",
      "uncertaintyInMilliseconds": {{LONG}}
    }
    

    Object Parameters

    Parameter Description Type
    instance The identifier of this instance of Alexa.ModeController on this endpoint. string
    value The value of the mode property.

    Accepted values must have been asserted as a value in the supportedModes.
    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

    SetMode

    AVS will send the SetMode directive to instruct the device to set the specified mode of the instance of Alexa.ModeController 3.0 on 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 SetMode directive cannot be successfully executed, the device should send the ErrorResponse event instead.

    Sample Message

    {
      "directive": {
        "header": {
          "namespace": "Alexa.ModeController",
          "instance": "{{STRING}},
          "name": "SetMode",
          "payloadVersion": "3",
          "messageId": "{{STRING}}",
          "correlationToken": "{{STRING}}"
        },
        "endpoint": {
          "endpointId": "{{STRING}}"
        }
        "payload": {
          "mode": "{{STRING}}"
        }
      }
    }
    

    Message Parameters

    Parameter Description Type
    directive.
      header.
        instance
    The identifier of this instance of Alexa.ModeController on this endpoint. string
    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
    directive.
      payload.
        mode
    The mode value to set this instance of Alexa.ModeController to on the specified endpoint.

    Possible values are those asserted as a value in the supportedModes.
    string

    AdjustMode

    AVS will send the AdjustMode directive to instruct the device to iterate through the modes of the instance of Alexa.ModeController 3.0 on the specified endpoint.

    AVS will only send this directive if the modes are asserted to be ordered.

    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 AdjustMode directive cannot be successfully executed, the device should send the ErrorResponse event instead.

    Sample Message

    {
      "directive": {
        "header": {
          "namespace": "Alexa.ModeController",
          "instance": "{{STRING}},
          "name": "AdjustMode",
          "payloadVersion": "3",
          "messageId": "{{STRING}}",
          "correlationToken": "{{STRING}}"
        },
        "endpoint": {
          "endpointId": "{{STRING}}"
        }
        "payload": {
          "modeDelta": {{LONG}}
        }
      }
    }
    

    Message Parameters

    Parameter Description Type
    directive.
      header.
        instance
    The identifier of this instance of Alexa.ModeController on this endpoint. string
    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
    directive.
      payload.
        modeDelta
    The integer number of modes to advance from the current mode, based on the order of objects in the asserted supportedModes list. The default value is 1, if the end user did not explicitly specify an amount. long

    Events

    Alexa.ModeController does not define any events within its namespace. Instances of Alexa.ModeController leverage the centralized state change and reporting mechanisms defined in the Alexa interface and must provide the instance field when including reportable state property objects:

    • Responses to Alexa.ModeController directives use the Response and ErrorResponse events.
    • Changes to Alexa.ModeController'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.ModeController's reportable state properties' values via the ReportState directive.

    Additional Resources

    The Alexa.ModeController 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: