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

The sample is configured to compile and run as a non-secure application on nRF91’s Cortex-M33. Therefore, it automatically includes the Secure Partition Manager that prepares the required peripherals to be available for the application.

You can also configure it to use TF-M instead of Secure Partition Manager.

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

nRF9160 DK and Thingy:91 devices are shipped with RSA256 certificates. To start using the Multicell location library with nRF Cloud, you must perform either of the following actions:

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, HERE Positioning or Skyhook Precision Location 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.

The sample is built as a non-secure firmware image for the nrf9160dk_nrf9160_ns build target. Because of this, it automatically includes the Secure Partition Manager. You can also configure it to use TF-M instead of SPM.

See Building and programming an application for information about how to build and program the application.

Testing

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

  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 samples: