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
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
do not 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.