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 publish
and acknowledge
MQTT topics, which are nested under the capabilities
topic.
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 theAcknowledge
message on thefromservice
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 |
acknowledge
Topic
Acknowledge
AIA sends the Acknowledge
message on the acknowledge
topic in response to a Publish
message on the 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 |