Cellular: Location

The Location sample demonstrates how you can retrieve the location of a device using GNSS, cellular or Wi-Fi positioning method. This sample uses the Location library.

Requirements

The sample supports the following development kits:

Hardware platforms

PCA

Board name

Board target

Shields

Thingy:91 X

PCA20065

thingy91x

thingy91x/nrf9151/ns

Thingy:91

PCA20035

thingy91

thingy91/nrf9160/ns

nRF9161 DK

PCA10153

nrf9161dk

nrf9161dk/nrf9161/ns

nrf7002ek_nrf7000 nrf7002ek_nrf7001 nrf7002ek

nRF9160 DK

PCA10090

nrf9160dk

nrf9160dk/nrf9160/ns

nrf7002ek_nrf7000 nrf7002ek_nrf7001 nrf7002ek

nRF9151 DK

PCA10171

nrf9151dk

nrf9151dk/nrf9151/ns

nrf7002ek_nrf7000 nrf7002ek_nrf7001 nrf7002ek

When built for a board target with the */ns variant, the sample is configured to compile and run as a non-secure application with Cortex-M Security Extensions enabled. Therefore, it automatically includes Trusted Firmware-M that prepares the required peripherals and secure services to be available for the application.

See also the requirements in Location library document.

Note

This sample uses the nRF Cloud REST API, which requires that your device has a valid signing key installed and registered with nRF Cloud.

(See nRF Cloud REST API and Securely generating credentials for more details on this requirement).

If you are using nRF9160 DK, modem version v1.3.x or later is required. Your nRF9160 DK may ship with modem firmware older than v1.3.x, so verify that you have the latest installed. For an nRF9161 DK, modem version v2.0.0 or later is required.

For instructions on updating your device’s modem firmware, see the following documents:

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).

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

  1. Ensure valid nRF Cloud credentials are installed. nRF91 Series 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.

Overview

The Location sample retrieves the location multiple times to illustrate the different ways of retrieving the location of a device. Each individual location request has been implemented in a separate function within the sample. In addition to the Location library, this sample uses LTE link control to control the LTE connection.

Configuration

See Configuring and building an application for information about how to permanently or temporarily change the configuration.

Additional configuration

Refer to the Location library document for configuring the location retrieval behavior, including supported location methods and services.

If you use an external GNSS antenna, add the following configuration:

Configuration files

The sample provides predefined configuration files for typical use cases. The configuration files are in the samples/cellular/location directory.

The following files are available:

  • overlay-nrf700x-wifi-scan-only.conf - Config overlay for nRF7002 Wi-Fi chip support.

  • thingy91x-wifi.overlay - DTC overlay for Thingy:91 X Wi-Fi support.

  • overlay-pgps.conf - Config overlay for P-GPS support.

Sending traces over UART on an nRF91 Series DK

To send modem traces over UART on an nRF91 Series DK, configuration must be added for the UART device in the devicetree and Kconfig. This is done by adding the modem trace UART snippet when building and programming.

Use the Cellular Monitor app for capturing and analyzing modem traces.

TF-M logging must use the same UART as the application. For more details, see shared TF-M logging.

Building and running

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

When built as firmware image for a board target with the */ns variant, the sample has Cortex-M Security Extensions (CMSE) enabled and separates the firmware between Non-Secure Processing Environment (NSPE) and Secure Processing Environment (SPE). Because of this, it automatically includes the Trusted Firmware-M (TF-M). To read more about CMSE, see Processing environments.

To build the sample, follow the instructions in Configuring and building an application for your preferred building environment. See also Programming an application for programming steps and Testing and optimization for general information about testing and debugging in the nRF Connect SDK.

Note

When building repository applications in the SDK repositories, building with sysbuild is enabled by default. If you work with out-of-tree freestanding applications, you need to manually pass the --sysbuild parameter to every build command or configure west to always use it.

nRF91 Series DK with nRF7002 EK Wi-Fi support

To build the sample with nRF91 Series DK and nRF7002 EK Wi-Fi support, use the -DSHIELD=nrf7002ek and -DEXTRA_CONF_FILE=overlay-nrf700x-wifi-scan-only.conf options. For example:

west build -p -b board_target -- -DSHIELD=nrf7002ek -DEXTRA_CONF_FILE=overlay-nrf700x-wifi-scan-only.conf

Replace the board_target with the board target of the nRF91 Series device you are using (see the Requirements section).

See Providing CMake options for more instructions on how to add these options.

Thingy:91 X Wi-Fi support

To build the Location sample with Thingy:91 X Wi-Fi support, use the -DDTC_OVERLAY_FILE=thingy91x_wifi.overlay and -DEXTRA_CONF_FILE=overlay-nrf700x-wifi-scan-only.conf options. For example:

west build -p -b thingy91x_nrf9151_ns -- -DDTC_OVERLAY_FILE=thingy91x_wifi.overlay -DEXTRA_CONF_FILE=overlay-nrf700x-wifi-scan-only.conf

See Providing CMake options for more instructions on how to add these options.

P-GPS support

To build the Location sample with P-GPS support, use the following commands:

west build -p -b board_target -- -DEXTRA_CONF_FILE=overlay-pgps.conf

Replace the board_target with the board target of the nRF91 Series device you are using (see the Requirements section).

See Providing CMake options for more instructions on how to add this option.

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, nRF Connect Serial Terminal). See Testing and optimization for the required settings and steps.

  3. Observe that the sample prints to the terminal.

Sample output

An example output of the sample:

Location sample started

Connecting to LTE...
Connected to LTE

Requesting location with short GNSS timeout to trigger fallback to cellular...
[00:00:06.481,262] <wrn> location: Timeout occurred
[00:00:06.487,335] <wrn> location: Failed to acquire location using 'GNSS', trying with 'Cellular' next
Got location:
method: cellular
latitude: 12.887095
longitude: 55.580397
accuracy: 1250.0 m
Google maps URL: https://maps.google.com/?q=12.887095,55.580397

Requesting location with the default configuration...
Got location:
method: GNSS
latitude: 12.893736
longitude: 55.575859
accuracy: 4.4 m
date: 2021-10-28
time: 13:36:29.072 UTC
Google maps URL: https://maps.google.com/?q=12.893736,55.575859

Requesting location with high GNSS accuracy...
Got location:
method: GNSS
latitude: 12.893755
longitude: 55.575879
accuracy: 2.8 m
date: 2021-10-28
time: 13:36:32.339 UTC
Google maps URL: https://maps.google.com/?q=12.893755,55.575879

Requesting Wi-Fi location with GNSS and cellular fallback...
Got location:
method: GNSS
latitude: 12.893770
longitude: 55.575884
accuracy: 4.5 m
date: 2021-10-28
time: 13:36:45.895 UTC
Google maps URL: https://maps.google.com/?q=12.893770,55.575884

Requesting 30s periodic GNSS location...
Got location:
method: GNSS
latitude: 12.893765
longitude: 55.575912
accuracy: 4.4 m
date: 2021-10-28
time: 13:36:47.536 UTC
Google maps URL: https://maps.google.com/?q=12.893765,55.575912

Got location:
method: GNSS
latitude: 12.893892
longitude: 55.576090
accuracy: 8.4 m
date: 2021-10-28
time: 13:37:17.685 UTC
Google maps URL: https://maps.google.com/?q=12.893892,55.576090

Dependencies

This sample uses the following nRF Connect SDK libraries:

In addition, it uses the following secure firmware component: