Device connectivity status queries

AWS IoT Fleet Indexing supports individual device connectivity querying, allowing you to efficiently retrieve connectivity status and related metadata for specific devices. This feature complements existing fleet-wide indexing and querying capabilities.

How it works

Device connectivity query support can be used for optimized single-device connectivity status retrieval. This API provides low-latency, high-throughput access to the most recent device-specific connectivity information. Once you enable connectivity indexing you will have access to this query API which will be charged as standard queries. For more information, see AWS IoT Device Management pricing

Features

With device connectivity query support, you can:

1. Query the current connectivity state (connected or disconnected) for a given device using its thingName.

2. Retrieve additional connectivity metadata, including:

   1. Disconnect reason

   2. Timestamps for the most recent connect or disconnect event.

   3. Session information including the keep-alive duration

   4. Socket level session information including IP address, port, and VPC endpoint ID. This information is available only when the following conditions are met:

      1. You enable this option in fleet indexing configuration settings.

      2. You have the corresponding permission in the IAM policy when invoking the API.

Note

Fleet indexing indexes the connectivity status for a device whose connection clientId is the same as the thingName of a registered thing in Registry.

Benefits

1. Low latency: Reflects the most recent device connectivity state and offers low latency to reflect connection state changes from IoT Core. IoT Core determines a device as disconnected either as soon as it receives a disconnect request from the device or in case of a device disconnecting without sending a disconnect request. IoT core will wait 1.5x of the configured keep-alive time before the client is determined to be disconnected. The Connectivity status API will reflect these changes typically under one second after IoT Core determines a device’s connected state change.

2. High throughput: Supports 350 Transactions Per Second (TPS) by default, and can be adjustable to higher upon request.

3. Data retention: Stores event data indefinitely when Fleet Indexing (FI) ConnectivityIndexing mode is enabled and the thing is not deleted. If you disable Connectivity Indexing, the records will not be retained.

Note

If connectivity status indexing was enabled before the launch of this API, Fleet Indexing begins tracking connectivity status changes after the API launch and reflects the updated status based on those changes.

Prerequisites

To use device connectivity query support:

1. Set up an AWS account

2. Onboard and register devices to AWS IoT Core in your preferred region

3. Enable Fleet Indexing with Connectivity indexing. Optional: Opt-in to receive socket level information by enabling the includeSocketInformation option.

Note

No additional setup is required if you already have connectivity indexing enabled.

For detailed setup instructions, refer to the AWS IoT Developer Guide

Example

CLI Command:

aws iot get-thing-connectivity-data --include-socket-information --thing-name myThingName

Response:

{
   "thingName": "myThingName",
   "connected": true,
   "timestamp": "2024-12-19T10:00:00.000000-08:00",
   "disconnectReason": "NONE",
   "sourceIp": "192.0.2.1",
   "sourcePort": 52123,
   "targetIp": "198.51.100.1",
   "targetPort": 8883,
   "vpcEndpointId": "vpce-1234567890abcdef0",
   "keepAliveDuration": 60,
   "cleanSession": true,
   "clientId": "myThingName"
}

API Parameters

• thingName: The name of the device registered in AWS IoT Registry. This must match the clientId used to connect to AWS IoT Core.

• includeSocketInformation: The includeSocketInformation parameter controls whether socket-level network information is included in the API response. When set to true, the response includes the following fields: sourceIp, sourcePort, targetIp, targetPort, vpcEndpointId. When includeSocketInformation is not specified or set to false, these socket fields are excluded from the response. To restrict specific IAM users from accessing socket information you will need to specify this in their IAM policy by setting the includeSocketInformation condition key to be false

Response Fields

• thingName: The name of the device registered in AWS IoT Registry. This must match the clientId used to connect to AWS IoT Core.

• connected: The boolean value true indicating this device is currently connected.

• disconnectReason: Reason for disconnect. Will be NONE for a connected device and UNKNOWN for a device which has never been connected. For a disconnected device, this will indicate if the disconnection was client initiated, server initiated, due to authentication/authorization issues or due to network issues. For disconnect reason codes, see LifeCycleEvents

• timestamp: The timestamp representing the device’s most recent connect or disconnect event.

• clientId: The clientId of the MQTT client.

• keepAliveDuration: The keep-alive interval in seconds that the client specified when establishing the connection. This determines how frequently the client sends keep-alive messages to maintain the connection.

• cleanSession: Indicates whether the client is using a clean session.

• sessionExpiry: The persistent session expiry configuration the client specified when establishing the connection. This determines how long a session will remain active after the client disconnects.

• sourceIp: The IP address of the client that initiated the connection. Only returned if includeSocketInformation is set to be true and user is authorized to retrieve this information.

• sourcePort: The port number used by the client for the connection. Only returned if includeSocketInformation is set to be true and user is authorized to retrieve this information.

• targetIp: The IP address where the connection request was made to. Only returned if includeSocketInformation is set to be true and user is authorized to retrieve this information

• targetPort: The port number of the AWS IoT Core endpoint that the client connected to. Only returned if includeSocketInformation is set to be true and user is authorized to retrieve this information.

• vpcEndpointId: The ID of the VPC endpoint that the client connected through, if applicable. Only returned if includeSocketInformation is set to be true and user is authorized to retrieve this information.

Required Permissions

To use the GetThingConnectivityData API, you need the following IAM permission

iot:GetThingConnectivityData

You can scope this permission to specific things using resource based policies. Use the iot:IncludeSocketInformation condition to implement granular access control on socket information. The policy example below demonstrates a scenario where you deny the user access to socket information. Please note that this example works when it is the sole policy granting access to the action GetThingConnectivityData.

Authorization Policy Examples

{
  "Version": "2012-10-17",
  "Statement": [ 
  { 
    "Effect": "Allow",
    "Action": [ "iot:GetThingConnectivityData" ],
    "Resource": [ "arn:aws:iot:us-east-1:123456789012:thing/*"],
    "Condition": { 
      "Bool": { 
        "iot:IncludeSocketInformation": "false" 
      } 
    } 
  }] 
}