Location

The Location library provides functionality for retrieving the location of a device using different positioning methods such as:

• GNSS satellite positioning including Assisted GNSS (A-GNSS) and Predicted GPS (P-GPS) data.

• Cellular positioning.

• Wi-Fi positioning.

Overview

This library provides an API for applications to request the location of a device. The application can determine the preferred order of the location methods to be used along with other configuration information. If a method fails to provide the location, the library performs a fallback to the next preferred method.

Both cellular and Wi-Fi positioning detect the base stations and use web services for retrieving the location. GNSS positioning uses satellites to compute the location of the device. This library can use the assistance data (A-GNSS and P-GPS) to find the satellites faster.

Implementation

The Location library has a compact API and a location core that handles the functionality that is independent of the location method, such as fallback to the next preferred method and timeouts. The supported location methods are as follows:

• GNSS positioning

  • Uses Global Navigation Satellite System for getting the location.

  • A-GNSS and P-GPS are managed with nRF Cloud A-GNSS and nRF Cloud P-GPS.

  • The application may also use some other source for the data and use location_agnss_data_process() and location_pgps_data_process() to pass the data to the Location library.

  • The data format of A-GNSS or P-GPS must be as received from nRF Cloud A-GNSS.

  • The data transport method for nRF Cloud A-GNSS and nRF Cloud P-GPS can be configured to be either MQTT (CONFIG_NRF_CLOUD_MQTT) or REST (CONFIG_NRF_CLOUD_REST). If different transport is desired for different location methods, (CONFIG_NRF_CLOUD_MQTT) and (CONFIG_NRF_CLOUD_REST) can be enabled simultaneously. In such a case, MQTT takes precedence as the transport method of GNSS assistance data.

  • Note that acquiring GNSS fix only starts when LTE connection, more specifically Radio Resource Control (RRC) connection, is idle. Also, if A-GNSS is not used and Power Saving Mode (PSM) is enabled, the Location library will wait for the modem to enter PSM.

  • Selectable location accuracy (low/normal/high).

  • Obstructed visibility detection enables a fast fallback to another positioning method if the device is detected to be indoors.

• Cellular positioning

  • Uses LTE link control for getting a list of nearby cellular base stations.

  • Neighbor cell measurement is performed with LTE_LC_NEIGHBOR_SEARCH_TYPE_EXTENDED_LIGHT search type. If more than one cell is requested, a GCI search with LTE_LC_NEIGHBOR_SEARCH_TYPE_GCI_DEFAULT search type is performed to find the cells based on the history information. If a sufficient number of cells still has not been found, a GCI search with LTE_LC_NEIGHBOR_SEARCH_TYPE_GCI_EXTENDED_LIGHT search type is performed. For more details on GCI search, see location_cellular_config.cell_count.

  • The cloud location method handles sending cell information to the selected location service and getting the calculated location back to the device.

• Wi-Fi positioning

  • Uses Zephyr’s Network Management API Network Management for getting a list of nearby Wi-Fi access points.

  • The cloud location method handles sending access point information to the selected location service and getting the calculated location back to the device.

The cloud location method handles the location methods (cellular and Wi-Fi positioning) that scan for technology-specific information and sends it over to the cloud service for location resolution. If the following conditions are met, Wi-Fi and cellular scan results are combined into a single cloud request:

• Methods are one after the other in the location request method list.

• Location request mode is LOCATION_REQ_MODE_FALLBACK.

• Requested cloud service for Wi-Fi and cellular is the same.

A special LOCATION_METHOD_WIFI_CELLULAR method can appear within the location_event_data structure, but it cannot be added into the location configuration passed to the location_request() function.

The default priority order of location methods is GNSS positioning, Wi-Fi positioning and Cellular positioning. If any of these methods are disabled, the method is simply omitted from the list.

Here are details related to the services handling cell information for cellular positioning, or access point information for Wi-Fi positioning:

• Services can be handled by the application by enabling the CONFIG_LOCATION_SERVICE_EXTERNAL Kconfig option, in which case rest of the service configurations are ignored.

• The service is selected in the location_method_config structure when requesting for location.

• The services available are nRF Cloud Location Services and HERE Positioning.

• The data transport method for the nRF Cloud Location Services can be configured to either MQTT (CONFIG_NRF_CLOUD_MQTT) or REST (CONFIG_NRF_CLOUD_REST).

• The only data transport method with HERE Positioning service is REST.

Diagrams

In this section, the diagrams illustrate the use of the Location library when the CONFIG_LOCATION_SERVICE_EXTERNAL Kconfig option is set.

The following diagram shows the basic case when GNSS fix is found.

The following diagram shows successful cellular positioning.

