System Capability Interface

Note: Watch the replay of Alexa Live ‘22 on demand. Catch the latest on ambient intelligence, smart home, and AI.

The System capability comprises the mechanics that enable coordination between the device and AIA on fundamental system-level details and cross-capability processes.

Because it is a mandatory capability interface for all AIA devices, it is not explicitly listed as a dependency of other capabilities.

It defines messages on the directive and event topics.

Getting Started
directive Topic
event Topic

Getting Started

AIA Envelope

This capability interface is compatible with v1 of the AIA envelope.

Topic Management

To support System 1.0 messages, the device must participate in the directive and event MQTT topics.

Capability Assertion

To use the System 1.0 interface, the device must assert support through the Publish message on the capabilities topic.

Sample Object

{
  "type": "AisInterface",
  "interface": "System",
  "version": "1.0",
  "configurations": {
    "mqtt": {
      "message": {
        "maxSizeInBytes": {{LONG}}
      }
    },
    "firmwareVersion": "{{STRING}}",
    "locale": "{{STRING}}"
  }
}

Field Name	Description	Value Type
`mqtt`	Details about the on-device AWS IoT MQTT client implementation.	object
`mqtt.` `message`	Details about individual messages that the on-device AWS IoT MQTT client implementation can accept through any subscribed topic. Note: The details specified here do not restrict the attributes of messages that the device may compose and publish to any MQTT topic.	object
`mqtt.` `message.` `maxSizeInBytes`	The maximum size of a single MQTT message in bytes that the device can read from any subscribed MQTT topic. Accepted Values: `1500` - `128000`	long
`firmwareVersion`	The current firmware version of the device represented as a non-zero 32-bit number, type-cast as a string. Note: See the `SoftwareInfo` event in the AVS System interface for more information.	string
`locale`	The locale that the device is set to in BCP-47 format. This value determines the language in which the user's speech will be interpreted and in which TTS output will be generated. Accepted Values: All those listed in the locales configuration parameter of the AVS System interface.	string

`directive` Topic

RotateSecret

The RotateSecret directive instructs the device to change the shared secret used to encrypt and decrypt AIA messages, starting with the specified sequence numbers.

The device must respond with a SecretRotated event.

If the device is unable to change the shared secret for any reason, it must send the ExceptionEncountered event, populating the sequenceNumber and index fields with references to the failed RotateSecret directive.

Note: If the AIA connection ends before the SecretRotated event is sent, subsequent AIA connections must continue to use the old shared secret. If the AIA connection ends after the SecretRotated event is sent, subsequent AIA connections must use the new shared secret. This guidance must be followed regardless of whether the sequence number(s) provided in the directive are reached.

Sample Message

{
  "header": {
    "name": "RotateSecret",
    "messageId": "{{STRING}}"
  },
  "payload": {
    "newSecret": "{{STRING}}",
    "directiveSequenceNumber": {{LONG}},
    "speakerSequenceNumber": {{LONG}}
  }
}

Payload Parameters

Field Name	Description	Value Type
`newSecret`	The new base64-encoded shared secret that will be used to encrypt and decrypt AIA messages.	string
`directiveSequenceNumber`	The sequence number of the first message on the `directive` topic that will be encrypted with the new secret. All subsequent messages will be encrypted with the new secret.	long
`speakerSequenceNumber`	The sequence number of the first message on the `speaker` topic that will be encrypted with the new secret. All subsequent messages will be encrypted with the new secret. Note: This field will only be present if the device implements the Speaker capability.	long

SetAttentionState

The SetAttentionState directive instructs the device to manifest a user-visible change in the Alexa Attention System.

Sample Message

{
  "header": {
    "name": "SetAttentionState",
    "messageId": "{{STRING}}"
  },
  "payload": {
    "state": "{{STRING}}"
    "offset": {{LONG}}
  }
}

Payload Parameters

Field Name	Description	Value Type
`state`	Alexa's state that the device should manifest in a user-visible change. Possible Values: `IDLE`: No active interaction. `THINKING`: The user has completed a request, the microphone is closed, and a response is pending. No additional voice input is accepted in this state. `SPEAKING`: TTS is being played through the `speaker` topic. This does not apply to long-running content, such as audiobooks or Flash Briefing. `ALERTING`: An alert is being played, either through the `speaker` topic or rendered locally in offline mode. `NOTIFICATION_AVAILABLE`: A Notification is available to be played to the user. `DO_NOT_DISTURB`: The user has enabled Do Not Disturb mode.	string
`offset`	If the device implements the Speaker capability, this specifies the byte offset in the `speaker` topic's audio stream at which to set the attention state. If the field is omitted or the device has already passed the offset, the device should change attention state immediately. In addition, if the field is omitted, the device should discard any previously stored attention states with future offsets. Note: The value is inclusive and will be greater than or equal to `0`; it identifies the first byte of audio that should be played from the stream while displaying the new attention state.	long

