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 |
Build target |
|---|---|---|---|
PCA10153 |
|
||
PCA10090 |
|
||
nRF9151 DK |
PCA10171 |
|
When built for an _ns build target, 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_confandfallbackflags 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 the _ns build target, 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: