Capability Primitives
AVS defines a special kind of capability interface called a "capability primitive". Unlike typical interfaces, like Alerts or SpeechRecognizer, primitives allow the device to implement the same capability interface multiple times under different instance names.
The three capability primitives include
They enable the creation of new reporting and control experiences for end users, without requiring a specialized Alexa-defined capability with preconfigured semantics.
For example, your device might be a laundry machine with a wash cycle selector and a progress indicator. Both the wash cycle selector and the progress indicator might best be modeled as modes. The Alexa.ModeController capability primitive allows the one laundry machine to implement the primitive as two instances: For example, once as Wash.Cycle and once as Wash.Progress.
instance field
Typical capabilities can be uniquely identified by the namespace field value. This appears in the header objects of events, directives, and generic context entries, as well as in reportable state property objects. When asserting support through Alexa.Discovery, the equivalent of the namespace field is the interface field.
Instances of capability primitives must be identified by an additional instance field.
For example, continuing with the laundry machine scenario from the introduction, when a device uses Alexa.Discovery to assert support for Alexa.ModeController for the wash cycle selector, it includes a capabilities object with a Wash.Cycle value for the instance field. To assert support for Alexa.ModeController for the progress indicator, it includes a capabilities object with a Wash.Progress value for the instance field.
Whenever Alexa sends directives to the device, the header will include Alexa.ModeController as the namespace and then either Wash.Cycle or Wash.Progress as the instance.
Whenever the device sends the mode state property's value to Alexa, it will include Wash.Cycle or Wash.Progress in the instance field of the property object, alongside Alexa.ModeController as the namespace value.
Capability Assertion
Each object defines its own specific configurations and parameters for how the state properties can be reported and set.
Continuing with the laundry machine scenario, the user may control the mode of Wash.Cycle through voice or an app interaction, resulting in a directive from Alexa to the device. Consequently, nonControllable may be set to false when the device asserts support for the Wash.Cycle instance of Alexa.ModeController.
By contrast, the mode value of Wash.Progress may be queryable by the user, but not controllable. For example, the user could say "Alexa, what's the progress of my laundry?", but not "Alexa, set the laundry machine to rinse.", once a cycle is already underway. Consequently, nonControllable may be set to true when the device asserts support for the Wash.Progress instance of Alexa.ModeController.
Similarly, each instance's capability assertion object may define its own named modes, with its own assets and labels, informing Alexa of what words and phrases to listen for to query or set state property values for the instance.
Semantic Annotation
To provide intuitive experiences for end users, capability primitives offer devices the ability to map specific utterances to the behaviors and states of capability instances.
For example, if device implements an instance of Alexa.RangeController on behalf of an endpoint for which concepts like "open" and "closed" apply, it can declare which range values map to each of these states, as well as define what value should be set when the user asks Alexa to "open" or "close" the endpoint.
When the device declares endpoints' capabilities through Alexa.Discovery, it includes any semantic annotations for a capability primitive in the corresponding capabilities object by adding a semantics object.
At a high level, semantic annotations enable two categories of experiences, with corresponding representations in the API surface:
- actions or instructions (such as "Alexa, open the blinds."), which result in directives to the device to control the specified endpoint
- state inquiries (such as "Alexa, are the blinds open?"), which Alexa correlates with values reported through state properties
| End-User Utterance | JSON Identifier | @type Value |
|---|---|---|
| "open {endpoint}" | Alexa.Actions.Open |
ActionsToDirective |
| "close {endpoint}" | Alexa.Actions.Close |
|
| "raise {endpoint}" | Alexa.Actions.Raise |
|
| "lower {endpoint}" | Alexa.Actions.Lower |
|
| "is {endpoint} open" | Alexa.States.Open |
StatesToValue and StatesToRange |
| "is {endpoint} closed" | Alexa.States.Closed |
The documentation for each capability primitive describes the specific manifestation of the semantics object that applies. The field appears in the capabilities object for the endpoint implementing an instance of the primitive. Overall, the structure of the object is as follows:
"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 indicates that the user's utterance is mapped 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 capability primitive 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 capability primitive in which this semantics object is being declared, 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 is mapped to a single valueStatesToRange: The state is mapped 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 |
Notes:
- The
semanticsobject is optional, but if included in thecapabilitiesobject, it must contain at least one of theactionMappingsandstateMappingslists. - A single
stateMappingslist may combine bothStatesToValueandStatesToRangeobjects, provided that the identifiedvalueandrangedo not overlap. - The same
actionsvalue may not appear in multiple objects in the sameactionMappingslist. Similarly, the samestatesvalue may not appear in multiple objects in the samestateMappingslist.
