AWS iot-wireless documentation change
Summary
Updated documentation for configuring LoRaWAN device positioning, including new sections on MQTT topic subscription for real-time location data, updated API/CLI examples, and a new table defining resolved location metadata parameters.
Security assessment
The changes are primarily documentation improvements, clarifications, and updates to examples (e.g., timestamps, JSON structures, API/CLI commands). There is no mention of security vulnerabilities, patches, or incidents. The removal of a note about Bluetooth Low Energy and Amazon Sidewalk gateway location data usage restrictions could be considered a reduction in security guidance, but it's not evidence of addressing a specific security issue. The changes focus on functionality and usability.
Diff
diff --git a/iot-wireless/latest/developerguide/lorawan-location-devices.md b/iot-wireless/latest/developerguide/lorawan-location-devices.md index 586012489..9af731fd7 100644 --- a//iot-wireless/latest/developerguide/lorawan-location-devices.md +++ b//iot-wireless/latest/developerguide/lorawan-location-devices.md @@ -7 +7 @@ -Frame ports and format of uplink messagesConfiguring position of your devices using the consoleConfigure device position using the API +Uplink message from AWS IoT Core for LoRaWAN to rules engineConfiguring the position of your devices using the consoleConfigure the position of your devices using API or CLIResolved location metadata parameters @@ -9 +9 @@ Frame ports and format of uplink messagesConfiguring position of your devices us -# Configuring position of LoRaWAN devices +# Configuring the position of LoRaWAN devices @@ -15 +15,3 @@ You can configure the position of your device using the AWS Management Console, -## Frame ports and format of uplink messages +## Uplink message from AWS IoT Core for LoRaWAN to rules engine + +###### Note @@ -23 +25,9 @@ The LoRaWAN specification provides a data delivery field (FRMPayload) and a Port -When you add a destination, it creates an AWS IoT rule to route the data to Amazon Location Service using the rules engine. The updated position information is then displayed on an Amazon Location map. If you haven't activated positioning, the destination routes the position data when you update the static position coordinates of your device. +You can subscribe to an MQTT topic to receive location data as it becomes available from your LoRaWAN device. This method allows you to process location data in real-time using AWS IoT rules. + + 1. ###### Create a destination for location data + +Create a destination with an AWS IoT rule that processes location data. For information about creating destinations, see [Add destinations to AWS IoT Core for LoRaWAN](./lorawan-create-destinations.html). + + 2. ###### Subscribe to the MQTT topic + +Go to the AWS IoT console, then navigate to **Test** > the [MQTT test client](https://console.aws.amazon.com/iot/home#/test). Enter the topic name that you specified in your location destination rule (for example, ``project/sensor/location``), and then choose **Subscribe**. @@ -25 +35 @@ When you add a destination, it creates an AWS IoT rule to route the data to Amaz -The following code shows the format of the uplink message sent from AWS IoT Core for LoRaWAN with the position information, accuracy, solver configuration, and the wireless metadata. The fields highlighted below are optional. If there's no vertical accuracy information, the value is `null`. + 3. ###### View location messages @@ -26,0 +37,3 @@ The following code shows the format of the uplink message sent from AWS IoT Core +When your device sends location data, you'll see messages published to the topic. The following shows an example of a location message: + +**Contents of deviceposition.json** @@ -29 +41,0 @@ The following code shows the format of the uplink message sent from AWS IoT Core - // Position configuration parameters for given wireless device @@ -32,6 +44,5 @@ The following code shows the format of the uplink message sent from AWS IoT Core - // Position information for a device in GeoJSON format. Altitude - // is optional. If no vertical accuracy information is available - // or positioning isn't activated, the value is set to null. - // The position information coordinates are listed in the order - // [longitude, latitude, altitude]. - "coordinates": [33.33000183105469, -22.219999313354492, 99.0], + "coordinates": [ + 33.33000183105469, + -22.219999313354492, + 99.0 + ], @@ -40,3 +51,4 @@ The following code shows the format of the uplink message sent from AWS IoT Core - "horizontalAccuracy": number, - "verticalAccuracy": number", - "timestamp": "2022-08-19T03:08:35.061Z" + "measurementType": "GNSS" | "Wi-Fi", + "horizontalAccuracy": 34, + "verticalAccuracy": 18.5, + "timestamp": "2026-01-01T00:00:00Z" @@ -74,2 +86 @@ The following code shows the format of the uplink message sent from AWS IoT Core - "Timestamp": "2021-05-03T03:24:29Z" - + "Timestamp": "2026-01-01T00:00:00Z" @@ -80 +91,10 @@ The following code shows the format of the uplink message sent from AWS IoT Core -## Configuring position of your devices using the console +###### Note + +The coordinates (position information for a device in GeoJSON format) are ordered as `[longitude, latitude, altitude]`, and altitude is optional if vertical accuracy information is unavailable. Please see more details on Resolved location metadata parameters. + +For WirelessMetadata, please refer to wireless device destination payload for regular uplink [Wireless device destination payload](./lorawan-device-connection-status.html#lorawan-device-connection-payload). + + + + +## Configuring the position of your devices using the console @@ -131,5 +151 @@ Information about historical position data isn't available. When you update the -## Configure device position using the API - -###### Note - -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. +## Configure the position of your devices using API or CLI @@ -143 +159,3 @@ The API actions [ UpdatePosition](https://docs.aws.amazon.com/iot-wireless/lates -### Add position information and configuration +### Update position information + +To update the position information for a given wireless device, specify the coordinates using the [ UpdateResourcePosition](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_UpdateResourcePosition.html) API operation or the [update-resource-position](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/update-resource-position.html) CLI command. Specify `WirelessDevice` as the `ResourceType`, the ID of the wireless device to be updated as the `ResourceIdentifier`, and the position information. @@ -145 +163 @@ The API actions [ UpdatePosition](https://docs.aws.amazon.com/iot-wireless/lates -To add the position information for a given wireless device, specify the coordinates using the [ UpdateResourcePosition](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_UpdateResourcePosition.html) API operation or the [update-resource-position](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/update-resource-position.html) CLI command. Specify `WirelessDevice` as the `ResourceType`, the ID of the wireless device to be updated as the `ResourceIdentifier`, and the position information. +**Sample of the UpdateResourcePosition API operation** @@ -147,0 +166,14 @@ To add the position information for a given wireless device, specify the coordin + PATCH /resource-positions/ResourceIdentifier?resourceType=WirelessDevice HTTP/1.1 + { + "coordinates": [ + 33.33, + -22.22, + 11.11 + ], + "type": "Point" + } + +**Sample of the update-resource-position CLI command** + + + echo '{"coordinates": [33.33, -22.22, 11.11], "type": "Point"}' > /tmp/position.json @@ -150,2 +182,2 @@ To add the position information for a given wireless device, specify the coordin - --resource-id "1ffd32c8-8130-4194-96df-622f072a315f" \ - --position [33.33, -33.33, 10.0] + --resource-id "5b58245e-146c-4c30-9703-0ca942e3ff35" \ + --geo-json-payload fileb:///tmp/position.json @@ -153 +185 @@ To add the position information for a given wireless device, specify the coordin -The following shows the contents of the ``deviceposition.json`` file. To specify the FPort values for sending the geolocation data, use the [Positioning](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_Positioning.html) object with the [CreateWirelessDevice](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_CreateWirelessDevice.html) and [UpdateWirelessDevice](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_UpdateWirelessDevice.html) API operations. +The following shows the contents of the ``deviceposition.json`` file, which is the uplink message from AWS IoT Core for LoRaWAN to rules engine To specify the FPort values for sending the geolocation data, use the [Positioning](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_Positioning.html) object with the [CreateWirelessDevice](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_CreateWirelessDevice.html) and [UpdateWirelessDevice](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_UpdateWirelessDevice.html) API operations. @@ -158,0 +191,6 @@ The following shows the contents of the ``deviceposition.json`` file. To specify + "coordinates": [ + 33.33, + -22.22, + 11.11 + ], + "WirelessDeviceId": "5b58245e-146c-4c30-9703-0ca942e3ff35", @@ -160 +197,0 @@ The following shows the contents of the ``deviceposition.json`` file. To specify - "coordinates": [33.3318, -22.2155, 13.123], @@ -162,3 +199,4 @@ The following shows the contents of the ``deviceposition.json`` file. To specify - "verticalAccuracy": 707, - "horizontalAccuracy": - "timestamp": "2018-11-30T18:35:24Z" + "measurementType": "UserInput", + "verticalAccuracy": 0, + "horizontalAccuracy": 0, + "timestamp": "2026-01-01T00:00:00Z" @@ -168 +206 @@ The following shows the contents of the ``deviceposition.json`` file. To specify -Running this command doesn't produce any output. To see the position information that you specified, use the `GetResourcePosition` API operation. +###### Note @@ -170 +208,3 @@ Running this command doesn't produce any output. To see the position information -### Get position information and configuration +This command returns no response body (`204 No Content`), so the ``update-resource-position-api-response.json`` file will be empty. To verify the updated position, use the `GetResourcePosition` API operation. + +### Get position information @@ -173,0 +214,7 @@ To get the position information for a given wireless device, use the [ GetResour +**Sample of the GetResourcePosition API operation** + + + GET /resource-positions/ResourceIdentifier?resourceType=WirelessDevice HTTP/1.1 + +**Sample of the get-resource-position CLI command** + @@ -177 +224,6 @@ To get the position information for a given wireless device, use the [ GetResour - --resource-id "1ffd32c8-8130-4194-96df-622f072a315f" + --resource-id "5b58245e-146c-4c30-9703-0ca942e3ff35" + /dev/stdout + +###### Note + +This command returns the position information of your wireless device as a GeoJSON payload (`200 OK`). The contents of the ``get-resource-position-api-response.json`` file includes the position coordinates, geolocation type, and properties such as measurement type, accuracy, and the timestamp when the device position was resolved. The wireless device ID is not included in the API response. @@ -179 +231 @@ To get the position information for a given wireless device, use the [ GetResour -Running this command displays the position information of your wireless device as a GeoJSON payload. You'll see information about the position coordinates, the location type, and properties which can include the accuracy information and the timestamp which corresponds to the last known position of the device. +**Contents of get-resource-position-api-response.json** @@ -182,0 +235,5 @@ Running this command displays the position information of your wireless device a + "coordinates": [ + 33.33, + -22.22, + 11.11 + ], @@ -184 +240,0 @@ Running this command displays the position information of your wireless device a - "coordinates": [33.3318, -22.2155, 13.123], @@ -186,5 +242,4 @@ Running this command displays the position information of your wireless device a - "verticalAccuracy": 707, - "horizontalAccuracy": 389, - "horizontalConfidenceLevel": 0.68, - "verticalConfidenceLevel": 0.68, - "timestamp": "2018-11-30T18:35:24Z" + "measurementType": "GNSS" | "Wi-Fi" | "UserInput", + "horizontalAccuracy": number, + "verticalAccuracy": number, + "timestamp": "Thu Jan 01 00:00:00 UTC 2026" @@ -193,0 +249,14 @@ Running this command displays the position information of your wireless device a +## Resolved location metadata parameters + +The following table shows a definition of the different parameters in the resolved location metadata. The ``wirelessDeviceId`` is the ID of the wireless device, such as ``5b58245e-146c-4c30-9703-0ca942e3ff35`` and the ``measurementType`` is the positioning method used to calculate the location. + +LoRaWAN resolved location metadata parameters Parameter | Description | Type +---|---|--- +`coordinates` | The resolved coordinates of the LoRaWAN device. Coordinates are ordered as `[longitude, latitude, altitude]`. | String +`wirelessDeviceId` | The identifier of the wireless device that sends the location uplink data | String +`type` | GeoJSON type. Currently supports the `"Point"` type. | String +`measurementType` | The measurement type for resolved location metadata. For LoRaWAN devices, the supported values are `"GNSS"` and `"Wi-Fi"`. If triggered by update-resource-position API or CLI, it would be `"UserInput"`. | String +`horizontalAccuracy` | The horizontal accuracy of the resolved position, in meters. | Number +`verticalAccuracy` | The vertical accuracy of the resolved position, in meters. | Number +`timestamp` | The timestamp when the LoRaWAN device location was resolved. | Timestamp +