Exception

When a server-detected error occurs, whether the result of a malformed event or too many requests, AIA will return a message to the device that includes an exception code and an optional description.

Note: A server-detected error does not imply that the AIA connection is in a bad state. The service will send a Disconnect message if it detects a bad connection state.

Sample Message

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

Payload Parameters

Field Name	Description	Value Type
`code`	The exception that occurred. Possible Values: `INVALID_REQUEST`: The message was malformed, and the device must update the request before trying again. `UNSUPPORTED_API`: The message was for an API the device failed to declare support for through a previous `Publish` capability assertion. `THROTTLING`: The device is sending messages too fast and must retry in accordance with the retry guidance. `INTERNAL_SERVICE`: Unknown internal service error; the device may resend the message, but there is no guaranteed behavior. `AIS_UNAVAILABLE`: AIA is unavailable, and the device may retry in accordance with the retry guidance.	string
`description`	An optionally populated field that provides additional information for logging and troubleshooting.	string

`event` Topic

SecretRotated

The SecretRotated event informs AIA that the device changed the shared secret used to encrypt and decrypt AIA messages, starting with the specified sequence numbers, in response to the RotateSecret directive.

This event itself must be encrypted with the old shared secret and must be the last message to use the old shared secret. All subsequent messages must use the new shared secret specified in the RotateSecret directive.

Sample Message

{
  "header": {
    "name": "SecretRotated",
    "messageId": "{{STRING}}"
  },
  "payload": {
    "eventSequenceNumber": {{LONG}},
    "microphoneSequenceNumber": {{LONG}}
  }
}

Payload Parameters

Field Name	Description	Value Type
`eventSequenceNumber`	The sequence number of the first message on the `event` topic that will be encrypted with the new secret. All subsequent messages will be encrypted with the new secret. This should be the next message after this `SecretRotated` event.	long
`microphoneSequenceNumber`	The sequence number of the first message on the `microphone` topic that will be encrypted with the new secret. All subsequent messages will be encrypted with the new secret. Note: This field will only be present if the device implements the Microphone capability.	long

SynchronizeState

The device must send the SynchronizeState event immediately on reconnecting to AIA, regardless of whether there have been local changes since the last connection.

Sample Message

{
  "header": {
    "name": "SynchronizeState",
    "messageId": "{{STRING}}"
  },
  "payload": {
    "speaker": {
      "volume": {{LONG}}
    },
    "alerts": {
      "allAlerts": ["{{STRING}}", ...]
    }
  }
}

Payload Parameters

Field Name	Description	Value Type
`speaker`	Details about the speaker state. Only required if the device implements the Speaker capability.	object
`speaker.` `volume`	The volume level set, on a scale of `0` (mute) to `100` (maximum output). Note: This field is required only if the device persists the volume locally. If the field is omitted, AIA will use a cached value and send a `SetVolume` directive.	long
`alerts`	Details about the alert state. Only required if the device implements the Alerts capability.	object
`alerts.` `allAlerts`	An unordered list of alert tokens persisted locally on the device, previously set through the `SetAlert` directive.	list
`alerts.` `allAlerts[i]`	The alert token. Note: Tokens for the following alerts should have already been removed from local storage and therefore should not be included: Alerts that were played and stopped while the device was offline. Alerts that failed to play while the device was powered off, which were scheduled to play more than 30 minutes before the device was powered back on.	string

ExceptionEncountered

The device must send the ExceptionEncountered event whenever it detects an error preventing it from successfully processing a message sent by AIA.

Sample Message

{
  "header": {
    "name": "ExceptionEncountered",
    "messageId": "{{STRING}}"
  },
  "payload": {
    "error": {
      "code": "{{STRING}}",
      "description": "{{STRING}}"
    },
    "message": {
      "topic": "{{STRING}}",
      "sequenceNumber": {{LONG}},
      "index": {{LONG}}
    }
  }
}

Payload Parameters

