Implement the AWS.DiscoverDevices operation

Device discovery aligns the list of physical devices owned by the end user with the digital representations of those end user devices maintained in Managed integrations for AWS IoT Device Management. It is performed by an AWS customer on devices owned by the end user. For OAuth 2.0, this occurs after account linking is completed. For General Authorization, this can occur after the account association is created.

Device discovery is an asynchronous process where Managed integrations for AWS IoT Device Management calls a connector to initiate the device discovery request. A C2C connector returns a list of discovered end user devices asynchronously with a reference identifier (referred to as deviceDiscoveryId) generated by Managed integrations for AWS IoT Device Management.

`AWS.DiscoverDevices` Workflow

The following diagram illustrates the device discovery workflow between the end user and Managed integrations for AWS IoT Device Management:

Workflow Steps

Customer initiates device discovery - The customer initiates the device discovery process on behalf of the end user.
Managed integrations generates reference ID - Managed integrations for AWS IoT Device Management generates a reference identifier called deviceDiscoveryId for the device discovery request generated by the AWS Customer.
Device discovery request sent - Managed integrations for AWS IoT Device Management sends a device discovery request to the C2C connector using the AWS.DiscoverDevices operation interface, including authorization information (OAuth access token or AWS Secrets Manager reference) as well as the deviceDiscoveryId.
Connector stores deviceDiscoveryId - Your connector stores deviceDiscoveryId to be included in the DEVICE_DISCOVERY event. This event will also contain a list of discovered end user's devices, and must be sent to Managed integrations for AWS IoT Device Management with the SendConnectorEvent API as a DEVICE_DISCOVERY event.
Connector calls resource server - Your C2C connector shall call resource server to fetch all the devices owned by the end user.
Connector responds with ACK - Your C2C connector Lambda responds to the Lambda invocation (invokeFunction) with the ACK response back to Managed integrations for AWS IoT Device Management, acting as the initial response for the AWS.DiscoverDevices operation. Managed integrations for AWS IoT Device Management notifies customer with an ACK to their initiated device discovery process.
Resource server returns device list - Your resource server sends you a list of devices owned and operated by the end user.
Convert device format - Your connector converts each end user device into the Managed integrations for AWS IoT Device Management required device format, including ConnectorDeviceId, ConnectorDeviceName and Capability report for each device.
Provide UserId - The C2C connector also provides UserId of the discovered devices owner. It may be retrieved from your resource server either as part of the device list or in a separate call depending on your resource server implementation.
Call SendConnectorEvent API - Next, your C2C connector will call the Managed integrations for AWS IoT Device Management API, SendConnectorEvent, over SigV4 using AWS account credentials and with operation parameter set as "DEVICE_DISCOVERY". Each device in the list of devices sent to Managed integrations for AWS IoT Device Management will be represented by device-specific parameters such as connectorDeviceId, connectorDeviceName, and a capabilityReport.
- Based on your resource server response, you need to notify Managed integrations for AWS IoT Device Management accordingly.
- For example, if your resource server has paginated response to list of discovered devices for an end user, then for each poll you can send an individual DEVICE_DISCOVERY operation event, with a statusCode parameter of 3xx. If your device discovery is still in process, then repeat steps 5, 6, and 7.
Managed integrations notifies customer - Managed integrations for AWS IoT Device Management sends a notification to customer about discovered the end user's devices.
Completion notification - If your C2C connector sends a DEVICE_DISCOVERY operation event with the statusCode parameter updated with a value of 200, then Managed integrations for AWS IoT Device Management will notify customer of the device discovery workflow completion.

Important

Steps 7 through 11 can occur before step 6, if desired. For example, if your third-party platform has an API to list an end user's devices, the DEVICE_DISCOVERY event can be sent with SendConnectorEvent before the C2C connector Lambda responds with the typical ACK.

C2C connector Requirements for Device Discovery

The following list outlines the requirements for your C2C connector to facilitate a successful device discovery:

The C2C connector Lambda can process a device discovery request message from Managed integrations for AWS IoT Device Management and handle the AWS.DiscoverDevices operation.
Your C2C connector can call the Managed integrations for AWS IoT Device Management APIs via SigV4 using the credentials of the AWS account used for registering the connector.

Device Discovery Process

Step 1: Managed Integrations Triggers Device Discovery

Send a POST request to DiscoverDevices with one of the following JSON payloads, depending on the authorization type:

OAuth 2.0 Request:


/DiscoverDevices
{
   "header": {
        "auth": {                 
            "token": "ashriu32yr97feqy7afsaf",  
            "type": "OAuth2.0"
        }
   },
   "payload": {
        "operationName": "AWS.DiscoverDevices",
        "operationVersion": "1.0",
        "connectorId": "Your-Connector-Id",
        "deviceDiscoveryId": "12345678",
        "connectorDeviceIdList": []
   }
}

