nRF9160: Multicell location

The Multicell location sample demonstrates how to use Multicell location library to get a device’s position based on LTE cell measurements.

Requirements

The sample supports the following development kits:

Hardware platforms

PCA

Board name

Build target

Thingy:91

PCA20035

thingy91_nrf9160

thingy91_nrf9160_ns

nRF9160 DK

PCA10090

nrf9160dk_nrf9160

nrf9160dk_nrf9160_ns

When built for an _ns build target, the sample is configured to compile and run as a non-secure application. Therefore, it automatically includes Trusted Firmware-M that prepares the required peripherals and secure services to be available for the application.

Overview

You can use this sample as a starting point to implement multicell location services in an application that needs the location of the device.

The sample acquires LTE cell information from LTE link controller. The cell information is passed on to the Multicell location library, where an HTTP request is generated and sent to the location service of choice. Responses from location services are parsed and returned to the sample, which displays the responses on a terminal.

Currently, you can use the sample with the following location services supported by the Multicell location library:

Before you use the services, see the Multicell location library documentation and the respective location service documentation for the required setup.

Note

To use nRF Cloud Location Services, your device must have a valid JWT signing key installed and registered with nRF Cloud.

(See nRF Connect for Cloud REST API and Securely Generating Credentials on the nRF9160 for more details on this requirement).

Modem version v1.3.x or later is also required.

To obtain and register a valid signing key, you can do one of the following:

  • Provision your device on nRF Cloud using Just-In-Time Provisioning (JITP) (detailed below).

  • Provision your device on nRF Cloud with preconnect provisioning (detailed in nRF Cloud Provisioning).

  • Install or generate a private key on your device and register its public key with nRF Cloud (detailed in Securely Generating Credentials on the nRF9160).

To provision your device on nRF Cloud using JITP, complete the following steps:

  1. Ensure valid nRF Cloud credentials are installed. nRF9160 DK and Thingy:91 have credentials pre-installed, but some may be shipped with RSA256 credentials; JWT signing requires ES256 credentials. These devices need new credentials to be installed before they can perform REST requests.

  2. Install a sample or application that supports JITP. You can use the Asset Tracker V2 application for this purpose.

  3. Allow your device to connect to nRF Cloud and add it to the nRF Cloud portal. When successfully provisioned, the device appears in the devices list of the nRF Cloud portal.

  4. Once your device is provisioned, you may reinstall this sample and the provisioning persists.

Trigger location requests

Location requests can be triggered in the following ways and can be controlled by Kconfig options:

  • Pressing Button 1.

  • Periodically, with a configurable interval.

  • Changing of the current LTE cell, indicating that the device has moved.

Cell measurements

Data from LTE cell measurements is used to resolve a device’s location. There are two types of cells for which properties can be measured:

  • Current cell to which the device is connected

  • Neighboring cells

The most detailed information is measured for the current cell. See lte_lc_cells_info in LTE link controller API for more details on the information that is available for the different cells. LTE link controller library offers APIs to start and stop measurements, and the results are received in a callback.

Cell measurements are in general influenced by the following factors:

  • Network configuration

  • LTE connection state

  • Radio conditions

Cell measurement results might vary with the state of the LTE connection, and with the configurations of the LTE network that the device is connected to. For instance, the timing advance property, which can be used to estimate the distance between a device and the LTE cell, is only valid and available in RRC connected mode. Based on the network configurations, neighbor cell measurements might not be available in RRC connected mode. In this case, the device must enter RRC idle mode to perform neighbor cell measurements. This means that in some networks and configurations, it might not be possible to obtain timing advance for the current cell and neighbor cell measurements at the same time.

Multicell location requests are based on cell measurements. While deciding on when to perform cell measurements, keep in mind the following factors:

  • Timing advance for the current cell is available in RRC connected mode and not in RRC idle mode.

  • Neighbor cell measurements might not be possible in RRC connected mode, depending on the network configuration.

  • Neighbor cell measurements can, with some exceptions, be done in RRC idle mode and PSM. The number of cells that can be found varies with network configuration.

Configuration

See Configuring your application for information about how to permanently or temporarily change the configuration.

Setup

To use one of the supported location services, you must have an account and a configured authorization method. Follow the documentation on nRF Cloud or HERE Positioning for account creation and authorization method details.

Configuration options

Check and configure the following configuration options for the sample:

CONFIG_MULTICELL_LOCATION_SAMPLE_REQUEST_PERIODIC

(bool) Request location periodically

Request cell measurements and location periodically.

CONFIG_MULTICELL_LOCATION_SAMPLE_REQUEST_PERIODIC_INTERVAL

(int) Periodic search interval [sec]

Interval for periodic cell measurements and location requests.

CONFIG_MULTICELL_LOCATION_SAMPLE_REQUEST_BUTTON

(bool) Request location pressing button 1

Request cell measurements and location when button 1 is pressed.

CONFIG_MULTICELL_LOCATION_SAMPLE_REQUEST_CELL_CHANGE

