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 of Wash.Cycle through an interaction, you set the nonControllable filed to false for the Wash.Cycle instance of ModeController.
By contrast, because a user can only query but not control the mode value of Wash.Progress, you set nonControllable to true for the Wash.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 the capabilities object, it must contain at least one of the actionMappings and stateMappings lists.
A single stateMappings list may combine both StatesToValue and StatesToRange objects, provided that the identified value and range don't overlap.
The same actions value may not appear in multiple objects in the same actionMappings list. Similarly, the same states value may not appear in multiple objects in the same stateMappings 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 value `StatesToRange`: 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

Alexa.ModeController API reference
Alexa.RangeController API reference
Alexa.ToggleController API reference

Last updated: Feb 01, 2021

Generic Controller Interfaces

Multiple instances

Multiple instance syntax

Semantics

Semantics syntax

Related topics