AWS iot-wireless documentation change
Summary
Restructured onboarding steps, added detailed instructions for creating destinations/IAM roles/IoT rules, and expanded documentation for device location features including positioning configuration and data handling notes.
Security assessment
The changes introduce documentation for device location features and explicitly state usage restrictions for gateway location data ('must only use for device location purposes', 'must not attempt to re-identify or reverse engineer'). These additions provide security guidance but do not address a specific disclosed vulnerability.
Diff
diff --git a/iot-wireless/latest/developerguide/sidewalk-getting-started.md b/iot-wireless/latest/developerguide/sidewalk-getting-started.md index fa9688359..41ddd2196 100644 --- a//iot-wireless/latest/developerguide/sidewalk-getting-started.md +++ b//iot-wireless/latest/developerguide/sidewalk-getting-started.md @@ -7 +7 @@ Try the sensor monitoring tutorialIntroduction to onboarding your Sidewalk devic -# Getting started with AWS IoT Core for Amazon Sidewalk +# Get started using AWS IoT Core for Amazon Sidewalk @@ -40 +40 @@ The following steps show you how to onboard and connect your Sidewalk end device -To perform the entire onboarding workflow, you also provision and register your end device, and connect your hardware development kit (HDK). For more information, see [Provisioning and registering your end device](https://docs.sidewalk.amazon/provisioning/) in the _Amazon Sidewalk documentation_. +To perform the entire onboarding workflow, you must provision and register your end device, and connect your hardware development kit (HDK). For more information, see [Provisioning and registering your end device](https://docs.sidewalk.amazon/provisioning/) in the _Amazon Sidewalk documentation_. @@ -44 +44 @@ To perform the entire onboarding workflow, you also provision and register your - * Step 1: Add your Sidewalk device to AWS IoT Core for Amazon Sidewalk + * Step 1: Create a destination for your Sidewalk end device @@ -46 +46 @@ To perform the entire onboarding workflow, you also provision and register your - * Step 2: Create a destination for your Sidewalk end device + * Step 2: Add your Sidewalk device to AWS IoT Core for Amazon Sidewalk @@ -55 +55,38 @@ To perform the entire onboarding workflow, you also provision and register your -### Step 1: Add your Sidewalk device to AWS IoT Core for Amazon Sidewalk +### Step 1: Create a destination for your Sidewalk end device + +Here's an overview of the steps that you'll perform to add your destination to AWS IoT Core for Amazon Sidewalk. Using the AWS Management Console, or the AWS IoT Wireless API operations, or the AWS CLI, you run the following steps to create a destination which can be an AWS IoT rule or an MQTT topic. You can then connect to the hardware platform, and view and exchange messages. For a sample IAM role and AWS IoT rule used for the AWS CLI examples in this section, see [Create an IAM role and IoT rule for your destination](./sidewalk-destination-rule-role.html). + +Store the destination name you create in this step. You'll use this information when you create a wireless device. + + 1. ###### Create IAM role + +Create an IAM role that grants AWS IoT Core for Amazon Sidewalk permission to send data to the AWS IoT rule. To create the role, use the [`CreateRole`](https://docs.aws.amazon.com/IAM/latest/APIReference/API_CreateRole.html) API operation or [`create-role`](https://docs.aws.amazon.com/cli/latest/reference/iam/create-role) CLI command. You can name the role as ``SidewalkRole``. + + aws iam create-role --role-name lambda-ex \ + --assume-role-policy-document file://lambda-trust-policy.json + + 2. ###### Create an AWS IoT rule for the destination + +Create an AWS IoT rule that will process the device's data and specify the topic to which messages are published. You'll observe messages on this topic after connecting to the hardware platform. Use the AWS IoT Core API operation, [`CreateTopicRule`](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateTopicRule.html), or the AWS CLI command, [`create-topic-rule`](https://docs.aws.amazon.com/cli/latest/reference/iot/create-topic-rule.html), to create a rule for the destination. + +###### Note + +You can also use an MQTT topic as a destination. For more information about how to create an MQTT topic, see [MQTT topics](https://docs.aws.amazon.com/iot/latest/developerguide/topics). + + aws iot create-topic-rule --rule-name Sidewalkrule \ + --topic-rule-payload file://myrule.json + + 3. ###### Create a destination + +Create a destination that associates your Sidewalk device with the IoT rule (or MQTT topic) that processes it for use with other AWS services. You can add a destination using the [Destinations hub](https://console.aws.amazon.com/iot/home#/wireless/destinations) of the AWS IoT console, or the [`CreateDestination`](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_CreateDestination.html) API operation or the [`create-destination`](https://docs.aws.amazon.com/cli/latest/reference/create-destination.html) CLI command. You'll send your Sidewalk end device's uplink data and location data to these destinations. + + aws iotwireless create-destination --name SidewalkDestination \ + --expression-type RuleName --expression SidewalkRule \ + --role-arn arn:aws:iam::123456789012:role/SidewalkRole + +Alternatively, if you want to provide an MQTT topic as the destination, replace the `expression-type` option with `MqttTopic` instead of `RuleName`. Replace `SidewalkRule` with the topic name. + + + + +### Step 2: Add your Sidewalk device to AWS IoT Core for Amazon Sidewalk @@ -61 +98 @@ Here's an overview of the steps that you'll perform to add your Sidewalk end dev -Create a device profile that contains the shared configurations for your Sidewalk devices. When creating the profile, specify a ``name`` for the profile as an alphanumeric string. To create a profile, either go to the [Sidewalk tab of the Profiles hub](https://console.aws.amazon.com/iot/home#/wireless/profiles?tab=sidewalk) in the AWS IoT console and choose **Create profile** , or use the [`CreateDeviceProfile`](https://docs.aws.amazon.com/iot-wireless/2020-11-22/apireference/API_CreateDeviceProfile.html) API operation or the [`create-device-profile`](https://docs.aws.amazon.com/cli/latest/reference/create-device-profile.html) CLI command as shown in this example. +Create a device profile that contains the shared configurations for your Sidewalk devices. When creating the profile, specify a `name` for the profile as an alphanumeric string. To create a profile, either go to the [Sidewalk tab of the Profiles hub](https://console.aws.amazon.com/iot/home#/wireless/profiles?tab=sidewalk) in the AWS IoT console and choose **Create profile** , or use the [`CreateDeviceProfile`](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_CreateDeviceProfile.html) API operation or the [`create-device-profile`](https://docs.aws.amazon.com/cli/latest/reference/create-device-profile.html) CLI command as shown in this example. @@ -66 +103 @@ Create a device profile that contains the shared configurations for your Sidewal - 2. ###### Create your Sidewalk end device + 2. ###### Create your Sidewalk end device and optionally get the device location @@ -68 +105,3 @@ Create a device profile that contains the shared configurations for your Sidewal -Create your Sidewalk end device with AWS IoT Core for Amazon Sidewalk. Specify a destination name and the ID of the device profile obtained from the previous step. To add a device, either go to the [Sidewalk tab of the Devices hub](https://console.aws.amazon.com/iot/home#/wireless/devices?tab=sidewalk) in the AWS IoT console and choose **Provision device** , or use the [`CreateWirelessDevice`](https://docs.aws.amazon.com/iot-wireless/2020-11-22/apireference/API_CreateWirelessDevice.html) API operation or the [`create-wireless-device`](https://docs.aws.amazon.com/cli/latest/reference/create-wireless-device.html) CLI command as shown in this example. + 1. ###### Create your Sidewalk end device + +Create your Sidewalk end device with AWS IoT Core for Amazon Sidewalk. Specify a destination name and the ID of the device profile obtained from the previous step. To add a device, either go to the [Sidewalk tab of the Devices hub](https://console.aws.amazon.com/iot/home#/wireless/devices?tab=sidewalk) in the AWS IoT console and choose **Provision device** , or use the [`CreateWirelessDevice`](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_CreateWirelessDevice.html) API operation or the [`create-wireless-device`](https://docs.aws.amazon.com/cli/latest/reference/create-wireless-device.html) CLI command as shown in this example. @@ -75,2 +114,4 @@ Specify a name for your destination that's unique to your AWS account and AWS Re - aws iotwireless create-wireless-device --type "Sidewalk" --name sidewalk_device \ - --destination-name SidewalkDestination \ + aws iotwireless create-wireless-device + --type "Sidewalk" + --name "sidewalk_device" \ + --destination-name "SidewalkDestination" \ @@ -79 +120 @@ Specify a name for your destination that's unique to your AWS account and AWS Re - 3. ###### Get device profile and wireless device information + 2. ###### (Optional) Create your Sidewalk end device and get the Sidewalk device location @@ -81 +122 @@ Specify a name for your destination that's unique to your AWS account and AWS Re -Get the device profile and wireless device information as a JSON. The JSON will contain information about the device details, device certificates, private keys, `DeviceTypeId`, and the Sidewalk manufacturing serial number (SMSN). +If you want to enable location data when you create your Sidewalk end device with AWS IoT Core for Amazon Sidewalk, enable positioning. Replace `LocationDestination` with the destination to which you want to send the device location data to. The destination can either be an AWS AWS IoT rule or an MQTT topic. You can use the destination you created in Step 1 above as your UplinkDestination. Alternatively, you can specify a different destination as LocationDestination. @@ -83 +124 @@ Get the device profile and wireless device information as a JSON. The JSON will - * If you're using the AWS IoT console, you can use the [Sidewalk tab of the Devices hub](https://console.aws.amazon.com/iot/home#/wireless/devices?tab=sidewalk) to download a combined JSON file for your Sidewalk end device. +AWS IoT Core for Amazon Sidewalk resolves the location of your Sidewalk end device using Bluetooth Low Energy (BLE), Wi-Fi, or GNSS uplink messages published by your Sidewalk end device. For more information on AWS IoT's location resolution capabilities, see [AWS IoT Core Device Location](https://docs.aws.amazon.com/iot/latest/developerguide/device-location.html). @@ -85 +126 @@ Get the device profile and wireless device information as a JSON. The JSON will - * If you're using the API operations, store the responses obtained from the API operations [`GetDeviceProfile`](https://docs.aws.amazon.com/iot-wireless/2020-11-22/apireference/API_GetDeviceProfile.html) and [`GetWirelessDevice`](https://docs.aws.amazon.com/iot-wireless/2020-11-22/apireference/API_CreateWirelessDevice.html) as separate JSON files, such as ``device_profile.json`` and ``wireless_device.json``. +###### Note @@ -87,3 +128 @@ Get the device profile and wireless device information as a JSON. The JSON will - // Store device profile information as a JSON file. - aws iotwireless get-device-profile \ - --id "12345678-a1b2-3c45-67d8-e90fa1b2c34d" > device_profile.json +You must enable positioning to use the device location feature. @@ -91,3 +130 @@ Get the device profile and wireless device information as a JSON. The JSON will - // Store wireless device information as a JSON file. - aws iotwireless get-wireless-device --identifier-type WirelessDeviceId \ - --identifier "23456789-abcd-0123-bcde-fabc012345678" > wireless_device.json +If you enable device location for the Sidewalk-enabled device, your raw uplink payload won't be propagated to the destination. @@ -94,0 +132,6 @@ Get the device profile and wireless device information as a JSON. The JSON will + // Add your Sidewalk device by using the device profile ID. + aws iotwireless create-wireless-device --type "Sidewalk" --name ""sidewalk_device" \ + --description "My Sidewalk Device Description" \ + --positioning "Enabled" \ + --destination-name "UplinkDestination" \ + --sidewalk DeviceProfileId="12345678-234a-45bc-67de-e8901234f0a1",Positioning={DestinationName="LocationDestination"} @@ -95,0 +139 @@ Get the device profile and wireless device information as a JSON. The JSON will +###### Note @@ -96,0 +141 @@ Get the device profile and wireless device information as a JSON. The JSON will +For Bluetooth Low Energy based location, AWS IoT returns location coordinates based on the approximate location of nearby Sidewalk Gateways that are connected to Amazon Sidewalk and have the Community Finding feature enabled. Gateway Location Data is AWS Content and is provided to you solely for the purpose of assisting you in locating your devices that are connected to Amazon Sidewalk, and you must only use the data for that purpose. You must only use and access location data via the interface and functionality that we generally make available to you, and you must not attempt to re-identify, reverse engineer, or re-map any Gateway location data provided by us to you. @@ -98 +143 @@ Get the device profile and wireless device information as a JSON. The JSON will -### Step 2: Create a destination for your Sidewalk end device + 3. ###### (Optional) Update your existing Sidewalk end device and get the device's location data @@ -100 +145 @@ Get the device profile and wireless device information as a JSON. The JSON will -Here's an overview of the steps that you'll perform to add your destination to AWS IoT Core for Amazon Sidewalk. Using the AWS Management Console, or the AWS IoT Wireless API operations, or the AWS CLI, you run the following steps to create an AWS IoT rule and destination. You can then connect to the hardware platform, and view and exchange messages. For a sample IAM role and AWS IoT rule used for the AWS CLI examples in this section, see [Create an IAM role and IoT rule for your destination](./sidewalk-destination-rule-role.html). +If you've already provisioned a Sidewalk end device in AWS IoT Wireless, you can update the device to get the device location data. @@ -102 +147 @@ Here's an overview of the steps that you'll perform to add your destination to A - 1. ###### Create IAM role +###### Note @@ -104 +149 @@ Here's an overview of the steps that you'll perform to add your destination to A -Create an IAM role that grants AWS IoT Core for Amazon Sidewalk permission to send data to the AWS IoT rule. To create the role, use the [`CreateRole`](https://docs.aws.amazon.com/IAM/latest/APIReference/API_CreateRole.html) API operation or [`create-role`](https://docs.aws.amazon.com/cli/latest/reference/iam/create-role) CLI command. You can name the role as ``SidewalkRole``. +You must enable positioning to use the device location feature. @@ -106,2 +151 @@ Create an IAM role that grants AWS IoT Core for Amazon Sidewalk permission to se - aws iam create-role --role-name lambda-ex \ - --assume-role-policy-document file://lambda-trust-policy.json +Replace `LocationDestination` with the destination name from the destination to which you want to send the device location data to. @@ -109 +153,3 @@ Create an IAM role that grants AWS IoT Core for Amazon Sidewalk permission to se - 2. ###### Create a rule for the destination + aws iotwireless update-wireless-device --id wireless-device-id \ + --positioning "Enabled" \ + --sidewalk Positioning={DestinationName="LocationDestination"} @@ -111 +157 @@ Create an IAM role that grants AWS IoT Core for Amazon Sidewalk permission to se -Create an AWS IoT rule that will process the device's data and specify the topic to which messages are published. You'll observe messages on this topic after connecting to the hardware platform. Use the AWS IoT Core API operation, [`CreateTopicRule`](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateTopicRule.html), or the AWS CLI command, [`create-topic-rule`](https://docs.aws.amazon.com/cli/latest/reference/iot/create-topic-rule.html), to create a rule for the destination. + 4. ###### Get device profile and wireless device information @@ -113,2 +159 @@ Create an AWS IoT rule that will process the device's data and specify the topic - aws iot create-topic-rule --rule-name Sidewalkrule \ - --topic-rule-payload file://myrule.json +Get the device profile and wireless device information as a JSON. The JSON will contain information about the device details, device certificates, private keys, `DeviceTypeId`, and the Sidewalk manufacturing serial number (SMSN). @@ -116 +161 @@ Create an AWS IoT rule that will process the device's data and specify the topic - 3. ###### Create a destination + * If you're using the AWS IoT console, you can use the [Sidewalk tab of the Devices hub](https://console.aws.amazon.com/iot/home#/wireless/devices?tab=sidewalk) to download a combined JSON file for your Sidewalk end device. @@ -118 +163 @@ Create an AWS IoT rule that will process the device's data and specify the topic -Create a destination that associates your Sidewalk device with the IoT rule that processes it for use with other AWS services. You can add a destination using the [Destinations hub](https://console.aws.amazon.com/iot/home#/wireless/destinations) of the AWS IoT console, or the [`CreateDestination`](https://docs.aws.amazon.com/iot-wireless/2020-11-22/apireference/API_CreateDestination.html) API operation or the [`create-destination`](https://docs.aws.amazon.com/cli/latest/reference/create-destination.html) CLI command. + * If you're using the API operations, store the responses obtained from the API operations [`GetDeviceProfile`](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetDeviceProfile.html) and [`GetWirelessDevice`](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_CreateWirelessDevice.html) as separate JSON files, such as ``device_profile.json`` and ``wireless_device.json``. @@ -120,3 +165,7 @@ Create a destination that associates your Sidewalk device with the IoT rule that - aws iotwireless create-destination --name SidewalkDestination \ - --expression-type RuleName --expression SidewalkRule \ - --role-arn arn:aws:iam::123456789012:role/SidewalkRole + // Store device profile information as a JSON file. + aws iotwireless get-device-profile \ + --id "12345678-a1b2-3c45-67d8-e90fa1b2c34d" > device_profile.json + + // Store wireless device information as a JSON file. + aws iotwireless get-wireless-device --identifier-type WirelessDeviceId \ + --identifier "23456789-abcd-0123-bcde-fabc012345678" > wireless_device.json @@ -145 +194 @@ Connect the HDK to your computer and follow the instructions provided by the ven -Use the MQTT client to subscribe to the topic specified in the rule and view the message received. You can also use the [`SendDataToWirelessDevice`](https://docs.aws.amazon.com/iot-wireless/2020-11-22/apireference/API_SendDataToWirelessDevice.html) API operation or the [`send-data-to-wireless-device`](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/send-data-to-wireless-device.html) CLI command to send a downlink message to your device and verify the connectivity status. +Use the MQTT client to subscribe to the topic specified in the rule and view the message received. You can also use the [`SendDataToWirelessDevice`](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_SendDataToWirelessDevice.html) API operation or the [`send-data-to-wireless-device`](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/send-data-to-wireless-device.html) CLI command to send a downlink message to your device and verify the connectivity status.