(bool) Request location on cell change

Request cell measurements and location when the current LTE cell changes. This can be useful when testing on a moving device.

CONFIG_MULTICELL_LOCATION_SAMPLE_PRINT_DATA

(bool) Print multicell data

Prints cell data when it’s reported from the link controller.

CONFIG_MULTICELL_LOCATION_SAMPLE_PSM

(bool) Request PSM from the network

Request PSM from the LTE network.

CONFIG_MULTICELL_LOCATION_SAMPLE_EDRX

(bool) Request eDRX from the network

Request eDRX from the LTE network.

Additional configuration

Check and configure the following library options that are used by the sample:

See Multicell location for more information on the various configuration options available for the services.

Building and running

Note

Before building the sample, you must configure a location provider and an API key as instructed in Multicell location.

This sample can be found under samples/nrf9160/multicell_location in the nRF Connect SDK folder structure.

When built as a non-secure firmware image for the _ns build target, the sample automatically includes the Trusted Firmware-M (TF-M).

To build the sample with Visual Studio Code, follow the steps listed on the Building nRF Connect SDK application quick guide page in the nRF Connect for VS Code extension documentation. See Building and programming an application for other building and programming scenarios and Testing and debugging an application for general information about testing and debugging in the nRF Connect SDK.

Testing

After programming the sample to your development kit, complete the following steps to test it:

  1. Connect the kit to the computer using a USB cable. The kit is assigned a COM port (Windows) or ttyACM device (Linux), which is visible in the Device Manager.

  2. Connect to the kit with a terminal emulator (for example, PuTTY). See How to connect with PuTTY for the required settings.

  3. Observe that the sample starts:

    *** Booting Zephyr OS build v2.4.99-ncs1-4938-g540567aae240  ***
<inf> multicell_location_sample: Multicell location sample has started
<inf> multicell_location: Provisioning certificate
<inf> multicell_location_sample: Connecting to LTE network, this may take several minutes

  4. Wait until an LTE connection is established. A successful LTE connection is indicated by the following entry in the log:

    <inf> multicell_location_sample: Network registration status: Connected - roaming

  5. Press Button 1 on the device to trigger a cell measurement and location request:

    <inf> multicell_location_sample: Button 1 pressed, starting cell measurements

  6. Observe that cell measurements are displayed on the terminal:

    <inf> multicell_location_sample: Neighbor cell measurements received
<inf> multicell_location_sample: Current cell:
<inf> multicell_location_sample:     MCC: 242
<inf> multicell_location_sample:     MNC: 001
<inf> multicell_location_sample:     Cell ID: 1654712
<inf> multicell_location_sample:     TAC: 3410
<inf> multicell_location_sample:     EARFCN: 1650
<inf> multicell_location_sample:     Timing advance: 65535
<inf> multicell_location_sample:     Measurement time: 645008
<inf> multicell_location_sample:     Physical cell ID: 292
<inf> multicell_location_sample:     RSRP: 57
<inf> multicell_location_sample:     RSRQ: 30
<inf> multicell_location_sample: Neighbor cell 1
<inf> multicell_location_sample:     EARFCN: 1650
<inf> multicell_location_sample:     Time difference: -8960
<inf> multicell_location_sample:     Physical cell ID: 447
<inf> multicell_location_sample:     RSRP: 33
<inf> multicell_location_sample:     RSRQ: -17
<inf> multicell_location_sample: Neighbor cell 2
<inf> multicell_location_sample:     EARFCN: 100
<inf> multicell_location_sample:     Time difference: 24
<inf> multicell_location_sample:     Physical cell ID: 447
<inf> multicell_location_sample:     RSRP: 19
<inf> multicell_location_sample:     RSRQ: 4
<inf> multicell_location_sample: Neighbor cell 3
<inf> multicell_location_sample:     EARFCN: 3551
<inf> multicell_location_sample:     Time difference: 32
<inf> multicell_location_sample:     Physical cell ID: 281
<inf> multicell_location_sample:     RSRP: 41
<inf> multicell_location_sample:     RSRQ: 13

  7. Confirm that location request is sent, and that the response is received for each enabled service:

    <inf> multicell_location_sample: Sending location request for nRF Cloud...
<inf> multicell_location_sample: Location obtained from nRF Cloud:
<inf> multicell_location_sample:     Latitude: 63.4216744
<inf> multicell_location_sample:     Longitude: 10.4373742
<inf> multicell_location_sample:     Accuracy: 310

    The request might take a while to complete.

  8. Observe that cell measurement and location request happen after the periodic interval has passed:

    <inf> multicell_location_sample: Periodical start of cell measurements

  9. Observe that the sample continues with cell measurements and location requests as explained in the previous steps.

Dependencies

This sample uses the following nRF Connect SDK libraries and drivers:

It uses the following sdk-nrfxlib library:

It uses the following Zephyr libraries:

In addition, it uses the following secure firmware component: