AWS iot documentation change
Summary
Added BLE solver documentation for Amazon Sidewalk devices, updated API reference links to use 'latest' version paths, and expanded supported device types across multiple solvers.
Security assessment
The change introduces a new section for BLE solver with a note about usage restrictions for Gateway Location Data, emphasizing proper use and prohibiting reverse engineering. While this adds security-related guidelines, there is no evidence of addressing a specific vulnerability or security incident. The updates to API links are routine maintenance.
Diff
diff --git a/iot/latest/developerguide/device-location-solvers-payload.md b/iot/latest/developerguide/device-location-solvers-payload.md index 1ef8a6cf9..a37b18535 100644 --- a//iot/latest/developerguide/device-location-solvers-payload.md +++ b//iot/latest/developerguide/device-location-solvers-payload.md @@ -5 +5 @@ -Wi-Fi based solverCellular based solverIP reverse lookup solverGNSS solver +Wi-Fi based solverCellular based solverIP reverse lookup solverGNSS solverBLE solver for Amazon Sidewalk enabled devices @@ -22,0 +23,2 @@ To resolve the device location, specify one or more of these measurement data ty + * BLE solver for Amazon Sidewalk enabled devices + @@ -28 +30 @@ To resolve the device location, specify one or more of these measurement data ty -Use the Wi-Fi based solver to resolve the location using the scan information from Wi-Fi access points. The solver supports the WLAN technology, and it can be used to compute the device location for general IoT devices and LoRaWAN wireless devices. +Use the Wi-Fi based solver to resolve the location using the scan information from Wi-Fi access points. The solver supports the WLAN technology, and it can be used to compute the device location for general IoT devices connecting over TCP/IP, LoRaWAN wireless devices, and Amazon Sidewalk enabled devices. @@ -32 +34,3 @@ The LoRaWAN devices must have the LoRa Edge chipset, which can decode the incomi -The following code shows an example of the JSON payload from the device that contains the measurement data. When AWS IoT Core Device Location receives this data as input, it sends an HTTP request to the solver provider to resolve the location information. To retrieve the information, specify values for the MAC Address and RSS (received signal strength). To do this, either provide the JSON payload using this format, or use the [WiFiAccessPoints object](https://docs.aws.amazon.com/iot-wireless/2020-11-22/apireference/API_WiFiAccessPoint.html) parameter of the [GetPositionEstimate](https://docs.aws.amazon.com/iot-wireless/2020-11-22/apireference/API_GetPositionEstimate.html) API operation. +To learn more about resolving location data for Amazon Sidewalk enabled devices, visit [AWS IoT Core for Amazon Sidewalk developer guide](https://docs.aws.amazon.com/iot-wireless/latest/developerguide/iot-sidewalk.html). + +The following code shows an example of the JSON payload from the device that contains the measurement data. When AWS IoT Core Device Location receives this data as input, it sends an HTTP request to the solver provider to resolve the location information. To retrieve the information, specify values for the MAC Address and RSS (received signal strength). To do this, either provide the JSON payload using this format, or use the [WiFiAccessPoints object](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_WiFiAccessPoint.html) parameter of the [GetPositionEstimate](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetPositionEstimate.html) API operation. @@ -64 +68 @@ You can use the cellular based solver to resolve the location using measurement -The following code shows examples of the JSON payload from the device that contains cellular measurement data. When AWS IoT Core Device Location receives this data as input, it sends an HTTP request to the solver provider to resolve the location information. To retrieve the information, you either provide the JSON payload using this format in the console, or specify values for the [CellTowers](https://docs.aws.amazon.com/iot-wireless/2020-11-22/apireference/API_GetPositionEstimate.html#iotwireless-GetPositionEstimate-request-CellTowers) parameter of the [GetPositionEstimate](https://docs.aws.amazon.com/iot-wireless/2020-11-22/apireference/API_GetPositionEstimate.html) API operation. You can provide the measurement data by specifying values for parameters using any or all of these cellular technologies. +The following code shows examples of the JSON payload from the device that contains cellular measurement data. When AWS IoT Core Device Location receives this data as input, it sends an HTTP request to the solver provider to resolve the location information. To retrieve the information, you either provide the JSON payload using this format in the console, or specify values for the [CellTowers](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetPositionEstimate.html#iotwireless-GetPositionEstimate-request-CellTowers) parameter of the [GetPositionEstimate](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetPositionEstimate.html) API operation. You can provide the measurement data by specifying values for parameters using any or all of these cellular technologies. @@ -66 +70 @@ The following code shows examples of the JSON payload from the device that conta -When you use this measurement data, you must specify information such as the network and country code of the mobile network, and optional additional parameters including information about the local ID. The following code shows an example of the payload format. For more information about these parameters, see [LTE object](https://docs.aws.amazon.com/iot-wireless/2020-11-22/apireference/API_LteObj.html). +When you use this measurement data, you must specify information such as the network and country code of the mobile network, and optional additional parameters including information about the local ID. The following code shows an example of the payload format. For more information about these parameters, see [LTE object](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_LteObj.html). @@ -100 +104 @@ When you use this measurement data, you must specify information such as the net -When you use this measurement data, you must specify information such as the network and country code of the mobile network, the base station information, and optional additional parameters. The following code shows an example of the payload format. For more information about these parameters, see [GSM object](https://docs.aws.amazon.com/iot-wireless/2020-11-22/apireference/API_GsmObj.html). +When you use this measurement data, you must specify information such as the network and country code of the mobile network, the base station information, and optional additional parameters. The following code shows an example of the payload format. For more information about these parameters, see [GSM object](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GsmObj.html). @@ -133 +137 @@ When you use this measurement data, you must specify information such as the net -When you use this measurement data, you must specify information such as the signal power and identification information, the base station information, and optional additional parameters. The following code shows an example of the payload format. For more information about these parameters, see [CDMA object](https://docs.aws.amazon.com/iot-wireless/2020-11-22/apireference/API_CdmaObj.html). +When you use this measurement data, you must specify information such as the signal power and identification information, the base station information, and optional additional parameters. The following code shows an example of the payload format. For more information about these parameters, see [CDMA object](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_CdmaObj.html). @@ -165 +169 @@ When you use this measurement data, you must specify information such as the sig -When you use this measurement data, you must specify information such as the network and country code, signal power and identification information, the base station information, and optional additional parameters. The following code shows an example of the payload format. For more information about these parameters, see [CDMA object](https://docs.aws.amazon.com/iot-wireless/2020-11-22/apireference/API_CdmaObj.html). +When you use this measurement data, you must specify information such as the network and country code, signal power and identification information, the base station information, and optional additional parameters. The following code shows an example of the payload format. For more information about these parameters, see [CDMA object](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_CdmaObj.html). @@ -197 +201 @@ When you use this measurement data, you must specify information such as the net -When you use this measurement data, you must specify information such as the network and country code, signal power and identification information, the base station information, and optional additional parameters. The following code shows an example of the payload format. For more information about these parameters, see [CDMA object](https://docs.aws.amazon.com/iot-wireless/2020-11-22/apireference/API_CdmaObj.html). +When you use this measurement data, you must specify information such as the network and country code, signal power and identification information, the base station information, and optional additional parameters. The following code shows an example of the payload format. For more information about these parameters, see [CDMA object](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_CdmaObj.html). @@ -238 +242 @@ By using the IP reverse lookup, you agree not to use it for the purpose of ident -The following code shows an example of the JSON payload from the device that contains the measurement data. When AWS IoT Core Device Location receives the IP address information in the measurement data, it looks up this information in the solver provider's database, which is then used to resolve the location information. To retrieve the information, either provide the JSON payload using this format, or specify values for the [Ip](https://docs.aws.amazon.com/iot-wireless/2020-11-22/apireference/API_GetPositionEstimate.html#iotwireless-GetPositionEstimate-request-Ip) parameter of the [GetPositionEstimate](https://docs.aws.amazon.com/iot-wireless/2020-11-22/apireference/API_GetPositionEstimate.html) API operation. +The following code shows an example of the JSON payload from the device that contains the measurement data. When AWS IoT Core Device Location receives the IP address information in the measurement data, it looks up this information in the solver provider's database, which is then used to resolve the location information. To retrieve the information, either provide the JSON payload using this format, or specify values for the [Ip](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetPositionEstimate.html#iotwireless-GetPositionEstimate-request-Ip) parameter of the [GetPositionEstimate](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetPositionEstimate.html) API operation. @@ -256 +260 @@ Use the GNSS (Global Navigation Satellite System) solver to retrieve the device -This solver can be used with LoRaWAN devices, and other devices that have been provisioned with AWS IoT. For general IoT devices, if the devices support location estimation using GNSS, when the GNSS scan information is received from the device, the transceivers resolve the location information. For LoRaWAN devices, the devices must have the LoRa Edge chipset. When an uplink message is received from the device, the GNSS scan data is sent to AWS IoT Core for LoRaWAN, and the location is estimated based on the scan results from the transceivers. +This solver can be used with LoRaWAN devices and Amazon Sidewalk enabled devices, as well as other devices that have been provisioned with AWS IoT devices that have been provisioned with AWS IoT. For general IoT devices, if the devices support location estimation using GNSS, when the GNSS scan information is received from the device, the transceivers resolve the location information. For LoRaWAN devices, the devices must have the LoRa Edge chipset. When an uplink message is received from the device, the GNSS scan data is sent to AWS IoT for LoRaWAN or AWS IoT for Amazon Sidewalk, and the location is estimated based on the scan results from the transceivers. @@ -258 +262 @@ This solver can be used with LoRaWAN devices, and other devices that have been p -The following code shows an example of the JSON payload from the device that contains the measurement data. When AWS IoT Core Device Location receives the GNSS scan information containing the payload in the measurement data, it uses the transceivers and any additional assistance information included to search for signals and resolve the location information. To retrieve the information, either provide the JSON payload using this format, or specify values for the [Gnss](https://docs.aws.amazon.com/iot-wireless/2020-11-22/apireference/API_GetPositionEstimate.html#iotwireless-GetPositionEstimate-request-Gnss) parameter of the [GetPositionEstimate](https://docs.aws.amazon.com/iot-wireless/2020-11-22/apireference/API_GetPositionEstimate.html) API operation. +The following code shows an example of the JSON payload from the device that contains the measurement data. When AWS IoT Core Device Location receives the GNSS scan information containing the payload in the measurement data, it uses the transceivers and any additional assistance information included to search for signals and resolve the location information. To retrieve the information, either provide the JSON payload using this format, or specify values for the [Gnss](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetPositionEstimate.html#iotwireless-GetPositionEstimate-request-Gnss) parameter of the [GetPositionEstimate](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetPositionEstimate.html) API operation. @@ -276,0 +281,8 @@ Before AWS IoT Core Device Location can resolve the device location, you must re +## BLE solver for Amazon Sidewalk enabled devices + +###### 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. + +Amazon Sidewalk end devices connecting over AWS IoT Core for Amazon Sidewalk can resolve their location data using BLE, Wi-Fi, or GNSS uplink messages published by the Amazon Sidewalk end device. For more information, see the [AWS IoT Core for Amazon Sidewalk developer guide](https://docs.aws.amazon.com/iot-wireless/latest/developerguide/sidewalk-getting-started.html). +