# Configuring position of wireless resources with AWS IoT Core for LoRaWAN
| |
| --- |
| Before using this feature, note that the chosen third party provider for resolving position information for LoRaWAN devices relies on data feeds and data sets provided or maintained by the International GNSS Service (IGS), EarthData via NASA, or other third-parties. These data feeds and data sets are Third-Party Content (as defined in the Customer Agreement) and provided on an as-is basis. For more information, see [AWS Service Terms](https://aws.amazon.com/service-terms). |
You can use AWS IoT Core for LoRaWAN to specify your static position data, or activate positioning to identify the position of your device in real time using third-party solvers. You can add or update the position information for either LoRaWAN devices or gateways, or both.
You specify the position information either when adding your device or gateway to AWS IoT Core for LoRaWAN, or when editing the configuration details of your device or gateway. The position information is specified as a [GeoJSON](https://geojson.org/) payload. The GeoJSON format is a format that's used to encode geographic data structures. The payload contains the latitude and longitude co-ordinates of your device location, that are based on the [ World Geodetic System coordinate system (WGS84)](https://gisgeography.com/wgs84-world-geodetic-system/).
After the solvers compute the position of your resource, if you have Amazon Location Service, you can activate an Amazon Location map where the position of your resource will be displayed. Using the position data, you can:
+ Activate positioning to identify and obtain the position of your LoRaWAN devices.
+ Track and monitor the position of your gateways and devices.
+ Define AWS IoT rules that process any updates to the position data and routes it to other AWS services. For a list of rule actions, see [AWS IoT rule actions](https://docs.aws.amazon.com/iot/latest/developerguide/iot-rule-actions.html) in the *AWS IoT developer guide*.
+ Create alerts and receive notifications to devices in case of any unusual activity by using the position data and Amazon SNS.
## How positioning works for LoRaWAN devices
You can activate positioning to identify the position of your devices using third-party Wi-Fi and GNSS solvers. This information can be used to track and monitor your device. The following steps show you how to activate positioning and view the position information for LoRaWAN devices.
**Note**
The third-party solvers can only be used with LoRaWAN devices that have the [LoRa Edge](https://www.semtech.com/products/wireless-rf/lora-edge) chip. It can't be used with LoRaWAN gateways. For gateways, you can still specify the static position information and identify the location on an Amazon Location map.
1.
**Add your device**
Before you activate positioning, first add your device to AWS IoT Core for LoRaWAN. The LoRaWAN device must have the LoRa Edge chipset, which is an ultra-low power platform that integrates a long range LoRa transceiver, multi-constellation GNSS scanner, and passive Wi-Fi MAC scanner targeting geolocation applications.
1.
**Activate positioning**
To obtain the real-time position of your devices, activate positioning. When your LoRaWAN device sends an uplink message, the Wi-Fi and GNSS scan data contained in the message is sent to AWS IoT Core for LoRaWAN using the geolocation frame port.
1.
**Retrieve position information**
Retrieve the estimated device position from the solvers computed based on the scan results from the transceivers. If the position information was computed using both Wi-Fi and GNSS scan results, AWS IoT Core for LoRaWAN selects the estimated position that has the higher accuracy.
1.
**View position information**
After the solver computes the position information, it will also provide the accuracy information which indicates the difference between the position computed by the solvers and the static position information that you entered. You can also view the device location on an Amazon Location map.
**Note**
As solvers can't be used for LoRaWAN gateways, the accuracy information will be reported as `0.0`.
For more information about the uplink message format and the frequency ports that are used for the positioning solver, see [Uplink message from AWS IoT Core for LoRaWAN to rules engine](lorawan-location-devices.md#lorawan-location-devices-uplink).
## Overview of positioning workflow
The following diagram shows how AWS IoT Core for LoRaWAN stores and updates the position information of your devices and gateways.
![\[Image showing how AWS IoT Core for LoRaWAN can use your static position data and raw data to compute the position in real time.\]](http://docs.aws.amazon.com/iot-wireless/latest/developerguide/images/iot-lorawan-lms-architecture.png)
1.
**Specify static position of your resource**
Specify the static position information of your device or gateway as a GeoJSON payload, using the latitude and longitude coordinates. You can also specify an optional altitude coordinate. These coordinates are based on the WGS84 coordinate system. For more information, see [ World Geodetic System (WGS84)](https://gisgeography.com/wgs84-world-geodetic-system/).
1.
**Activate positioning for devices**
If you're using LoRaWAN devices that have the LoRa Edge chip, you can optionally activate positioning to track your device position in real time. When your device sends an uplink message, the GNSS and Wi-Fi scan data is sent to AWS IoT Core for LoRaWAN using the geolocation frame port. The solvers then use this information to resolve the device position.
1.
**Add a destination to route position data**
You can add a destination that describes the IoT rule for processing the device data and route the updated position information to AWS IoT Core for LoRaWAN. You can also view the last known position of your resource on an Amazon Location map.
## Configuring your resource position
You can configure the position of your resource using the AWS Management Console, the AWS IoT Wireless API, or the AWS CLI.
If your devices have the LoRa Edge chip, you can activate positioning to compute the real-time position information. For your gateways, you can still enter the static position coordinates and use Amazon Location to track the gateway position on an Amazon Location map.
**Topics**
+ [How positioning works for LoRaWAN devices](#lorawan-location-solver)
+ [Overview of positioning workflow](#lorawan-location-workflow)
+ [Configuring your resource position](#lorawan-location-how)
+ [Configuring the position of LoRaWAN gateways](lorawan-location-gateways.md)
+ [Configuring position of LoRaWAN devices](lorawan-location-devices.md)
# Configuring the position of LoRaWAN gateways
When you add your gateway to AWS IoT Core for LoRaWAN, you can specify the static position data. If you've activated Amazon Location Service maps, the position data is displayed on an Amazon Location map.
**Note**
The third-party solvers can't be used with LoRaWAN gateways. For gateways, you can still specify the static position coordinates. When solvers aren't used to compute the position, such as in the case of gateways, the accuracy information will be reported as `0.0`.
You can configure the gateway position using the AWS Management Console, the AWS IoT Wireless API, or the AWS CLI.
## Configuring position of your gateway using the console
To configure the position of your gateway resources by using the AWS Management Console, first sign in to the console and then go to the [https://console.aws.amazon.com/iot/home#/wireless/gateways](https://console.aws.amazon.com/iot/home#/wireless/gateways) hub page of the AWS IoT console.
**Add position information**
To add a position configuration for your gateway
1. In the **Gateways** hub page, choose **Add gateway**.
1. Enter the gateway's EUI, frequency band (RFRegion), and any additional gateway details and LoRaWAN configuration information. For more information, see [Add a gateway using the console](lorawan-onboard-gateway-add.md#lorawan-onboard-gateway-console).
1. Go to the **Position information - Optional** section, and enter the position information for your gateway using the latitude and longitude coordinates, and an optional altitude coordinate. The position information is based on the WGS84 coordinate system.
**View gateway's position**
After you've configured your gateway's position, AWS IoT Core for LoRaWAN creates an Amazon Location map called `iotwireless.map`. You can see this map in the details page of your gateway on the **Position** tab. Based on the position coordinates that you specified, the position of your gateway will be displayed as a marker on the map. You can zoom in or zoom out to clearly view the position of your gateway on the map. On the **Position** tab, you'll also see the accuracy information and the timestamp at which your gateway's position was determined.
**Note**
If you don't have Amazon Location Service maps installed, you'll see a message indicating that you must use Amazon Location Service to access the map and view the gateway position. Using Amazon Location Service maps may incur additional charges to your AWS account. For more information, see [AWS IoT Core pricing](https://aws.amazon.com/iot-core/pricing/).
The map, `iotwireless.map`, acts as a source of map data which is accessed using `Get` API operations, such as [https://docs.aws.amazon.com/location-maps/latest/APIReference/API_GetMapTile.html](https://docs.aws.amazon.com/location-maps/latest/APIReference/API_GetMapTile.html). For information about `Get` APIs used with maps, see [Amazon Location Service API reference](https://docs.aws.amazon.com/location-maps/latest/APIReference/Welcome.html).
To get additional details about this map, go to the Amazon Location Service console, choose **maps**, and then choose [iotwireless.map](https://console.aws.amazon.com/location/maps/home#/describe/iotwireless.map). For more information, see [Maps](https://docs.aws.amazon.com/location/latest/developerguide/map-concepts.html) in the *Amazon Location Service developer guide*.
**Update gateway's position configuration**
To change the gateway's position configuration, in the gateway details page, choose **Edit** and then update the position information and the destination.
**Note**
Information about historical position data isn't available. When you update the gateway's position coordinates, it overwrites the previously reported position data. After you've updated the position, in the **Position** tab of the gateway details, you'll see the new position information. The change in timestamp indicates that it corresponds to the last known position of the gateway.
## Configure position of your gateway using the API
You can specify the position information and configure the gateway position using the AWS IoT Wireless API or the AWS CLI.
**Important**
The API actions [ UpdatePosition](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_UpdatePosition.html), [GetPosition](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetPosition.html), [PutPositionConfiguration](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_PutPositionConfiguration.html), [GetPositionConfiguration](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetPositionConfiguration.html), and [ListPositionConfigurations](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_ListPositionConfigurations.html) are no longer supported. Calls to update and retrieve the position information should use the [GetResourcePosition](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetResourcePosition.html) and [UpdateResourcePosition](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_UpdateResourcePosition.html) API operations instead.
### Add position information
To add the static position information for a given wireless gateway, 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 `WirelessGateway` as the `ResourceType`, the ID of the wireless gateway to be updated as the `ResourceIdentifier`, and the position information as a GeoJSON payload.
```
aws iotwireless update-resource-position \
--resource-type WirelessGateway \
--resource-id "12345678-a1b2-3c45-67d8-e90fa1b2c34d" \
--cli-input-json file://gatewayposition.json
```
The following shows the contents of the `gatewayposition.json` file.
**Contents of gatewayposition.json**
```
{
"type": "Point",
"coordinates": [33.3318, -22.2155, 13.123],
"properties": {
"timestamp": "2018-11-30T18:35:24Z"
}
}
```
Running this command doesn't produce any output. To see the position information that you specified, use the `GetResourcePosition` API operation.
### Get position information
To get the position information for a given wireless gateway, use the [ GetResourcePosition](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetResourcePosition.html) API operation or the [get-resource-position](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/get-position.html) CLI command. Specify `WirelessGateway` as the `resourceType` and provide the ID of the wireless gateway as the `resourceIdentifier`.
```
aws iotwireless get-resource-position \
--resource-type WirelessGateway \
--resource-id "12345678-a1b2-3c45-67d8-e90fa1b2c34d"
```
Running this command displays the position information of your wireless gateway as a GeoJSON payload. You'll see information about the position coordinates, the type of position information, and additional properties, such as the timestamp which corresponds to the last known position of the gateway.
```
{
{
"type": "Point",
"coordinates": [33.3318,-22.2155,13.123],
"properties": {
"timestamp": "2018-11-30T18:35:24Z"
}
}
}
```
# Configuring position of LoRaWAN devices
When you add your device to AWS IoT Core for LoRaWAN, you can specify the static position information, optionally activate positioning, and specify a destination. The destination describes the IoT rule that processes the device's position information and routes the updated position to Amazon Location Service. After you configure your device position, the position data is displayed on an Amazon Location map with the accuracy information, and the destination that you specified.
You can configure the position of your device using the AWS Management Console, the AWS IoT Wireless API, or the AWS CLI.
## Frame ports and format of uplink messages
If you activate positioning, you must specify the geolocation frame port for communicating the Wi-Fi and GNSS scan data from the device to AWS IoT Core for LoRaWAN. The position information is communicated to AWS IoT Core for LoRaWAN using this frame port.
The LoRaWAN specification provides a data delivery field (FRMPayload) and a Port field (FPort) to distinguish between different types of messages. To communicate the position information, you can specify a value anywhere between 1 and 223 for the frame port. FPort 0 is reserved for MAC messages, FPort 224 is reserved for MAC compliance testing, and ports 225-255 are reserved for future standardized application extensions.
### Uplink message from AWS IoT Core for LoRaWAN to rules engine
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.
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`.
```
{
// Position configuration parameters for given wireless device
"WirelessDeviceId": "5b58245e-146c-4c30-9703-0ca942e3ff35",
// 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],
"type": "Point",
"properties": {
"horizontalAccuracy": number,
"verticalAccuracy": number",
"timestamp": "2022-08-19T03:08:35.061Z"
},
//Parameters controlled by AWS IoT Core for LoRaWAN
"WirelessMetadata":
{
"LoRaWAN":
{
"ADR": false,
"Bandwidth": 125,
"ClassB": false,
"CodeRate": "4/5",
"DataRate": "0",
"DevAddr": "00b96cd4",
"DevEui": "58a0cb000202c99",
"FOptLen": 2,
"FCnt": 1,
"Fport": 136,
"Frequency": "868100000",
"Gateways": [
{
"GatewayEui": "80029cfffe5cf1cc",
"Snr": -29,
"Rssi": 9.75
}
],
"MIC": "7255cb07",
"MType": "UnconfirmedDataUp",
"Major": "LoRaWANR1",
"Modulation": "LORA",
"PolarizationInversion": false,
"SpreadingFactor": 12,
"Timestamp": "2021-05-03T03:24:29Z"
}
}
}
```
## Configuring position of your devices using the console
To configure and manage the position of your devices by using the AWS Management Console, first sign in to the console and then go to the [https://console.aws.amazon.com/iot/home#/wireless/devices](https://console.aws.amazon.com/iot/home#/wireless/devices) hub page of the AWS IoT console.
**Add position information**
To add position information for your device:
1. In the ** Devices** hub page, choose **Add wireless device**.
1. Enter the wireless device specification, device and service profiles, and the destination that defines the IoT rule for routing the data to other AWS services. For more information, see [Onboard your devices to AWS IoT Core for LoRaWAN](lorawan-onboard-end-devices.md).
1. Enter the position information, optionally activate geolocation, and specify a position data destination that you want to use for routing messages.
+
**Position information**
Specify the position data for your device using the latitude and longitude coordinates, and an optional altitude coordinate. The position information is based on the WGS84 coordinate system.
+
**Geolocation**
Activate positioning if you want AWS IoT Core for LoRaWAN to use geolocation for computing the device position. It uses third-party GNSS and Wi-Fi solvers to identify the position of your device in real time.
To enter the geolocation information, choose **Activate positioning**, and enter the geolocation frame port for communicating the GNSS and Wi-Fi scan data to AWS IoT Core for LoRaWAN. You'll see default FPorts populated for your reference. However, you can choose a different value anywhere between 1 and 223.
+
**Position data destination**
Choose a destination to describe the AWS IoT rule that processes the device's position data and forwards it to AWS IoT Core for LoRaWAN. Use this destination only to route position data. It must be different from the destination that you use for routing device data to other AWS services.
**View device's position configuration**
After you've configured your device's position, AWS IoT Core for LoRaWAN creates an Amazon Location map called `iotwireless.map`. You can see this map in the details page of your device on the **Position** tab. Based on the position coordinates that you specified or the position computed by the third-party solvers, the position of your device will be displayed as a marker on the map. You can zoom in or zoom out to clearly view the position of your device on the map. In the device's details page, on the **Position** tab, you'll also see the accuracy information, the timestamp at which your device's position was determined, and the position data destination that you specified.
**Note**
If you haven't activated Amazon Location Service maps, you'll see a message indicating that you'll have to use Amazon Location Service to access the map and view the position. Using Amazon Location Service maps may incur additional charges to your AWS account. For more information, see [AWS IoT Core pricing](https://aws.amazon.com/iot-core/pricing/).
The map, `iotwireless.map`, acts as a source of map data which is accessed using `Get` API operations, such as [https://docs.aws.amazon.com/location-maps/latest/APIReference/API_GetMapTile.html](https://docs.aws.amazon.com/location-maps/latest/APIReference/API_GetMapTile.html). For information about `Get` APIs used with maps, see [Amazon Location Service API reference](https://docs.aws.amazon.com/location-maps/latest/APIReference/Welcome.html).
To get additional details about this map, go to the Amazon Location Service console, choose **maps**, and then choose [iotwireless.map](https://console.aws.amazon.com/location/maps/home#/describe/iotwireless.map). For more information, see [Maps](https://docs.aws.amazon.com/location/latest/developerguide/map-concepts.html) in the *Amazon Location Service developer guide*.
**Update device's position configuration**
To change the device's position configuration, in the device details page, choose **Edit** and then update the position information, any geolocation settings, and the destination.
**Note**
Information about historical position data isn't available. When you update the device's position coordinates, it overwrites the previously reported position data. After you've updated the position, in the **Position** tab of the device details, you'll see the new position information. The change in timestamp indicates that it corresponds to the last known position of the device.
## 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.
You can specify the position information, configure the device position, and activate optional geolocation using the AWS IoT Wireless API or the AWS CLI.
**Important**
The API actions [ UpdatePosition](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_UpdatePosition.html), [GetPosition](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetPosition.html), [PutPositionConfiguration](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_PutPositionConfiguration.html), [GetPositionConfiguration](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetPositionConfiguration.html), and [ListPositionConfigurations](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_ListPositionConfigurations.html) are no longer supported. Calls to update and retrieve the position information should use the [GetResourcePosition](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetResourcePosition.html) and [UpdateResourcePosition](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_UpdateResourcePosition.html) API operations instead.
### Add position information and configuration
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.
```
aws iotwireless update-resource-position \
--resource-type WirelessDevice \
--resource-id "1ffd32c8-8130-4194-96df-622f072a315f" \
--position [33.33, -33.33, 10.0]
```
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.
**Contents of deviceposition.json**
```
{
"type": "Point",
"coordinates": [33.3318, -22.2155, 13.123],
"properties": {
"verticalAccuracy": 707,
"horizontalAccuracy":
"timestamp": "2018-11-30T18:35:24Z"
}
}
```
Running this command doesn't produce any output. To see the position information that you specified, use the `GetResourcePosition` API operation.
### Get position information and configuration
To get the position information for a given wireless device, use the [ GetResourcePosition](https://docs.aws.amazon.com/iot-wireless/latest/apireference/API_GetResourcePosition.html) API or the [get-resource-position](https://docs.aws.amazon.com/cli/latest/reference/iotwireless/get-resource-position.html) CLI command. Specify `WirelessDevice` as the `resourceType` and provide the ID of the wireless device as the `resourceIdentifier`.
```
aws iotwireless get-resource-position \
--resource-type WirelessDevice \
--resource-id "1ffd32c8-8130-4194-96df-622f072a315f"
```
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.
```
{
"type": "Point",
"coordinates": [33.3318, -22.2155, 13.123],
"properties": {
"verticalAccuracy": 707,
"horizontalAccuracy": 389,
"horizontalConfidenceLevel": 0.68,
"verticalConfidenceLevel": 0.68,
"timestamp": "2018-11-30T18:35:24Z"
}
}
```