Finding device location using cells¶

This guide shows you how to find a device's location using one or more cells over REST. It uses the Asset Tracker v2 application and LTE Link Monitor (part of nRF Connect for Desktop) to find network information that you need to call the REST API.

The reference hardware for this guide is the nRF9160 DK.

Prerequisites and hardware requirements¶

For this guide, you need to program your device with Asset Tracker v2 with debug logs enabled. The setup for CELL location is different from the general one, so read through this section before you start.

Make sure you have met the general prerequisites and hardware requirements for Location Services.

Note

This guide requires nRF Connect SDK v1.8.0 or later.

Application¶

For this guide, you need to program your device with Asset Tracker v2 with debug logs enabled. The setup for CELL location is different from the general one, so read through Building the application before you start.

Building the application¶

Follow the instructions to build your application and program your device through nRF Connect for VS Code or through the command line, with the following changes:

Through nRF Connect for VS Code: When you reach the step setting your build configuration, under the menu Kconfig fragments, select overlay-debug.conf.
Through the command line: Use west build -b nrf9160dk_nrf9160ns -- -DOVERLAY_CONFIG=overlay-debug.conf to build the application with debug logs enabled.

Once you have built your application, continue with programming your device.

Getting network information¶

Once you have a device running Asset Tracker v2 and connected to nRF Cloud, you need parameter values related to the cells near the device. These values are used to determine the device's location.

You can get this information using the LTE Link Monitor application:

Open nRF Connect for Desktop.
Open LTE Link Monitor. The terminal shows by default.
If the side panel is not visible, click Show side panel.
Find the cards that list network parameters in the side panel, and note their values:
- Mccand Mnc appear as one number, the Public Land Mobile Network (PLMN) ID. Mcc is the first three digits and Mnc is the last two to three digits. These are separate values in API calls.
- CellId: This is eci in API calls.
- TAC: A five-digit tracking area code.

You may also include information on neighbor cells. Because you built your application with debug options enabled, you can access the debug log through LTE Link Monitor:

At the bottom of the terminal window, click Open log file. A file opens.
In the log file, search for nmr. This array contains data on neighbor cells. Within the array are more parameters:
- earfcn: Evolved Absolute Radio Frequency Channel.
- pci: Physical Cell Identity.
Make a note of these values. You may include them when calling the API.

Here is an example debug log entry with network data:

[00:01:41.711,608] <inf> event_manager: DATA_EVT_DATA_READY
Encoded message:
{
        "appId":        "CELL_POS",
        "messageType":  "DATA",
        "data": {
                "lte":  [{
                                "eci":  33903884,
                                "mcc":  242,
                                "mnc":  2,
                                "tac":  2801,
                                "earfcn":       6300,
                                "rsrp": -66,
                                "rsrq": -7,
                                "adv":  16,
                                "nmr":  [{
                                                "earfcn":       6300,
                                                "pci":  181,
                                                "rsrp": -89,
                                                "rsrq": -29
                                        }, {
                                                "earfcn":       6300,
                                                "pci":  176,
                                                "rsrp": -96,
                                                "rsrq": -34.5
                                        }]
                        }],
                "doReply":      0
        }
}
[00:01:41.771,026] <dbg> data_module.data_encode: Neighbor cell data encoded successfully
[00:01:41.779,663] <dbg> data_module.data_list_add_pending: Pending data added: 0x20022f38
[00:01:41.788,482] <inf> event_manager: DATA_EVT_NEIGHBOR_CELLS_DATA_SEND

Constructing the API request¶

This step shows you how to query device location from one or more cells, depending on what data you include in your request and which endpoint you call.

Calling the ground fix endpoint for cell location¶

The GetLocationFromCellsOrWifiNetworks ground fix endpoint combines Wi-Fi and LTE positioning methods into a single call. The service attempts to find the device's location using Wi-Fi first and falls back to cellular if the Wi-Fi request cannot resolve.

Example¶

The following cURL example is for REST, using LTE measurements:

curl --location --request POST "$API_HOST/v1/location/ground-fix" \
--header "Authorization: Bearer $JWT" \
--header "Content-Type: application/json" \
--data-raw "{\"lte\":[{\"mcc\":$MCC, \"mnc\":$MNC,\"tac\":$TAC,\"eci\":$ECI}]}"

For cURL, use the -d or --data-raw field to pass a JSON-formatted lte array including the following parameters:

eci: The value of CellId in your network information.
mcc: The first three digits of the Mccmnc parameter in your network information.
mnc: The last two digits of the Mccmncparameter in your network information.
tac: The area code in your network information.
nmr: Neighbor cell data. Including this can make the result more accurate. See the Ground Fix endpoint for more details.

The server responds with latitude and longitude, as well as uncertainty in meters. The fulfilledWith property tells you which method nRF Cloud used. See GetLocationFromCellsOrWifiNetworks for an example request and response.

The server stores position data in the location history. To view this, call the GetLocationHistory endpoint. You can also view historical location data under the Location card on a device's page in the nRF Cloud portal.