The following diagram depicts a failure to find the GNSS fix, followed by a fallback to cloud positioning. Since the Wi-Fi and cellular positioning methods are one after another, they are combined to a single cloud positioning request. Both Wi-Fi APs and LTE cells are given to the application with a single LOCATION_EVT_CLOUD_LOCATION_EXT_REQUEST event. The LOCATION_EVT_STARTED and the LOCATION_EVT_FALLBACK events are sent, if the CONFIG_LOCATION_DATA_DETAILS Kconfig option is set.

The following diagram illustrates a case where Wi-Fi is used as first priority location method, and its result is unknown. A fallback is performed to GNSS.

Requirements

nRF Cloud certificates

When using nRF Cloud for any location data, you must have the certificate provisioned. See Updating the nRF Cloud certificate for more information. An nRF91 Series DK comes pre-provisioned with certificates for nRF Cloud.

Location service accounts

To use the location services that provide A-GNSS or P-GPS, cellular or Wi-Fi positioning data, see the respective documentation for setting up your account and getting the required credentials for authentication:

• nRF Cloud Location Services

• HERE Positioning

You can configure the required credentials for the location services using Kconfig options.

Wi-Fi chip

None of the supported DKs have an integrated Wi-Fi chip. You can use an external Wi-Fi chip, such as nRF7002 EK, and connect it to the nRF91 Series DK.

Library files

This library is found under lib/location in the nRF Connect SDK folder structure.

Configuration

Configure the following Kconfig options to enable this library:

• CONFIG_LOCATION - Enables the Location library.

• CONFIG_NRF_MODEM_LIB - Enable modem library.

• CONFIG_LTE_LINK_CONTROL - Enable LTE link control.

Configure the following Kconfig options to enable Wi-Fi interface:

• CONFIG_WIFI - Enable Wi-Fi for Zephyr.

The chosen Wi-Fi device needs to be set in devicetree:

chosen {
  ncs,location-wifi = &mywifi;
};

Configure the following options to enable location methods of your choice:

• CONFIG_LOCATION_METHOD_GNSS - Enables GNSS location method.

• CONFIG_LOCATION_METHOD_CELLULAR - Enables cellular location method.

• CONFIG_LOCATION_METHOD_WIFI - Enables Wi-Fi location method.

The following options control the use of GNSS assistance data:

• CONFIG_LOCATION_SERVICE_EXTERNAL - Enables A-GNSS and P-GPS data retrieval, and cellular cell information and Wi-Fi APs sending to an external source, implemented separately by the application. If enabled, the library triggers a LOCATION_EVT_GNSS_ASSISTANCE_REQUEST, LOCATION_EVT_GNSS_PREDICTION_REQUEST or LOCATION_EVT_CLOUD_LOCATION_EXT_REQUEST event when additional information is needed. Once the application has obtained necessary information, it must call the location_agnss_data_process(), the location_pgps_data_process(), or the location_cloud_location_ext_result_set() function, respectively, to feed it into the library.

• CONFIG_NRF_CLOUD_AGNSS - Enables A-GNSS data retrieval from nRF Cloud.

• CONFIG_NRF_CLOUD_PGPS - Enables P-GPS data retrieval from nRF Cloud.

• CONFIG_NRF_CLOUD_AGNSS_FILTERED - Reduces assistance size by only downloading ephemerides for visible satellites. See Filtered ephemerides for more details.

The following option is useful when setting CONFIG_NRF_CLOUD_AGNSS_FILTERED:

• CONFIG_NRF_CLOUD_AGNSS_ELEVATION_MASK - Sets elevation threshold angle.

The obstructed visibility feature is based on the fact that the number of satellites found indoors or in other environments with limited sky-view is severely decreased. The following options control the sensitivity of obstructed visibility detection:

• CONFIG_LOCATION_METHOD_GNSS_VISIBILITY_DETECTION_EXEC_TIME - Cut-off time for stopping GNSS.

• CONFIG_LOCATION_METHOD_GNSS_VISIBILITY_DETECTION_SAT_LIMIT - Minimum number of satellites that must be found to continue the search beyond CONFIG_LOCATION_METHOD_GNSS_VISIBILITY_DETECTION_EXEC_TIME.

These options set the threshold for how many satellites need to be found in how long a time period in order to conclude that the device is likely not indoors. Configuring the obstructed visibility detection is always a tradeoff between power consumption and the accuracy of detection.

The following options control the transport method used with nRF Cloud:

• CONFIG_NRF_CLOUD_REST - Uses REST APIs to communicate with nRF Cloud if CONFIG_NRF_CLOUD_MQTT is not set.

