Generic Controller Interfaces
Generic controller interfaces are general-purpose interfaces that you can use to model different components for your implementation of the Alexa Voice Service (AVS).
The AVS APIs include three generic controllers:
- ModeController – Models properties of a device that you can set to one of a list of values.
- RangeController – Models properties of a device that you can set to one of a range of values.
- ToggleController – Models properties of a device that you can set to on or off.
For most scenarios, choose the most specific controller available to model components of your devices, because the more specific the controller, the more natural the utterances are for your user. However, generic controllers provide some benefits not available with more specific controllers:
- Multiple instances – Create multiple instances of a controller for a single device.
- Semantics – Semantics offer devices the ability to map specific utterances to the behaviors and states of controller instances.
Multiple instances
Multiple instances enable a device to implement multiple instances of the same controller. For example, your device might be a laundry machine with a wash cycle selector and a progress indicator. Given that both the wash cycle selector and the progress indicator would likely have a list of possible values. The ModeController allows the one laundry machine to implement the controller as two instances, for example, a Wash.Cycle
instance and a Wash.Progress
instance.
Multiple instance syntax
Declare your device support for various AVS interfaces with the namespace
field value in the header
objects of events, directives, and generic context entries, and reportable state property objects. When you declare support for an instance of a generic controller through Alexa.Discovery, the equivalent of the namespace
field is the interface
field.
Declare individual instances of a generic controller through the instance
field. For example, in the laundry machine scenario, when Alexa sends directives to the device, the header includes Alexa.ModeController
as the namespace
and then either Wash.Cycle
or Wash.Progress
as the instance
. When the device sends the mode
value to Alexa, it includes Wash.Cycle
and Wash.Progress
in the instance
fields of the property object.
Use the nonControllable
field to specify whether a user can control the mode
of a given instance:
- For example, because a user controls the
mode
ofWash.Cycle
through an interaction, you set thenonControllable
filed tofalse
for theWash.Cycle
instance of ModeController. - By contrast, because a user can only query but not control the
mode
value ofWash.Progress
, you setnonControllable
totrue
for theWash.Progress
instance of ModeController.
Semantics
In addition to multiple instance support, generic controllers offer devices the ability to map specific utterances to the behaviors and states of controller instances.
Consider an example where a device implements an instance of RangeController with states of "open" and "closed." The device can declare which values within the range map to each of these states and define what value to set when the user asks Alexa to "open" or "close" the device.
Semantics enable two categories of experiences:
- Actions or instructions, such as "Alexa, open the blinds."
- State inquiries, such as "Alexa, are the blinds open?"
To implement semantics, map your actions and states for your scenarios. Map them in the semantics
object within the capabilities
object for each instance of your controller.
Semantics syntax
- The
semantics
object is optional, but if included in thecapabilities
object, it must contain at least one of theactionMappings
andstateMappings
lists. - A single
stateMappings
list may combine bothStatesToValue
andStatesToRange
objects, provided that the identifiedvalue
andrange
don't overlap. - The same
actions
value may not appear in multiple objects in the sameactionMappings
list. Similarly, the samestates
value may not appear in multiple objects in the samestateMappings
list.
Example object
The following example shows the syntax for a semantics
object:
"semantics": { "actionMappings": [ { "@type": "ActionsToDirective", "actions": ["{{STRING}}", ...], "directive": { "name": "{{STRING}}", "payload": {{OBJECT}} } }, ... ], "stateMappings": [ { "@type": "StatesToValue", "states": ["{{STRING}}", ...], "value": {{POLYMORPHIC}} }, { "@type": "StatesToRange", "states": ["{{STRING}}", ...], "range": { "minimumValue": {{LONG}}, "maximumValue": {{LONG}} } }, ... ] }
Object parameters
Parameter | Description | Type |
---|---|---|
actionMappings | A list of objects representing mappings between user utterances and the corresponding directives. | list |
actionMappings[i]. @type |
For actionMappings , @type is always ActionsToDirective .This parameter maps a user utterance to a specific directive payload. |
string |
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 |
actionMappings[i]. directive. name |
The name of the directive as defined in the namespace of the controller in which this semantics object is being declared.
|
string |
actionMappings[i]. directive. payload |
The payload of the directive as defined in the namespace of the controller declaring the semantics object, with the values that correspond to the desired state specified.
|
object |
stateMappings | A list of objects representing mappings between user utterances and state property values of the capability instance for the endpoint. | list |
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 maps to a single valueStatesToRange : The state maps to an inclusive range of values, applicable only to Alexa.RangeController
|
string |
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 |
stateMappings[i]. value |
The single value mapped to the states , if @type is StatesToValue .The value type of this field is the same as the value of the corresponding reportable state property of the capability interface.
|
various |
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 the configuration.supportedRange.minimumValue of the capabilities object for this instance of Alexa.RangeController.
|
long |
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 the configuration.supportedRange.maximumValue of the capabilities object for this instance of Alexa.RangeController.
|
long |
Related topics
- Alexa.ModeController API reference
- Alexa.RangeController API reference
- Alexa.ToggleController API reference
Last updated: Feb 01, 2021