C2C connector requirements for device discovery Device discovery process Constructing a CapabilityReport

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 only after account linking is completed between the user and managed integrations for AWS IoT Device Management. 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.

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

AWS.DiscoverDevices workflow

The customer initiates the device discovery process on behalf of the end user.
Managed integrations for AWS IoT Device Management generates a reference identifier called deviceDiscoveryId for the device discovery request generated by the AWS Customer.
Managed integrations for AWS IoT Device Management sends a device discovery request to the C2C connector using the AWS.DiscoverDevices operation interface, including a valid OAuth accessToken of the end user as well as the 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.
Your C2C connector shall call resource server to fetch all the devices owned by the end user.
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 notifies customer with an ACK to their initiated device discovery process.
Your resource server sends you a list of devices owned and operated by the end user.
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.
The C2C connector also provides UserId of the discovered devices owner. It may be retrieved from you resource server either as part of the device list or in a separate call depending on your resource server implementation.
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.
1. Based on your resource server response, you need to notify managed integrations for AWS IoT Device Management accordingly.
  
  For example, if your resource server is having 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 for AWS IoT Device Management sends a notification to customer about discovered the end user's devices.
If your C2C connector sends a DEVICE_DISCOVERY operation event with the statusCode parameter updated with a value of 200, then managed integrations 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 users 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 a 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

The following steps outline the device discovery process with your C2C connector and managed integrations for AWS IoT Device Management.

Device discovery process

Managed integrations triggers the device discovery:

Send a POST request to DiscoverDevices with the following JSON payload:


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

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`"
     }
}

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. The following fields must be provided in the ` 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

Important

C2C connector requirements for device discovery

Device discovery process

Device discovery process

Construct a CapabilityReport for the DISCOVER_DEVICES event