• CONFIG_NRF_CLOUD_MQTT - Uses MQTT transport to communicate with nRF Cloud.

Both cellular and Wi-Fi location services are handled externally by the application or selected using the runtime configuration, in which case you must first configure the available services. Use at least one of the following sets of options:

• CONFIG_LOCATION_SERVICE_EXTERNAL

• CONFIG_LOCATION_SERVICE_NRF_CLOUD

• CONFIG_LOCATION_SERVICE_HERE and CONFIG_LOCATION_SERVICE_HERE_API_KEY

The following options are related to the HERE service and can usually have the default values:

• CONFIG_LOCATION_SERVICE_HERE_HOSTNAME

• CONFIG_LOCATION_SERVICE_HERE_TLS_SEC_TAG

The following options control the default location request configurations and are applied when location_config_defaults_set() function is called:

• CONFIG_LOCATION_REQUEST_DEFAULT_METHOD_FIRST - Choice symbol for first priority location method.

• CONFIG_LOCATION_REQUEST_DEFAULT_METHOD_SECOND - Choice symbol for second priority location method.

• CONFIG_LOCATION_REQUEST_DEFAULT_METHOD_THIRD - Choice symbol for third priority location method.

• CONFIG_LOCATION_REQUEST_DEFAULT_INTERVAL

• CONFIG_LOCATION_REQUEST_DEFAULT_TIMEOUT

• CONFIG_LOCATION_REQUEST_DEFAULT_GNSS_TIMEOUT

• CONFIG_LOCATION_REQUEST_DEFAULT_GNSS_ACCURACY

• CONFIG_LOCATION_REQUEST_DEFAULT_GNSS_NUM_CONSECUTIVE_FIXES

• CONFIG_LOCATION_REQUEST_DEFAULT_GNSS_VISIBILITY_DETECTION

• CONFIG_LOCATION_REQUEST_DEFAULT_GNSS_PRIORITY_MODE

• CONFIG_LOCATION_REQUEST_DEFAULT_CELLULAR_TIMEOUT

• CONFIG_LOCATION_REQUEST_DEFAULT_CELLULAR_CELL_COUNT

• CONFIG_LOCATION_REQUEST_DEFAULT_WIFI_TIMEOUT

The following option adds more details to the location_event_data structure:

• CONFIG_LOCATION_DATA_DETAILS

Usage

To use the Location library, perform the following steps:

1. Initialize the library with the location_init() function.

2. Create the configuration (location_config structure).

3. Set the default values by passing the configuration to the location_config_defaults_set() function together with the list of method types.

4. Set any required non-default values to the structures.

5. Call the location_request() function with the configuration.

You can use the location_request() function in different ways, as in the following examples.

Use default values for location configuration:

int err;

err = location_request(NULL);

Use GNSS and cellular and set custom timeout values for them:

int err;
struct location_config config;
enum location_method methods[] = {LOCATION_METHOD_GNSS, LOCATION_METHOD_CELLULAR};

location_config_defaults_set(&config, ARRAY_SIZE(methods), methods);

/* Now you have default values set and here you can modify the parameters you want */
config.timeout = 180 * MSEC_PER_SEC;
config.methods[0].gnss.timeout = 90 * MSEC_PER_SEC;
config.methods[1].cellular.timeout = 15 * MSEC_PER_SEC;

err = location_request(&config);

Use method priority list defined by Kconfig options and set custom timeout values for entire location_request() operation and cellular positioning:

int err;
struct location_config config;

location_config_defaults_set(&config, 0, NULL);

/* Now you have default values set and you can modify the parameters you want but you
 * need to iterate through the method list as the order is defined by Kconfig options.
 */
for (int i = 0; i < config.methods_count; i++) {
    if (config.methods[i].method == LOCATION_METHOD_CELLULAR) {
        config.methods[i].cellular.timeout = 15 * MSEC_PER_SEC;
    }
}

err = location_request(&config);

Samples using the library

The following nRF Connect SDK applications and samples use this library:

• Asset Tracker v2

• Cellular: Location

• Cellular: Modem Shell

• Cellular: nRF Cloud multi-service

Limitations

• The Location library can only have one application registered at a time. If there is already an application handler registered, another initialization will override the existing handler.

Dependencies

This library uses the following nRF Connect SDK libraries:

• Modem library integration layer

• LTE link control

• REST client

• nRF Cloud

• nRF Cloud A-GNSS

• nRF Cloud P-GPS

• nRF Cloud REST

• Modem JWT

It uses the following sdk-nrfxlib library:

• Global Navigation Satellite System

It uses the following Zephyr libraries:

• Network Management

• Network Interface

API documentation

Header file: include/modem/location.h

Source files: lib/location/

Location library