AWS iot-mi documentation change
Summary
Updated capitalization of 'Integrations' throughout document and added new section for including device brand/model metadata in discovery events
Security assessment
The changes consist of editorial capitalization corrections ('integrations' to 'Integrations') and addition of optional device metadata fields (brand/model). No security vulnerabilities, authentication mechanisms, or access controls were modified. The added metadata improves device identification but doesn't address security weaknesses or introduce security features.
Diff
diff --git a/iot-mi/latest/devguide/discover-devices-op.md b/iot-mi/latest/devguide/discover-devices-op.md index 186edd3ed..c36f9ee1e 100644 --- a//iot-mi/latest/devguide/discover-devices-op.md +++ b//iot-mi/latest/devguide/discover-devices-op.md @@ -7 +7 @@ -Constructing a CapabilityReport +Brand and ModelConstructing a CapabilityReport @@ -11 +11 @@ Constructing a CapabilityReport -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 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. @@ -13 +13 @@ Device discovery aligns the list of physical devices owned by the end user with -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. +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. @@ -17 +17 @@ Device discovery is an asynchronous process where Managed integrations for AWS I -The following diagram illustrates the device discovery workflow between the end user and Managed integrations for AWS IoT Device Management: +The following diagram illustrates the device discovery workflow between the end user and Managed Integrations for AWS IoT Device Management: @@ -25 +25 @@ The following diagram illustrates the device discovery workflow between the end - 2. **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. + 2. **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. @@ -27 +27 @@ The following diagram illustrates the device discovery workflow between the end - 3. **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`. + 3. **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`. @@ -29 +29 @@ The following diagram illustrates the device discovery workflow between the end - 4. **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. + 4. **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. @@ -33 +33 @@ The following diagram illustrates the device discovery workflow between the end - 6. **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. + 6. **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. @@ -37 +37 @@ The following diagram illustrates the device discovery workflow between the end - 8. **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. + 8. **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. @@ -41 +41 @@ The following diagram illustrates the device discovery workflow between the end - 10. **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`. + 10. **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`. @@ -43 +43 @@ The following diagram illustrates the device discovery workflow between the end - * Based on your resource server response, you need to notify Managed integrations for AWS IoT Device Management accordingly. + * Based on your resource server response, you need to notify Managed Integrations for AWS IoT Device Management accordingly. @@ -47 +47 @@ The following diagram illustrates the device discovery workflow between the end - 11. **Managed integrations notifies customer** \- Managed integrations for AWS IoT Device Management sends a notification to customer about discovered the end user's devices. + 11. **Managed integrations notifies customer** \- Managed Integrations for AWS IoT Device Management sends a notification to customer about discovered the end user's devices. @@ -49 +49 @@ The following diagram illustrates the device discovery workflow between the end - 12. **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. + 12. **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. @@ -62 +62 @@ The following list outlines the requirements for your C2C connector to facilitat - * 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. + * 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. @@ -64 +64 @@ The following list outlines the requirements for your C2C connector to facilitat - * 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. + * 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. @@ -211,0 +212,28 @@ Send a POST request to `/connector-event/`{your_connector_id}`` with the followi +## Populate Brand and Model for discovered devices + +Your C2C connector can optionally include a `DeviceMetadata` object for each device in the `DEVICE_DISCOVERY` event to report the device's brand and model. These values are then returned in the [ListDiscoveredDevices](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_ListDiscoveredDevices.html#API_ListDiscoveredDevices_ResponseSyntax) and [ListManagedThings](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_ListManagedThings.html#API_ListManagedThings_ResponseSyntax) responses. + +Include a `DeviceMetadata` object in each device entry and map: + + * `DeviceMetadata.Brand` (String) → `Brand` + + * `DeviceMetadata.Model` (String) → `Model` + + + + +The following example shows a device entry with `DeviceMetadata` included: + + + { + "ConnectorDeviceId": "Your_Device_Id_1", + "ConnectorDeviceName": "Your-Device-Name", + "CapabilityReport": { ... }, + "DeviceMetadata": { + "Brand": "ExampleBrand", + "Model": "ExampleModel-X1" + } + } + +Both keys are case-sensitive strings. If you omit `DeviceMetadata`, omit an individual key, or provide a non-string value, the corresponding field is not available when the device is retrieved. +