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 |