nRF9160: nRF Cloud REST cellular positioning

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

Requirements

The sample supports the following development kits:

Hardware platforms

PCA

Board name

Build target

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.

You can also configure it to use the Secure Partition Manager.

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.

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 ref:modem_info_readme library. To enable multi-cell mode, press button 1. In multi-cell mode, the sample requests for neighbor cell measurement using the ref:lte_lc_readme 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_POS_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.

If you have not requested for JITP before starting up your device, the sample asks if the location card on the nRF Cloud portal should be enabled in the device’s shadow. This is only valid for provisioned devices. Press button 1 to perform the shadow update. The location card displays the device’s location on a map. This is not required for the sample to function. 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.

Configuration

See Configuring your 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_POS_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_POS_BUTTON_EVT_NUM - Button number

This configuration option defines the button to use for device interactions.

Building and running

This sample can be found under samples/nrf9160/nrf_cloud_rest_cell_pos 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). You can configure it to use the Secure Partition Manager instead of TF-M.

See Building and programming an application for information about how to build and program the application and Testing and debugging an application for general information about testing and debugging in the nRF Connect SDK.

Dependencies

This sample uses the following nRF Connect SDK libraries: