Alexa.RangeController Interface

The RangeController interface enables your skill to model components of an endpoint that are represented by numbers within a minimum and maximum range. You can include multiple instances of a RangeController on a single endpoint, as long as they have unique values in the instance and friendlyNames fields.

RangeController is highly configurable and enables you to model many different kinds of settings for many different kinds of devices. For some devices, the following interfaces might be a better fit:

Use one of these more specific interfaces if it's appropriate for your device.

Discovery response

All smart home skills must send a discovery response (Discover.Response) that describes the devices associated with the customer's account.

Example discovery response

The following example shows a discovery response for a smart home skill that implements the RangeController interface.

{
  "event": {
    "header": {
      "messageId": "0a29824b-9299-4d55-b0c3-1d96ecfae81e",
      "name": "Discover.Response",
      "namespace": "Alexa.Discovery",
      "payloadVersion": "3"
    },
    "payload": {
      "endpoints": [
        {
          "endpointId": "TowerFan-001",
          "description": "Device description for the customer",
          "displayCategories": [
            "OTHER"
          ],
          "friendlyName": "Basement Fan",
          "manufacturerName": "Example Manufacturer",
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.RangeController",
              "version": "3",
              "instance": "TowerFan.Speed",
              "capabilityResources": {
                "friendlyNames": [
                  {
                    "@type": "asset",
                    "value": {
                      "assetId": "Alexa.Setting.FanSpeed"
                    }
                  }
                ]
              },
              "properties": {
                "supported": [
                  {
                    "name": "rangeValue"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              },
              "configuration": {
                "supportedRange": {
                  "minimumValue": 1,
                  "maximumValue": 10,
                  "precision": 1
                },
                "presets": [
                  {
                    "rangeValue": 10,
                    "presetResources": {
                      "friendlyNames": [
                        {
                          "@type": "asset",
                          "value": {
                            "assetId": "Alexa.Value.Maximum"
                          }
                        },
                        {
                          "@type": "asset",
                          "value": {
                            "assetId": "Alexa.Value.High"
                          }
                        },
                        {
                          "@type": "text",
                          "value": {
                            "text": "Highest",
                            "locale": "en-US"
                          }
                        }
                      ]
                    }
                  }
                ]
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa",
              "version": "3"
            }
          ]
        }
      ]
    }
  }
}

Discovery response fields

The following table describes the fields that are specific to the discovery response for devices that implement the RangeController interface.

Field Description Type
instance Required. A unique identifier for this instance of the RangeController interface. string that contains letters or numbers, spaces or the following special characters: _ - = # ; : ? @ &
capabilityResources Required. A capabilityResources object specifying the names that customers can use for VUI and GUI interactions. object
supportedRange Required. An object specifying the configuration of the range supported by the component of the device. object
supportedRange.minimumValue Required. The minimum value that is supported in the range. number
supportedRange.maximumValue Required. The maximum value that is supported in the range. number
supportedRange.precision Required. The smallest adjustment that can be made to the value. The value for this field must be greater than zero. The difference between supportedRange.maximumValue and supportedRange.minimumValue should be an integer multiple of this value. number
unitOfMeasure Optional. The unit of measurement for specifying minimumValue, maximumValue, precision, and value for the range. These are specified as a reference to the units catalog. string
presets Optional. An array of preset objects. A preset is an option that allows customers to specify a preset value instead of a numeric quantity. For example, "Alexa, set the toaster temperature to medium" instead of "set the toaster temperature to 50%". SetRangeValue will send a numeric rangevalue even if the customer specifies a preset value. object array
preset.rangeValue Required for presets. The value for the preset setting. number
preset.presetResources Required for presets. A PresetResources object specifying the names that customers can use for VUI and GUI interactions. object

PresetResources and capabilityResources objects

For more information on PresetResources and capabilityResources objects, see Resources and Assets.

Directives

The RangeController interface supports directives to set and adjust the value within the range, and to query the current value. The following example is a query utterance:

User: Alexa, what is the bedroom fan speed?

SetRangeValue

The following are example utterances that result in a SetRangeValue directive.

User: Alexa, set the bedroom fan speed to 7.
User: Alexa, set the fan speed on the bedroom fan to maximum.

The following example shows a SetRangeValue directive.

{
  "directive": {
    "header": {
      "namespace": "Alexa.RangeController",
      "instance": "TowerFan.Speed",
      "name": "SetRangeValue",
      "payloadVersion": "3",
      "messageId": "1bd5d003-31b9-476f-ad03-71d471922820",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<an OAuth2 bearer token>"
      },
      "endpointId": "TowerFan-001",
      "cookie": {}
    },
    "payload": {
      "rangeValue": 7
    }
  }
}

