System Capability Interface

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
  • AIA Envelope
  • Topic Management
  • Capability Assertion
• directive Topic
  • RotateSecret
  • SetAttentionState
  • Exception
• event Topic
  • SecretRotated
  • SynchronizeState
  • ExceptionEncountered
  • BufferStateChanged

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}}"
  }
}

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

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

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

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.

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": "SecretRotated",
    "messageId": "{{STRING}}"
  },
  "payload": {
    "eventSequenceNumber": {{LONG}},
    "microphoneSequenceNumber": {{LONG}}
  }
}

Payload Parameters

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

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

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