Alexa.RangeController 3.0

The Alexa.RangeController capability interface comprises the mechanics related to control and reporting on the properties of an endpoint that can be set to a numeric value within a range.

Alexa.RangeController is an example of a generic controller, a type of interface that you can implement multiple times for the same device. The instance field in its capability assertion differentiates between the different functionalities that leverage Alexa.RangeController.

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

Note: While the canonical version of this interface is "3.0", it must be reported and referenced as only the major version "3" in events and directives.

Dependencies

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

Sample Object

{
  "type": "AlexaInterface",
  "interface": "Alexa.RangeController",
  "version": "3",
  "instance": "{{STRING}}",
  "properties": {
    "supported": [
      {
        "name": "rangeValue"
      }
    ],
    "proactivelyReported": {{BOOLEAN}},
    "retrievable": {{BOOLEAN}},
    "nonControllable": {{BOOLEAN}}
  },
  "configuration": {
    "supportedRange": {
      "minimumValue": {{NUMBER}},
      "maximumValue": {{NUMBER}},
      "precision": {{NUMBER}}
    },
    "presets": [
      {
        "rangeValue": {{NUMBER}},
        "presetResources": {
          "friendlyNames": [
            // label objects representing
            // friendly names for the preset within range
          ]
        }
      },
      ...
    ]
  }
  "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": "StatesToRange",
        "states": ["{{STRING}}", ...],
        "range": {
          "minimumValue": {{NUMBER}},
          "maximumValue": {{NUMBER}}
        }
      },
      ...
    ]
  }
},
{
  "type": "AlexaInterface",
  "interface": "Alexa",
  "version": "3"
}

Object Parameters

Parameter	Description	Type
instance	The identifier of this instance of Alexa.RangeController 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 `SetRangeValue` and `AdjustRangeValue` directives.	boolean
configuration. supportedRange. minimumValue	The minimum value of the range this instance supports.	number
configuration. supportedRange. maximumValue	The maximum value of the range this instance supports.	number
configuration. supportedRange. precision	The amount by which the set value changes when iterating through the range. For example, if a user asks by voice to increase the value, but doesn't specify by how much, this value will be used.	number
configuration. presets	A list of objects describing values that can be invoked by name. For example, a `rangeValue` of `10` might be configured as the "high" preset.	list
configuration. presets[i]. rangeValue	The value within the range that has a named preset associated with it.	number
configuration. presets[i]. presetResources. friendlyNames	A list of label objects to describe the possible friendly names for the preset. Examples are available in the preset resources section of the Smart Home Skills Kit documentation.	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	Semantics 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: `SetRangeValue`: The identified `actions` should trigger the `SetRangeValue` directive with the specified `payload`. `AdjustRangeValue`: The identified `actions` should trigger the `AdjustRangeValue` directive with the specified `payload`.	string
semantics. actionMappings[i]. directive. payload	If `name` is `SetRangeValue`, this must be the `SetRangeValue` `payload` object that contains the `rangeValue` property and the corresponding value between the `minumumValue` and `maximumValue` of the `configuration.supportedRange`. If `name` is `AdjustRangeValue`, this must be the `AdjustRangeValue` `payload` object that contains the `rangeValueDelta` and `rangeValueDeltaDefault` fields.	object
stateMappings[i]. @type	Whether the identified each entry in `states` is mapped to a single value or a range of values. Accepted Values: `StatesToValue`: the state is mapped to a single value `StatesToRange`: The state is mapped to an inclusive range of values	string
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 single value mapped to the `states` if `@type` is `StatesToValue`. This value must be between the `minumumValue` and `maximumValue` of the `configuration.supportedRange`.	number
semantics. stateMappings[i]. range. minimumValue	The minimum value of the range mapped to the `states`, if `@type` is `StatesToRange`. The value of this field must be greater than or equal to `configuration.supportedRange.minimumValue`.	number
semantics. stateMappings[i]. range. maximumValue	The maximum value of the range mapped to the `states`, if `@type` is `StatesToRange`. The value of this field must be less than or equal to `configuration.supportedRange.maximumValue`.	number

Reportable state properties

rangeValue

Alexa.RangeController 3.0 defines the rangeValue property.

Sample Object

{
  "namespace": "Alexa.RangeController",
  "instance": "{{STRING}}",
  "name": "rangeValue",
  "value": {{NUMBER}},
  "timeOfSample": "{{STRING}}",
  "uncertaintyInMilliseconds": {{NUMBER}}
}

Object Parameters

Parameter	Description	Type
instance	The identifier of this instance of Alexa.RangeController on this endpoint.	string
value	The value of the `rangeValue` property. Accepted values fall between the asserted `minimumValue` and `maximumValue`.	number
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`.	number

Directives

SetRangeValue

AVS will send the SetRangeValue directive to instruct the device to set the specified value of the instance of Alexa.RangeController 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 SetRangeValue directive can't run, the device should send the ErrorResponse event instead.

Sample Message

{
  "directive": {
    "header": {
      "namespace": "Alexa.RangeController",
      "instance": "{{STRING}},
      "name": "SetRangeValue",
      "payloadVersion": "3",
      "messageId": "{{STRING}}",
      "correlationToken": "{{STRING}}"
    },
    "endpoint": {
      "endpointId": "{{STRING}}"
    }
    "payload": {
      "rangeValue": {{NUMBER}}
    }
  }
}

Message Parameters

Parameter	Description	Type
directive. header. instance	The identifier of this instance of Alexa.RangeController 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. rangeValue	The value to set this instance of Alexa.RangeController to on the specified endpoint.	number

AdjustRangeValue

AVS will send the AdjustRangeValue directive to instruct the device to increment the value of the instance of Alexa.RangeController 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 AdjustRangeValue directive can't run, the device should send the ErrorResponse event instead.

Sample Message

{
  "directive": {
    "header": {
      "namespace": "Alexa.RangeController",
      "instance": "{{STRING}},
      "name": "AdjustRangeValue",
      "payloadVersion": "3",
      "messageId": "{{STRING}}",
      "correlationToken": "{{STRING}}"
    },
    "endpoint": {
      "endpointId": "{{STRING}}"
    }
    "payload": {
      "rangeValueDelta": {{NUMBER}},
      "rangeValueDeltaDefault": {{BOOLEAN}}
    }
  }
}

Message Parameters

Parameter	Description	Type
directive. header. instance	The identifier of this instance of Alexa.RangeController 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. rangeValueDelta	The amount by which to adjust the value of this instance of Alexa.RangeController to on the specified endpoint. If the end user did not explicitly specify an amount, `precision` from the capability assertion is used.	number
directive. payload. rangeValueDeltaDefault	`true` if the user made an implicit adjustment, such as "Alexa, increase the fan speed". `false` if the user specified an explicit amount, such as "Alexa, increase the fan speed by 2".	boolean

Events

Alexa.RangeController does not define any events within its namespace. Instances of Alexa.RangeController 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.RangeController directives use the Response and ErrorResponse events.
Changes to Alexa.RangeController'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.RangeController's reportable state properties' values via the ReportState directive.

Additional resources

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

Last updated: Jan 22, 2021