Payload fields

The following table describes the fields in the payload of a SetRangeValue directive.

Field Description Type
rangeValue The value to set for this instance of the RangeController. number

AdjustRangeValue

The following are example utterances that result in an AdjustRangeValue directive.

User: Alexa, turn up the bedroom fan speed.
User: Alexa, decrease the fan speed on the bedroom fan by 3.

The following example shows an AdjustRangeValue directive.

{
  "directive": {
    "header": {
      "namespace": "Alexa.RangeController",
      "instance": "TowerFan.Speed",
      "name": "AdjustRangeValue",
      "payloadVersion": "3",
      "messageId": "1bd5d003-31b9-476f-ad03-71d471922820",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<an OAuth2 bearer token>"
      },
      "endpointId": "TowerFan-001",
      "cookie": {}
    },
    "payload": {
      "rangeValueDelta": -3,
      "rangeValueDeltaDefault": false
    }
  }
}

Payload fields

The following table describes the fields in the payload of an AdjustRangeValue directive.

Field Description Type
rangeValueDelta The requested change in value, represented by a positive or negative number.

For example, a starting value of 100 and a rangeValueDelta of -3 results in a final value of 97.

Defaults to precision when the user does not specify the amount by which to adjust the value.
number
rangeValueDeltaDefault A flag that indicates whether the value in the rangeValueDelta field was explicitly specified by the user.

When this is false, the value was explicitly specified by the user.

When this is true, the value is the precision value specified during discovery.
Boolean

Properties and events

When the state of a range value changes, send a state report with a rangeValue property. You must also include the instance to specify which RangeController of the endpoint you are reporting state for.

Property name Description Type
rangeValue The current value of this instance of the RangeController. number

Supported Values for unitOfMeasure

The following are supported values for unitOfMeasure:

  • Alexa.Unit.Weight.Pounds
  • Alexa.Unit.Weight.Ounces
  • Alexa.Unit.Mass.Kilograms
  • Alexa.Unit.Mass.Grams
  • Alexa.Unit.Percent
  • Alexa.Unit.Volume.Gallons
  • Alexa.Unit.Volume.Pints
  • Alexa.Unit.Volume.Quarts
  • Alexa.Unit.Volume.Liters
  • Alexa.Unit.Volume.CubicMeters
  • Alexa.Unit.Volume.CubicFeet
  • Alexa.Unit.Distance.Yards
  • Alexa.Unit.Distance.Inches
  • Alexa.Unit.Distance.Meters
  • Alexa.Unit.Distance.Feet
  • Alexa.Unit.Distance.Miles
  • Alexa.Unit.Distance.Kilometers
  • Alexa.Unit.Angle.Degrees
  • Alexa.Unit.Angle.Radians
  • Alexa.Unit.Temperature.Degrees
  • Alexa.Unit.Temperature.Celsius
  • Alexa.Unit.Temperature.Fahrenheit
  • Alexa.Unit.Temperature.Kelvin

ErrorResponse

You should respond with an error when you cannot complete the customer request for some reason. See Alexa.ErrorResponse for more information.