Note

The connectorDeviceIdList parameter is an optional filter that allows you to specify a list of device IDs to discover. When empty ([]), all devices associated with the account will be discovered. When populated with specific device IDs, only those devices will be included in the discovery response.

General Authorization request:


/DiscoverDevices
{
   "header": {
        "auth": {
            "secretsManager": {
                "arn": "string",
                "versionId": "string"
            },
            "type": "GeneralAuthorization"
        }
   },
   "payload": {
        "operationName": "AWS.DiscoverDevices",
        "operationVersion": "1.0",
        "connectorId": "Your-Connector-Id",
        "deviceDiscoveryId": "12345678",
        "connectorDeviceIdList": []
   }
}

Note

General Authorization Request:


/DiscoverDevices
{
   "header": {
        "auth": {
            "secretsManager": {
                "arn": "string",
                "versionId": "string"
            },
            "type": "GeneralAuthorization"
        }
   },
   "payload": {
        "operationName": "AWS.DiscoverDevices",
        "operationVersion": "1.0",
        "connectorId": "Your-Connector-Id",
        "deviceDiscoveryId": "12345678",
        "connectorDeviceIdList": []
   }
}

Note

Step 2: Connector Acknowledges Discovery

The connector sends an acknowledgment with the following JSON response:


{
     "header": {
          "responseCode":200
     },
     "payload": {
          "responseMessage": "Discovering devices for discovery-job-id '12345678' with connector-id `Your-Connector-Id`"
     }
}

Step 3: Connector Sends Device Discovery Event

Send a POST request to /connector-event/{your_connector_id} with the following JSON payload:


AWS API - /SendConnectorEvent
URI – POST /connector-event/{your_connector_id}
{
   "UserId": "6109342",
   "Operation": "DEVICE_DISCOVERY",
   "OperationVersion": "1.0",
   "StatusCode": 200,
   "DeviceDiscoveryId": "12345678",
   "ConnectorId": "Your_connector_Id",
   "Message": "Device discovery for discovery-job-id '12345678' successful",
   "Devices": [
        {
            "ConnectorDeviceId": "Your_Device_Id_1",
            "ConnectorDeviceName": "Your-Device-Name",
            "CapabilityReport": {
 	      		"nodeId":"1",
 			"version":"1.0.0", 
  			"endpoints":[{
 				"id":"1",
 				"deviceTypes":["Camera"],
 				"clusters":[{
 					"id":"0x0006",
 					"revision":1, 
 					"attributes":[{
 						"id":"0x0000",
 					}],
 					"commands":["0x00","0x01"],
 					"events":["0x00"]
 				}]
 			}]
 		} 
        }
    ]
}

Construct a CapabilityReport for the DISCOVER_DEVICES event

As seen in the event structure defined above, every device reported in a DISCOVER_DEVICES event, serving as response to an AWS.DiscoverDevices operation, will require a CapbilityReport to describe the corresponding device’s capabilities. A `CapabilityReport` tells managed integrations for AWS IoT Device Management device capabilities in a Matter compliant format.

Required Fields in CapabilityReport

nodeId, String: Identifier for the devices node containing the following endpoints
version, String: Version of this device node, set by the connector developer
endpoints, List<Cluster>: List of AWS implementations of the Matter Data Model supported by this device endpoint.
- id, String: Endpoint identifier set by connector developer
- deviceTypes, List<String>: List of device types this endpoint captures, i.e. "Camera".
- clusters, List<Cluster>: List of AWS implementations of the Matter Data Model this endpoint supports.
  - id, String: Cluster identifier as defined by the Matter standard.
  - revision, Integer: Cluster revision number as defined by the Matter standard.
  - attributes, Map<String, Object>: Map of attribute identifiers and their corresponding current device state values, with identifiers and valid values defined by the matter standard.
    
    id, String: Attribute ID as defined by AWS implementations of the Matter Data Model.
    
    value, Object: The current value of the attribute defined by the attribute ID. The type of 'value' can change depending on the attribute. The value field is optional for each attribute and should only be included if your connector lambda can determine the current state during discovery.
  - commands, List<String>: List of command IDs supported this cluster as defined by the Matter standard.
  - events, List<String>: List of event IDs supported this cluster as defined by the Matter standard.

For the current list of supported capabilities and their corresponding AWS implementations of the Matter Data Model refer to the latest release of the Data Model documentation.

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Implement the AWS.ActivateUser operation

Implement the AWS.SendCommand operation

Implement the AWS.DiscoverDevices operation

AWS.DiscoverDevices Workflow

Workflow Steps

Important

C2C connector Requirements for Device Discovery

Device Discovery Process

Note

Note

Note

Construct a CapabilityReport for the DISCOVER_DEVICES event

Required Fields in CapabilityReport

`AWS.DiscoverDevices` Workflow