Cellular: nRF Cloud REST cellular location

This sample demonstrates how to use the nRF Cloud REST API for nRF Cloud’s cellular location service on your device.

Requirements

The sample supports the following development kits:

Hardware platforms

PCA

Board name

Board target

nRF9161 DK

PCA10153

nrf9161dk

nrf9161dk/nrf9161/ns

nRF9160 DK

PCA10090

nrf9160dk

nrf9160dk/nrf9160/ns

nRF9151 DK

PCA10171

nrf9151dk

nrf9151dk/nrf9151/ns

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.

The sample requires an nRF Cloud account. It requires one of the following:

  • A device provisioned and associated with an nRF Cloud account. The sample supports JITP provisioning through REST.

  • A private key installed on the device and its associated public key registered with an nRF Cloud account.

Note

This sample requires modem firmware v1.3.x or later for an nRF9160 DK, or modem firmware v2.x.x for the nRF91x1 DKs.

Overview

After the sample initializes and connects to the network, it enters single-cell mode and sends a single-cell location request to nRF Cloud using network data obtained from the Modem information library. To enable multi-cell mode, press button 1. In multi-cell mode, the sample requests for neighbor cell measurement using the LTE link control library. If neighbor cell data is measured, the sample sends a multi-cell location request to nRF Cloud. Otherwise, the request is single-cell. In either mode, the sample sends a new location request if a change in cell ID is detected.

See the nRF Cloud Location Services documentation for additional information.

Limitations

The sample requires the network carrier to provide date and time to the modem. Without a valid date and time, the modem cannot generate JWTs with an expiration time.

User interface

If you have the option CONFIG_REST_CELL_LOCATION_DO_JITP enabled and you press button 1 when prompted at startup, it requests for just-in-time provisioning (JITP) with nRF Cloud through REST. This is useful when initially provisioning and associating a device on nRF Cloud. You only need to do this once for each device.

After the sample completes any requested JITP or shadow updates, pressing the button 1 toggles between single-cell and multi-cell mode.

Set the CONFIG_REST_CELL_CHANGE_CONFIG Kconfig config value to try all combinations of the nrf_cloud_location_config structure values hi_conf and fallback.

Configuration

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

Configuration options

Check and configure the following Kconfig options for the sample:

CONFIG_REST_CELL_LOCATION_DO_JITP - Enable prompt to perform JITP via REST

This configuration option defines whether the application prompts the user for just-in-time provisioning on startup.

CONFIG_REST_CELL_CHANGE_CONFIG - Enable changing request configuration

Set this to use the next combination of hi_conf and fallback flags after performing both single- and multi-cell location requests.

CONFIG_REST_CELL_DEFAULT_DOREPLY_VAL - Enable return of location from cloud

If enabled, request the cloud to return the location information.

CONFIG_REST_CELL_DEFAULT_FALLBACK_VAL - Enable fallback to coarse location

If enabled and the location of the cell tower or Wi-Fi access points cannot be found, return area-level location based on the cellular tracking area code. Otherwise an error will be returned indicating location is not known.

CONFIG_REST_CELL_DEFAULT_HICONF_VAL - Enable high confidence result

Enable a 95% confidence interval for the location, instead of the default 68%.

CONFIG_REST_CELL_SEND_DEVICE_STATUS - Send device status

Send device status to nRF Cloud on initial connection.

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/nrf_cloud_rest_cell_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 with Visual Studio Code, follow the steps listed on the How to build an application page in the nRF Connect for VS Code extension documentation. See Configuring and building an application for other building scenarios, Programming an application for programming steps, and Testing and optimization for general information about testing and debugging in the nRF Connect SDK.

Dependencies

This sample uses the following nRF Connect SDK libraries:

In addition, it uses the following secure firmware component: