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.