Field Name	Description	Value Type
`error`	Details about the error.	object
`error.` `code`	The exception that occurred. Accepted Values: `MALFORMED_MESSAGE`: The message was malformed, such as missing required fields, wrong value types, or non-conforming JSON structure. `INTERNAL_ERROR`: Unknown or miscellaneous device-side error in processing the message. Note: Undocumented or unexpected fields in directives should not trigger device-side errors.	string
`error.` `description`	An optional field that provides additional information for logging and troubleshooting.	string
`message`	Details about the message, if the error resulted from processing a message sent by AIA. This object may be omitted if the error is not directly related to a message sent by AIA.	object
`message.` `topic`	The topic on which the triggering message was sent. Accepted Values: `directive`, `speaker`, `connection/fromservice`, `capabilities/acknowledge` Note: If the error occurred when attempting to process a message on the `speaker` topic, AIA infers that the device is unable to gracefully resume playback without a new `OpenSpeaker` directive. In this case, a `SpeakerClosed` event does not need to accompany this `ExceptionEncountered` event.	string
`message.` `sequenceNumber`	An optional field that provides the sequence number of the MQTT message sent by AIA that triggered the error. Note:: This field must be omitted if `message.topic` is `connection/fromservice`.	long
`message.` `index`	An optional field that provides the index of the message that triggered the error. All indices are 0-indexed. If `message.topic` is `directive`, this is the index of the directive in the `directives` array. If `message.topic` is `speaker`, this is the index of the binary stream message within the full MQTT message.	long

BufferStateChanged

When streaming audio to the user and the speaker is open, the device must send the BufferStateChanged event when its buffer is empty, has overflowed, or is at risk of one of these states.

This event advises AIA that the audio stream message rate needs to be sped up or slowed down, in order to make sure that the device is able to deliver an optimal audio playback experience to the user.

When any of the following conditions is met, the event must be sent immediately:

The audio buffer is empty (UNDERRUN).
The audio buffer is full, resulting in dropped messages (OVERRUN).
The amount of data in the audio buffer has decreased, crossing the threshold specified in the audioBuffer.reporting.underrunWarningThreshold configuration parameter of the Speaker capability assertion (UNDERRUN_WARNING).
The amount of data in the audio buffer has increased, crossing the threshold specified in the audioBuffer.reporting.overrunWarningThreshold configuration parameter of the Speaker capability assertion (OVERRUN_WARNING).

Notes:

If the speaker is closed, the device should not send this event, even if data is being streamed on the speaker topic. In that case, the device should continue filling the buffer, with the oldest data being dropped, as necessary.
The device should only send this event in the case of moving from a healthier state to a more degraded state. For example, the device should not send this event if the device previously sent an UNDERRUN_WARNING or UNDERRUN state, AIA sped up the message rate, and the amount of data in the buffer increased, crossing the UNDERRUN_WARNING threshold back into a normal buffer state.
The device may not always know that the end of an audio stream is approaching. When there is no more audio being streamed and the buffer begins to approach empty, AIA expects that the device will send the UNDERRUN_WARNING state. However, if the device does know that the end of the audio stream is approaching and that is why it crossed the UNDERRUN_WARNING threshold, sending this event may be skipped.
If the buffer has emptied, but the device received a CloseSpeaker directive with an offset that corresponds to the last audio stream message sent on the speaker topic, the device should not send this event with the UNDERRUN state.
If the device sent the this event with the OVERRUN state, AIA will resend all messages on the speaker topic, starting with the specified sequenceNumber, which is the first speaker message the device had to drop.

Sample Message

{
  "header": {
    "name": "BufferStateChanged",
    "messageId": "{{STRING}}"
  },
  "payload": {
    "state": "{{STRING}}",
    "message": {
      "topic": "{{STRING}}",
      "sequenceNumber": {{LONG}}
    }
  }
}

Payload Parameters

Field Name	Description	Value Type
`state`	The degraded state the buffer transitioned to. Accepted Values: `UNDERRUN`: The buffer is empty. `OVERRUN`: The buffer is full, and messages are being dropped without being played. `UNDERRUN_WARNING`: The amount of data in the buffer has fallen below the `audioBuffer.reporting.underrunWarningThreshold` value. `OVERRUN_WARNING`: The amount of data in the buffer has exceeded the `audioBuffer.reporting.overrunWarningThreshold` value.	string
`message`	Details about the message that coincided with the buffer state change.	object
`message.` `topic`	The topic on which the coinciding message was sent. Accepted Values: `speaker`	string
`message.` `sequenceNumber`	The sequence number of the MQTT message sent by AIA that coincided with the buffer state change. In the case of `OVERRUN`, this is the sequence number of the first message the device had to drop.	long

System Capability Interface

Getting Started

AIA Envelope

Topic Management

Capability Assertion

directive Topic

RotateSecret

SetAttentionState

Exception

event Topic

SecretRotated

SynchronizeState

ExceptionEncountered

BufferStateChanged

`directive` Topic

`event` Topic