Lifecycle events - AWS IoT Core
Connect/Disconnect eventsSubscribe/Unsubscribe events

Lifecycle events

AWS IoT can publish lifecycle events on the MQTT topics. These events are available by default and they can't be disabled.

Note

Lifecycle messages might be sent out of order. You might receive duplicate messages.

Connect/Disconnect events

Note

With AWS IoT Device Management fleet indexing, you can search for things, run aggregate queries, and create dynamic groups based on thing Connect/Disconnect events. For more information, see Fleet indexing.

AWS IoT publishes a message to the following MQTT topics when a client connects or disconnects:

  • $aws/events/presence/connected/clientId – A client connected to the message broker.

  • $aws/events/presence/disconnected/clientId – A client disconnected from the message broker.

The following is a list of JSON elements that are contained in the connection/disconnection messages published to the $aws/events/presence/connected/clientId topic.

clientId

The client ID of the connecting or disconnecting client.

Note

Client IDs that contain # or + do not receive lifecycle events.

clientInitiatedDisconnect

True if the client initiated the disconnect. Otherwise, false. Found in disconnect messages only.

disconnectReason

The reason why the client is disconnecting. Found in disconnect messages only. The following table contains valid values and whether the broker will send Last Will and Testament (LWT) messages when the disconnection occurs.

Disconnect reason Description The broker will send the LWT messages
AUTH_ERROR The client failed to authenticate or authorization failed. Yes. If the device has an active connection before receiving this error.
CLIENT_INITIATED_DISCONNECT The client indicates that it will disconnect. The client can do this by sending either a MQTT DISCONNECT control packet or a Close frame if the client is using a WebSocket connection. No.
CLIENT_ERROR The client did something wrong that causes it to disconnect. For example, a client will be disconnected for sending more than 1 MQTT CONNECT packet on the same connection or if the client attempts to publish with a payload that exceeds the payload limit. Yes.
CONNECTION_LOST The client-server connection is cut off. This can happen during a period of high network latency or when the internet connection is lost. Yes.
DUPLICATE_CLIENTID The client is using a client ID that is already in use. In this case, the client that is already connected will be disconnected with this disconnect reason. Yes.
FORBIDDEN_ACCESS The client is not allowed to be connected. For example, a client with a denied IP address will fail to connect. Yes. If the device has an active connection before receiving this error.
MQTT_KEEP_ALIVE_TIMEOUT If there is no client-server communication for 1.5x of the client's keep-alive time, the client is disconnected. Yes.
SERVER_ERROR Disconnected due to unexpected server issues. Yes.
SERVER_INITIATED_DISCONNECT Server intentionally disconnects a client for operational reasons. Yes.
THROTTLED The client is disconnected for exceeding a throttling limit. Yes.
WEBSOCKET_TTL_EXPIRATION The client is disconnected because a WebSocket has been connected longer than its time-to-live value. Yes.
CUSTOMAUTH_TTL_EXPIRATION The client is disconnected because it has been connected longer than the time-to-live value of its custom authorizer. Yes.
eventType

The type of event. Valid values are connected or disconnected.

ipAddress

The IP address of the connecting client. This can be in IPv4 or IPv6 format. Found in connection messages only.

principalIdentifier

The credential used to authenticate. For TLS mutual authentication certificates, this is the certificate ID. For other connections, this is IAM credentials.

sessionIdentifier

A globally unique identifier in AWS IoT that exists for the life of the session.

timestamp

An approximation of when the event occurred.

versionNumber

The version number for the lifecycle event. This is a monotonically increasing long integer value for each client ID connection. The version number can be used by a subscriber to infer the order of lifecycle events.

Note

The connect and disconnect messages for a client connection have the same version number.

The version number might skip values and is not guaranteed to be consistently increasing by 1 for each event.

If a client is not connected for approximately one hour, the version number is reset to 0. For persistent sessions, the version number is reset to 0 after a client has been disconnected longer than the configured time-to-live (TTL) for the persistent session.

A connect message has the following structure.

{
    "clientId": "186b5",
    "timestamp": 1573002230757,
    "eventType": "connected",
    "sessionIdentifier": "a4666d2a7d844ae4ac5d7b38c9cb7967",
    "principalIdentifier": "12345678901234567890123456789012",
    "ipAddress": "192.0.2.0",
    "versionNumber": 0
}

A disconnect message has the following structure.

{
    "clientId": "186b5",
    "timestamp": 1573002340451,
    "eventType": "disconnected",
    "sessionIdentifier": "a4666d2a7d844ae4ac5d7b38c9cb7967",
    "principalIdentifier": "12345678901234567890123456789012",
    "clientInitiatedDisconnect": true,
    "disconnectReason": "CLIENT_INITIATED_DISCONNECT",
    "versionNumber": 0
}

Handling client disconnections

The best practice is to always have a wait state implemented for lifecycle events, including Last Will and Testament (LWT) messages. When a disconnect message is received, your code should wait a period of time and verify a device is still offline before taking action. One way to do this is by using SQS Delay Queues. When a client receives a LWT or a lifecycle event, you can enqueue a message (for example, for 5 seconds). When that message becomes available and is processed (by Lambda or another service), you can first check if the device is still offline before taking further action.

Subscribe/Unsubscribe events

AWS IoT publishes a message to the following MQTT topic when a client subscribes or unsubscribes to an MQTT topic:

$aws/events/subscriptions/subscribed/clientId

or 

$aws/events/subscriptions/unsubscribed/clientId

Where clientId is the MQTT client ID that connects to the AWS IoT message broker.

The message published to this topic has the following structure:

{
    "clientId": "186b5",
    "timestamp": 1460065214626,
    "eventType": "subscribed" | "unsubscribed",
    "sessionIdentifier": "00000000-0000-0000-0000-000000000000",
    "principalIdentifier": "000000000000/ABCDEFGHIJKLMNOPQRSTU:some-user/ABCDEFGHIJKLMNOPQRSTU:some-user",
    "topics" : ["foo/bar","device/data","dog/cat"]
}

The following is a list of JSON elements that are contained in the subscribed and unsubscribed messages published to the $aws/events/subscriptions/subscribed/clientId and $aws/events/subscriptions/unsubscribed/clientId topics.

clientId

The client ID of the subscribing or unsubscribing client.

Note

Client IDs that contain # or + do not receive lifecycle events.

eventType

The type of event. Valid values are subscribed or unsubscribed.

principalIdentifier

The credential used to authenticate. For TLS mutual authentication certificates, this is the certificate ID. For other connections, this is IAM credentials.

sessionIdentifier

A globally unique identifier in AWS IoT that exists for the life of the session.

timestamp

An approximation of when the event occurred.

topics

An array of the MQTT topics to which the client has subscribed.

Note

Lifecycle messages might be sent out of order. You might receive duplicate messages.