Event-Directive Control Plane

Control messages often need to communicate that an action must be taken at a certain location in the corresponding data stream. This communication is done through the use of a binary offset. Audio Data messages (as in the Speaker and Microphone capabilities) define a binary offset field in their Audio Stream Header that indicates the position of the message in the binary stream. Control messages that need to take effect at specific locations in a data stream will include the binary offset for the relevant stream.

There are two types of control messages:

• directives, which allow AIA to control the device and data streaming to it
• events, which allow the device to inform AIA of local activities, states, and changes

Note: Not all JSON messages that use the header/payload structure described below are part of capability interfaces, such as those pertaining to connection and capability assertion.

Directives

When a capability interface defines a directive and the device asserts support for that capability, AIA will send directive messages on the directive topic.

Individual directive MQTT messages comprise the common header and an AIA-encrypted JSON string.

The JSON string, defined by AIA envelope v1 in the structure below, may consist of multiple individual directives from one or more capability interfaces. The number of directives included in a single MQTT message is limited by the mqtt.message.maxSizeInBytes value provided by the device when asserting support for the required System capability.

Directives in the array are ordered and must be processed sequentially. If any directive cannot be successfully processed, the device must send the ExceptionEncountered event, referring to the 0-based index in this array in the message.index field of the payload.

Unexpected fields should be ignored without causing a device error state. The device must process each directive's fields that it does understand, discarding those fields it does not understand.

Message Structure

{
  "directives": [
    {
      "header": {
        "name": "{{STRING}}",
        "messageId": "{{STRING}}"
      },
      "payload": {{OBJECT}}
    },
    // additional directives
  ]
}

Message Parameters

Field Name	Description	Value Type
header	Metadata about the individual directive.	object
header.   name	The name of the directive, defined by the capability interface to which it belongs.	string
header.   messageId	A universally unique identifier (UUID) generated to the RFC 4122 specification.	string
payload	The substantive content of a message, defined by the capability interface for the given name. If the message doesn't define any payload contents, the entire field may be omitted or the object may be empty.	object

Events

When a capability interface defines an event and the device asserts support for that capability, the device will send event messages on the event topic.

Individual event MQTT messages comprise the common header and an AIA-encrypted JSON string.

The JSON string, defined by AIA envelope v1 in the structure below, may consist of multiple individual events from one or more capability interfaces. By batching events in a single MQTT message, the device can adhere to the rate limit guidelines.

Events in the array are ordered, and AIA will process them sequentially. If any individual event cannot be successfully processed or the overall event message is malformed, AIA will send the Exception directive.

Unexpected fields will be ignored.

Message Structure

{
  "events": [
    {
      "header": {
        "name": "{{STRING}}",
        "messageId": "{{STRING}}"
      },
      "payload": {{OBJECT}}
    },
    // additional events
  ]
}

Message Parameters

Field Name	Description	Value Type
header	Metadata about the individual event.	object
header.   name	The name of the event, defined by the capability interface to which it belongs.	string
header.   messageId	A universally unique identifier (UUID) generated to the RFC 4122 specification.	string
payload	The substantive content of a message, defined by the capability interface for the given name. If the message doesn't define any payload contents, the entire field may be omitted or the may be empty.	object