Capability Assertion

A "capability" or "capability interface" is a set of messages and mechanics that enables some functionality. For example, the Speaker capability defines events, directives, and use of the speaker MQTT topic.

A device must explicitly assert its support for each capability that it uses, including the always-required System capability.

Getting Started

AIA Envelope

Asserting capabilities requires v1 of the AIA envelope.

Topic Management

To support capability assertion, the device must participate in the capabilities/publish and capabilities/acknowledge MQTT topics, which are nested under the capabilities topic.

capabilities/publish Topic

Publish

The device must send the Publish message to inform AIA of which capability interfaces it supports.

The following principles determine when to send this message:

  • The device may only send the Publish message immediately after receiving the Acknowledge message on the connection/fromservice topic. If it is sent after any other message, AIA will reject it.
  • After the first connection to AIA, the device must send the initial set of capabilities.
  • If capabilities have changed, the device must re-establish a connection to AIA and send an updated set of capabilities.

Note: The Publish message must always include the full set of capabilities that the device supports. Partial updates will result in an error state or may be rejected.

Sample Message

{
  "header": {
    "name": "Publish",
    "messageId": "{{STRING}}"
  },
  "payload": {
    "capabilities": [
      {
        "type": "AisInterface",
        "interface": "{{STRING}}",
        "version": "{{STRING}}",
        "configurations": {
          ...
        }
      },
      ...
    ]
  }
}

Payload Parameters

Field Name Description Value Type
capabilities A list of capability assertion objects, as defined in the "Capability Assertion" section of each interface's reference documentation.

Note: An object for the System capability is required. 		list
capabilities[i].
  interface		 The name of the capability.

Accepted Values: System, Speaker, Microphone, Alerts, Clock 		string
capabilities[i].
  version		 The major.minor version of the capability. string
capabilities[i].
  configurations		 Any configuration parameters defined by the capability. Whether this object and any fields within are required depends on the definition specified in the "Capability Assertion" section of the reference document for the interface. object

capabilities/acknowledge Topic

Acknowledge

AIA sends the Acknowledge message on the capabilities/acknowledge topic in response to a Publish message on the capabilities/publish topic.

Sample Message

{
  "header": {
    "name": "Acknowledge",
    "messageId": "{{STRING}}"
  },
  "payload": {
    "publishMessageId": "{{STRING}}",
    "code": "{{STRING}}",
    "description": "{{STRING}}"
  }
}

Payload Parameters

Field Name Description Value Type
publishMessageId The messageId from the Publish message, returned verbatim. string
code A code indicating the success or failure of the capability assertion.

Possible Values:
CAPABILITIES_ACCEPTED: AIA has accepted the list of asserted capabilities. The device may begin exchanging messages with AIA on those capabilities.
CAPABILITIES_REJECTED: AIA has rejected the list of asserted capabilities. The device must change the Publish message and retry, based on details provided in the description field. The device may still use capabilities that were previously successfully asserted. 		string
description In case of error (CAPABILITIES_REJECTED), AIA will provide additional information about the cause, such as missing parameters or invalid values. string