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

• Alexa.ToggleController
• Alexa.RangeController
• Alexa.ModeController

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
• Capability Assertion
• Semantic Annotation

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

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

Notes:

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