Connection Management

After establishing an AWS IoT connection, your device must establish a connection with AIA using the connection topic's fromclient and fromservice sub-topics. Only then can your device exchange messages on any other AIA-specific MQTT topic to manifest an Alexa experience for end users.

AIA connections are maintained until closed by either the device or by AIA. While the connection is open, the device must remain subscribed to the directive and fromservice topics, as well as any other topics required by asserted capabilities (for example, the speaker topic, if the Speaker capability is asserted).

Note: Messages sent on the fromclient and fromservice topics are secured through AWS IAM permissions associated with your AWS account. The JSON data exchanged on them does not use AIA encryption, though it is secured through TLS over MQTT. Consequently, it also is not preceded by the common header.

Getting Started

AIA Envelope

Connection management is presently compatible with v1 of the AIA envelope.

Topic Management

To support connection messages, the device must participate in the fromclient and fromservice MQTT topics, which are nested under the connection topic.

fromclient Topic

Connect

The device sends the Connect message to AIA to establish a connection.

If AIA receives and attempts to process the message, it will reply with the Acknowledge message on the fromservice topic. This applies to both successes and failures.

Sample Message

{
  "header": {
    "name": "Connect",
    "messageId": "{{STRING}}"
  },
  "payload": {
    "awsAccountId": "{{STRING}}",
    "clientId": "{{STRING}}"
  }
}

Payload Parameters

Field Name Description Value Type
awsAccountId The AWS account ID that the device is connected to. This must be the same as the iot.awsAccountId declared during registration. string
clientId The AWS IoT clientId the device uses to connected to AWS IoT. This must be the same as the iot.clientId declared during registration. string

Disconnect

The device may choose to disconnect gracefully by sending the Disconnect message to AIA. AIA will not respond with any acknowledgement. This only terminates the AIA connection, not the AWS IoT connection.

The client ID of the device will be inferred from the fully qualified MQTT topic.

Note: AIA may also initiate disconnecting a device by sending a Disconnect message on the fromservice topic.

Sample Message

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

Payload Parameters

Field Name Description Value Type
code A code indicating the reason for disconnecting.

Accepted Values:
UNEXPECTED_SEQUENCE_NUMBER: A message with an unexpected sequence number was received. Opening a new connection should resolve this issue.
MESSAGE_TAMPERED: The unencrypted and decrypted sequence numbers of the common header do not match, indicating a potential replay attack.
ENCRYPTION_ERROR: There was an error encrypting or decrypting an AIA message using the shared secret.
GOING_OFFLINE: The device is going offline for any other reason.
string
description The device may optionally provide additional information about the reason for disconnecting for logging and troubleshooting. string

fromservice Topic

Acknowledge

AIA sends the Acknowledge message on the fromservice topic in response to a Connect message on the fromclient topic.

Sample Message

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

Payload Parameters

Field Name Description Value Type
connectMessageId The messageId from the Connect message, returned verbatim. string
code A code indicating the success or failure of the connection request.

Possible Values:
CONNECTION_ESTABLISHED: The device has been successfully connected to AIA and may begin exchanging message over other MQTT topics.
INVALID_ACCOUNT_ID: The awsAccountId provided in the Connect message is not valid. The device must correct the value before retrying.
INVALID_CLIENT_ID: The clientId provided in the Connect message is not valid. The device must correct the value before retrying.
API_VERSION_DEPRECATED: The API version in the fully qualified MQTT topic on which this message was sent has been deprecated. The device must use a more recent version, consistent with a successful registration.
UNKNOWN_FAILURE: An unexpected issue occurred that prevented AIA from opening the connection. This may be a server side failure, and the same Connect message may be retried.
string
description AIA may optionally provide additional information about the connection attempt for logging and troubleshooting. string

Disconnect

AIA may choose to disconnect a device gracefully by sending the Disconnect message. The device does not respond with any acknowledgement. This only terminates the AIA connection, not the AWS IoT connection.

The client ID of the device will be inferred from the fully qualified MQTT topic.

Note: The device may also initiate disconnecting from AIA by sending a Disconnect message on the fromclient topic.

Sample Message

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

Payload Parameters

Field Name Description Value Type
code A code indicating the reason for disconnecting.

Accepted Values:
UNEXPECTED_SEQUENCE_NUMBER: A message with an unexpected sequence number was received. Opening a new connection should resolve this issue.
MESSAGE_TAMPERED: The unencrypted and decrypted sequence numbers of the common header do not match, indicating a potential replay attack.
ENCRYPTION_ERROR: There was an error encrypting or decrypting a message using the shared secret. The device must register and acquire a new shared secret before attempting to reconnect.
API_VERSION_DEPRECATED: The API version of the connection is no longer supported. The device must re-register and specify a newer API version before attempting to reconnect.
string
description AIA may optionally provide additional information about the reason for disconnecting for logging and troubleshooting. string