Capability rediscovery - Managed integrations for AWS IoT Device Management
PrerequisitesWhen to use capability rediscoveryStart capability rediscoveryTroubleshooting

Capability rediscovery

This section describes the steps to relearn device capability information for hub-connected devices using capability rediscovery.

Prerequisites

Complete these steps before attempting capability rediscovery:

When to use capability rediscovery

Use capability rediscovery in the following scenarios:

  • After a firmware update to an end device that adds or modifies device capabilities

  • After a hub software update that enables support for new device features

  • When device capabilities are not accurately reflected in managed integrations

  • To refresh the capability information for a single device or all devices connected to a hub

Start capability rediscovery

Start capability rediscovery for your hub to update device capabilities.

To start capability rediscovery

  • Use the start-device-discovery command with the CONTROLLER_CAPABILITY_REDISCOVERY discovery type.

    start-device-discovery example

    # For a single device
aws iot-managed-integrations start-device-discovery \
  --discovery-type CONTROLLER_CAPABILITY_REDISCOVERY \
  --controller-identifier HUB_MANAGED_THING_ID \
  --protocol PROTOCOL \
  --end-device-identifier DEVICE_MANAGED_THING_ID

# For all devices on a protocol
aws iot-managed-integrations start-device-discovery \
  --discovery-type CONTROLLER_CAPABILITY_REDISCOVERY \
  --controller-identifier HUB_MANAGED_THING_ID \
  --protocol PROTOCOL

    Response:

    {
    "Id": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
    "StartedAt": "2026-01-12T23:07:49.275Z"
}
    Note

    The --protocol parameter accepts ZIGBEE, ZWAVE, or CUSTOM.

    If the optional --end-device-identifier parameter is not provided, all devices associated with the hub for the selected protocol are rediscovered.

    For more information, see the start-device-discovery command in the managed integrations AWS CLI Command Reference.

To verify that the device capabilities have been updated, see Get managed thing capabilities.

Troubleshooting

Use the following guidance to troubleshoot common issues with capability rediscovery. When capability rediscovery is in progress, managed integrations sends notifications through Kinesis or EventBridge as JSON messages.

Success notifications

Per device being processed:

{
    "messageType": "DEVICE_DISCOVERY_STATUS",
    // Capability rediscovery with controller and end device
    "resources": ["arn:aws:iotmanagedintegrations:us-east-1:123456789012:managed-thing/abc123def456", "arn:aws:iotmanagedintegrations:us-east-1:123456789012:managed-thing/xyz789uvw012"],
    "payload": {
        "deviceDiscoveryId": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
        "status": "RUNNING",
        "deviceCount": 1
    }
}

Completion:

{
    "messageType": "DEVICE_DISCOVERY_STATUS",
    // Capability rediscovery with controller only
    "resources": ["arn:aws:iotmanagedintegrations:us-east-1:123456789012:managed-thing/abc123def456"],
    "payload": {
        "deviceDiscoveryId": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
        "status": "SUCCEEDED",
        "deviceCount": 0
    }
}

Failure notifications

Device failure:

{
    "messageType": "DEVICE_DISCOVERY_STATUS",
    // Capability rediscovery with controller and end device
    "resources": ["arn:aws:iotmanagedintegrations:us-east-1:123456789012:managed-thing/abc123def456", "arn:aws:iotmanagedintegrations:us-east-1:123456789012:managed-thing/ghi345jkl678"],
    "payload": {
        "deviceDiscoveryId": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
        "status": "RUNNING",
        "deviceCount": 1,
        "error": {
            "code": "500",
            "message": "Device unreachable",
            "managedThingId": "ghi345jkl678"
        }
    }
}

Complete failure:

{
    "messageType": "DEVICE_DISCOVERY_STATUS",
    // Capability rediscovery with controller only
    "resources": ["arn:aws:iotmanagedintegrations:us-east-1:123456789012:managed-thing/abc123def456"],
    "payload": {
        "deviceDiscoveryId": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
        "status": "FAILED",
        "deviceCount": 0,
        "error": {
            "code": "404",
            "message": "Specified controller does not exist"
        }
    }
}

No notifications received

If you do not receive notifications about the discovery status, verify that you have subscribed to DEVICE_DISCOVERY_STATUS event notifications. For more information on setting up notifications, see Set up managed integrations notifications.

Some devices not updated

If some devices fail to update during capability rediscovery, check the error messages in the DEVICE_DISCOVERY_STATUS notifications. Common error messages include:

  • Device unreachable - The device is offline or not responding

  • Timeout querying device - The device is not responding within the expected timeframe

  • Invalid capability report - The device firmware may have an issue

To resolve these issues, ensure the affected devices are powered on and reachable, then retry capability rediscovery for the failed devices individually using the --end-device-identifier parameter.

Discovery never completes

If the capability rediscovery process does not complete, check the discovery status using the discovery job ID returned from the start-device-discovery command:

aws iot-managed-integrations get-device-discovery \
  --identifier DISCOVERY_JOB_ID

If the discovery is stuck:

  • Verify that the hub is online and connected to managed integrations

  • Wait up to 15 minutes for the discovery to timeout automatically

  • Retry the capability rediscovery after confirming the hub and devices are operational