AWS iot: Document multi-frame GNSS solver payload and constraints
Summary
Added a new 'Multi-frame GNSS solver' section describing the GnssMultiFrame payload, mutual exclusivity with Gnss, capture count constraints, and Use2DSolver/AssistAltitude validation.
Security assessment
This documents a new location-solving feature and its input validation rules; it is functional API documentation, not security guidance or a fix for a vulnerability.
Evidence
+The `Gnss` and `GnssMultiFrame` measurement types are mutually exclusive. A single request can't contain both.
Diff
diff --git a/iot/latest/developerguide/device-location-solvers-payload.md b/iot/latest/developerguide/device-location-solvers-payload.md index 2124997ee..210a91b3f 100644 --- a//iot/latest/developerguide/device-location-solvers-payload.md +++ b//iot/latest/developerguide/device-location-solvers-payload.md @@ -7 +7 @@ -Wi-Fi based solverCellular based solverIP reverse lookup solverGNSS solverBLE solver for Amazon Sidewalk enabled devices +Wi-Fi based solverCellular based solverIP reverse lookup solverGNSS solverMulti-frame GNSS solverBLE solver for Amazon Sidewalk enabled devices @@ -24,0 +25,2 @@ To resolve the device location, specify one or more of these measurement data ty + * Multi-frame GNSS solver + @@ -263,0 +266,4 @@ This solver can be used with LoRaWAN devices and Amazon Sidewalk enabled devices +###### Note + +The `Gnss` and `GnssMultiFrame` measurement types are mutually exclusive. A single request can't contain both. + @@ -282,0 +289,47 @@ Before AWS IoT Core Device Location can resolve the device location, you must re +## Multi-frame GNSS solver + +Use the multi-frame GNSS (Global Navigation Satellite System) solver to retrieve the device location using the information contained in multiple GNSS scan result messages or NAV messages that were captured by the same device. You provide the captures in the `Captures` list. You can optionally provide additional GNSS assistance information, which reduces the number of variables that the solver must use to search for signals. By providing this assistance information, which includes the position, altitude, and the capture time and accuracy information, the solver can easily identify the satellites in view and compute the device location. + +###### Note + +The `Gnss` and `GnssMultiFrame` measurement types are mutually exclusive. A single request can't contain both. + +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 multi-frame GNSS scan information containing the captures 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 [GnssMultiFrame](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetPositionEstimate.html#iotwireless-GetPositionEstimate-request-GnssMultiFrame) parameter of the [GetPositionEstimate](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetPositionEstimate.html) API operation. + +###### Note + + 1. Before AWS IoT Core Device Location can resolve the device location, you must remove the destination byte from each capture payload. + + 2. The number of captures provided in the `Captures` list must be one of the following values: 2, 4, 8, 16, or 32. + + 3. When a request has `Use2DSolver` set to `true`, you must also provide `AssistAltitude`. Otherwise, the request fails with a validation error. + + + + + + { + "Timestamp": 1664313161, // optional + "GnssMultiFrame": { + "AssistAltitude": number, // optional + "AssistPosition": [ number ], // optional + "CaptureTimeAccuracy": number, // optional + "Use2DSolver": boolean, // optional + "Captures": [ // required, must be 2, 4, 8, 16, or 32 captures + { + "Payload": "string", // required + "CaptureTime": number // optional + }, + { + "Payload": "string", // required + "CaptureTime": number // optional + }, + ... + { + "Payload": "string", // required + "CaptureTime": number // optional + } + ] + } + } +