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 GNSS interface 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:

• GNSS interface

It uses the following Zephyr libraries:

• Network Management

• Network Interface

API documentation

Header file: include/modem/location.h

Source files: lib/location

group location

Typedefs

typedef void (*location_event_handler_t)(const struct location_event_data *event_data)

Event handler prototype.

Param event_data:

[in] Event data.

Enums

enum location_method

Location method.

Values:

enumerator LOCATION_METHOD_CELLULAR

LTE cellular positioning.

enumerator LOCATION_METHOD_GNSS

Global Navigation Satellite System (GNSS).

enumerator LOCATION_METHOD_WIFI

Wi-Fi positioning.

enumerator LOCATION_METHOD_WIFI_CELLULAR

Wi-Fi and cellular positioning combined into one cloud request.

Cannot be used in the method list passed to location_request(), but this method can appear in the location event (location_event_data::id) to indicate that Wi-Fi and cellular positioning methods have been combined into a single cloud location method.

If the combined method is desired, set Wi-Fi and cellular methods next to each other in the method list passed to location_request(). This also happens by default if NULL configuration is passed to location_request().

enum location_req_mode

Location acquisition mode.

Values:

enumerator LOCATION_REQ_MODE_FALLBACK

Fallback to next preferred method (default).

enumerator LOCATION_REQ_MODE_ALL

All requested methods are used sequentially.

enum location_event_id

Event IDs.

Values:

enumerator LOCATION_EVT_LOCATION

Location update.

enumerator LOCATION_EVT_TIMEOUT

Getting location timed out.

enumerator LOCATION_EVT_ERROR

An error occurred when trying to get the location.

enumerator LOCATION_EVT_RESULT_UNKNOWN

Application has indicated that getting location has been completed, the result is not known, and the Location library does not need to care about it.

This event can occur only if CONFIG_LOCATION_SERVICE_EXTERNAL is set.

enumerator LOCATION_EVT_GNSS_ASSISTANCE_REQUEST

GNSS is requesting A-GNSS data.

Application should obtain the data and send it to location_agnss_data_process().

enumerator LOCATION_EVT_GNSS_PREDICTION_REQUEST

GNSS is requesting P-GPS data.

Application should obtain the data and send it to location_pgps_data_process().

enumerator LOCATION_EVT_CLOUD_LOCATION_EXT_REQUEST

Cloud location request with neighbor cell and/or Wi-Fi access point information is available.

The application should send the information to cloud services and then call location_cloud_location_ext_result_set().

enumerator LOCATION_EVT_STARTED

Location request has been started.

This event is only sent if CONFIG_LOCATION_DATA_DETAILS is set.

enumerator LOCATION_EVT_FALLBACK

A fallback from one method to another has occurred, and the positioning procedure continues.

This event is only sent if CONFIG_LOCATION_DATA_DETAILS is set and location_config::mode is LOCATION_REQ_MODE_FALLBACK.

enum location_ext_result

Result of the external cloud location request.

Values:

enumerator LOCATION_EXT_RESULT_SUCCESS

Cloud location request was successful.

enumerator LOCATION_EXT_RESULT_UNKNOWN

The result of the cloud location request is unknown.

From the fallback functionality perspective, this is handled similarly to LOCATION_EXT_RESULT_ERROR.

enumerator LOCATION_EXT_RESULT_ERROR

Cloud location request failed.

enum location_accuracy

Location accuracy.

Values:

enumerator LOCATION_ACCURACY_LOW

Allow lower accuracy to conserve power.

enumerator LOCATION_ACCURACY_NORMAL

Normal accuracy.

enumerator LOCATION_ACCURACY_HIGH

Try to improve accuracy. Increases power consumption.

enum location_service

Location service.

Values:

enumerator LOCATION_SERVICE_ANY

Use any location service that has been configured to be available.

This is useful when only one service is configured but can also be used even if several services are available.

enumerator LOCATION_SERVICE_NRF_CLOUD

nRF Cloud location service.

enumerator LOCATION_SERVICE_HERE

HERE location service.

Functions

int location_handler_register(location_event_handler_t handler)

Register handler for location events.

This function is not needed for clients that call location_init() and pass event handler into it.

Multiple event handlers can be registered.

Parameters:

• handler – [in] Event handler.

Return values:

• -EINVAL – The handler was a NULL pointer.

• -ENOMEM – Out of memory.

Returns:

0 on success, or negative error code on failure.

int location_handler_deregister(location_event_handler_t handler)

Deregister handler for location events.

Parameters:

• handler – [in] Event handler.

Return values:

-EINVAL – The handler was not found or it was a NULL pointer.

Returns:

0 on success, or negative error code on failure.

int location_init(location_event_handler_t handler)

Initializes the library.

Initializes the library and sets the event handler function. The first call to this function must be called before going to LTE normal mode. This can be called multiple times, which sets the event handler again.

Parameters:

• handler – [in] Event handler function.

Return values:

• -EINVAL – Given event_handler is NULL.

• -EFAULT – Failed to obtain Wi-Fi interface.

Returns:

0 on success, or negative error code on failure.

int location_request(const struct location_config *config)

Requests the current position or starts periodic position updates.

Requests the current position using the given configuration. Depending on the configuration, a single position or periodic position updates are given. If the position request is successful, the results are delivered to the event handler function in LOCATION_EVT_LOCATION event. Otherwise LOCATION_EVT_TIMEOUT or LOCATION_EVT_ERROR event is triggered.

In periodic mode, position update is always attempted after the configured interval regardless of the outcome of any previous attempt. Periodic position updates can be stopped by calling location_cancel().

Parameters:

• config – [in] Used configuration or NULL to get a single position update with the default configuration. Default configuration has the following location methods in priority order (if they are enabled in library configuration): GNSS, Wi-Fi and Cellular.

Return values:

• -EPERM – Library not initialized.

• -EBUSY – Previous location request still ongoing.

• -EINVAL – Invalid configuration given.

Returns:

0 on success, or negative error code on failure.

int location_request_cancel(void)

Cancels periodic position updates.

Return values:

-EPERM – Library not initialized.

Returns:

0 on success, or negative error code on failure.

void location_config_defaults_set(struct location_config *config, uint8_t methods_count, enum location_method *method_types)

Sets the default values to a given configuration.

Parameters:

• config – [inout] Configuration to be supplied with default values.

• methods_count – [in] Number of location methods. This must not exceed CONFIG_LOCATION_METHODS_LIST_SIZE .

• method_types – [in] List of location method types in priority order. Location methods with these types are initialized with default values into given configuration. List size must be as given in ‘methods_count’.

const char *location_method_str(enum location_method method)

Return location method as a string.

Parameters:

• method – [in] Location method.

Returns:

Location method in string format. Returns “Unknown” if given method is not known.

const struct location_data_details *location_details_get(const struct location_event_data *event_data)

Get location data details from the location event data.

The location_data_details structure is located in a different place in the location_event_data structure depending on the event ID. This is a helper function to provide the location_data_details structure.

Parameters:

• event_data – [in] Event data.

Returns:

Location data details. NULL if there is no location_data_details structure for the provided event.

int location_agnss_data_process(const char *buf, size_t buf_len)

Feed in A-GNSS data to be processed by library.

If Location library is not receiving A-GNSS assistance data directly from nRF Cloud, it triggers the LOCATION_EVT_GNSS_ASSISTANCE_REQUEST event when assistance is needed. Once application has obtained the assistance data it can be handed over to Location library using this function.

Note that the data must be formatted similarly to the nRF Cloud A-GNSS data, see for example nrf_cloud_agnss_schema_v1.h.

Parameters:

• buf – [in] Data received.

• buf_len – [in] Buffer size of data to be processed.

Return values:

• -EINVAL – Given buffer is NULL or buffer length zero.

• -ENOTSUP – CONFIG_LOCATION_SERVICE_EXTERNAL is not set.

Returns:

0 on success, or negative error code on failure.

int location_pgps_data_process(const char *buf, size_t buf_len)

Feed in P-GPS data to be processed by library.

If Location library is not receiving P-GPS assistance data directly from nRF Cloud, it triggers the LOCATION_EVT_GNSS_PREDICTION_REQUEST event when assistance is needed. Once application has obtained the assistance data it can be handed over to Location library using this function.

Note that the data must be formatted similarly to the nRF Cloud P-GPS data, see for example nrf_cloud_pgps_schema_v1.h.

Parameters:

• buf – [in] Data received.

• buf_len – [in] Buffer size of data to be processed.

Return values:

• -EINVAL – Given buffer is NULL or buffer length zero.

• -ENOTSUP – CONFIG_LOCATION_SERVICE_EXTERNAL is not set.

Returns:

0 on success, or negative error code on failure.

void location_cloud_location_ext_result_set(enum location_ext_result result, struct location_data *location)

Pass cloud location result to the library.

If the Location library is not receiving cloud location directly from the services, it triggers the LOCATION_EVT_CLOUD_LOCATION_EXT_REQUEST event, that indicates the LTE neighbor cell and/or Wi-Fi access point information is ready to be sent to cloud services for location resolution. Then, the application responds with the result.

In addition to ‘success’ and ‘error’ results, the application can indicate that the result is ‘unknown’ with LOCATION_EXT_RESULT_UNKNOWN. This is useful when the application wants the Location library to proceed irrespective of the outcome. The Location library will try to perform a fallback to the next method, if available, just like in a failure case. If there are no more methods, LOCATION_EVT_RESULT_UNKNOWN event will be sent to the application.

Parameters:

• result – [in] Result of the external cloud location request.

• location – [in] Cloud location data. Will be used only if result is LOCATION_EXT_RESULT_SUCCESS.

struct location_datetime

#include <location.h>

Date and time (UTC).

Public Members

bool valid

True if date and time are valid, false if not.

uint16_t year

4-digit representation (Gregorian calendar).

uint8_t month

1…12

uint8_t day

1…31

uint8_t hour

0…23

uint8_t minute

0…59

uint8_t second

0…59

uint16_t ms

0…999

struct location_data_details_gnss

#include <location.h>

Location details for GNSS.

Public Members

uint8_t satellites_tracked

Number of satellites tracked at the time of event.

uint8_t satellites_used

Number of satellites used at the time of event.

struct nrf_modem_gnss_pvt_data_frame pvt_data

PVT data.

uint32_t elapsed_time_gnss

Elapsed GNSS time in milliseconds.

This is the time since last start of GNSS operation until the fix or timeout including any time LTE has blocked GNSS.

pvt_data member has execution_time, which indicates cumulative GNSS execution time since last start excluding any time LTE has blocked GNSS.

struct location_data_details_cellular

#include <location.h>

Location details for cellular.

Public Members

uint8_t ncells_count

Number of neighbor cells.

uint8_t gci_cells_count

Number of GCI (surrounding) cells.

struct location_data_details_wifi

#include <location.h>

Location details for Wi-Fi.

Public Members

uint16_t ap_count

Number of Wi-Fi APs.

struct location_data_details

#include <location.h>

Location details.

Only one of the child structures is filled most of the time depending on the method found in location_event_data::method member of the parent structure. For a combined method LOCATION_METHOD_WIFI_CELLULAR both cellular and wifi are filled.

Public Members

uint32_t elapsed_time_method

Elapsed method time in milliseconds.

This is the time from method start until it completes and includes any time spent waiting for some conditions to happen before proceeding, such as waiting for LTE connection to go idle for some methods.

struct location_data_details_cellular cellular

Location details for cellular.

struct location_data_details_wifi wifi

Location details for Wi-Fi.

struct location_data

#include <location.h>

Location data.

Public Members

double latitude

Geodetic latitude (deg) in WGS-84.

double longitude

Geodetic longitude (deg) in WGS-84.

float accuracy

Location accuracy in meters (1-sigma).

struct location_datetime datetime

Date and time (UTC).

struct location_data_details details

Location details.

struct location_data_error

#include <location.h>

Location error information.

Public Members

struct location_data_details details

Data details at the time of error.

struct location_data_unknown

#include <location.h>

Information for an unknown location result.

Public Members

struct location_data_details details

Data details at the time of an unknown location result.

struct location_data_fallback

#include <location.h>

Location fallback information.

Public Members

enum location_method next_method

New location method that is tried next.

enum location_event_id cause

Event ID indicating the cause for the fallback.

Either LOCATION_EVT_TIMEOUT and LOCATION_EVT_ERROR.

struct location_data_details details

Data details at the time of a timeout or an error that caused the fallback.

struct location_data_cloud

#include <location.h>

Cloud location information.

Public Members

const struct lte_lc_cells_info *cell_data

Cellular cell information.

const struct wifi_scan_info *wifi_data

Wi-Fi access point information.

struct location_event_data

#include <location.h>

Location event data.

Public Members

enum location_event_id id

Event ID.

enum location_method method

Used location method.

struct location_data location

Current location, used with event LOCATION_EVT_LOCATION.

struct location_data_error error

Relevant location data when a timeout or an error occurs. Used with events LOCATION_EVT_TIMEOUT and LOCATION_EVT_ERROR.

struct location_data_unknown unknown

Relevant location data when an unknown result occurs. Used with event LOCATION_EVT_RESULT_UNKNOWN.

struct location_data_fallback fallback

Relevant location data when a fallback to another method occurs due to a timeout or an error. Used with event LOCATION_EVT_FALLBACK.

struct nrf_modem_gnss_agnss_data_frame agnss_request

A-GNSS notification data frame used by GNSS to let the application know it needs new assistance data, used with event LOCATION_EVT_GNSS_ASSISTANCE_REQUEST.

struct gps_pgps_request pgps_request

P-GPS notification data frame used by GNSS to let the application know it needs new assistance data, used with event LOCATION_EVT_GNSS_PREDICTION_REQUEST.

struct location_data_cloud cloud_location_request

Cloud location information to let the application know it should send these to a cloud service to resolve the location. Used with event LOCATION_EVT_CLOUD_LOCATION_EXT_REQUEST.

union location_event_data.[anonymous] [anonymous]

Event specific data.

struct location_gnss_config

#include <location.h>

GNSS configuration.

Public Members

int32_t timeout

Timeout (in milliseconds), meaning how long GNSS is allowed to run when trying to acquire a fix. SYS_FOREVER_MS means that the timer is disabled, meaning that GNSS will continue to search until it gets a fix or the application calls cancel.

Note that this is not real time as experienced by the user. Since GNSS cannot run while LTE is operating, the running time is counted from the instant when GNSS is allowed to start. Library waits until RRC connection is inactive before starting GNSS. If LTE power saving mode (PSM) is enabled and A-GNSS is disabled, library waits until modem enters PSM before starting GNSS, thus maximizing uninterrupted operating window and minimizing power consumption.

Default value is 120000 (2 minutes). It is applied when location_config_defaults_set() function is called and can be changed at build time with CONFIG_LOCATION_REQUEST_DEFAULT_GNSS_TIMEOUT configuration.

enum location_accuracy accuracy

Desired accuracy level.

If accuracy is set to LOCATION_ACCURACY_LOW, GNSS relaxes the criteria for a qualifying fix and may produce fixes using only three satellites.

If accuracy is set to LOCATION_ACCURACY_HIGH, instead of using the first fix, GNSS is allowed to run for a longer time. This typically improves the location accuracy.

Default value is LOCATION_ACCURACY_NORMAL. It is applied when location_config_defaults_set() function is called and can be changed at build time with CONFIG_LOCATION_REQUEST_DEFAULT_GNSS_ACCURACY choice configuration.

uint8_t num_consecutive_fixes

The number of fixes GNSS is allowed to produce before the library outputs the current location when accuracy is set to LOCATION_ACCURACY_HIGH.

If accuracy is set to LOCATION_ACCURACY_NORMAL or LOCATION_ACCURACY_LOW this parameter has no effect.

Default value is 3. It is applied when location_config_defaults_set() function is called and can be changed at build time with CONFIG_LOCATION_REQUEST_DEFAULT_GNSS_NUM_CONSECUTIVE_FIXES configuration.

bool visibility_detection

Obstructed visibility detection. If set to true, the library tries to detect situations where getting a GNSS fix is unlikely or would consume a lot of energy. When such a situation is detected, GNSS is stopped without waiting for a fix or a timeout.

See Kconfig for related configuration options.

Default value is false. It is applied when location_config_defaults_set() function is called and can be changed at build time with CONFIG_LOCATION_REQUEST_DEFAULT_GNSS_VISIBILITY_DETECTION configuration.

Note

Only supported with modem firmware v1.3.2 or later.

bool priority_mode

Enable GNSS priority mode if GNSS does not get enough runtime due to LTE idle mode operations.

If set to true, the library triggers GNSS priority mode if five consecutive PVT messages indicate that GNSS is blocked by LTE idle mode operations. This is especially helpful if A-GNSS or P-GPS is not enabled or downloading assistance data fails and GNSS module has to decode navigation data from the satellite broadcast. Priority mode is disabled automatically after the first fix or after 40 seconds.

If the device attempts to send data during the priority mode, it will be buffered and sent after the priority time window ends. In case of mobile terminated data reception during the priority mode the network will typically buffer the data and sent them to the device once the priority time window ends. However, it is possible that the network drops the data, or some protocol timer expires causing data transfer to fail.

Default value is false. It is applied when location_config_defaults_set() function is called and can be changed at build time with CONFIG_LOCATION_REQUEST_DEFAULT_GNSS_PRIORITY_MODE configuration.

struct location_cellular_config

#include <location.h>

LTE cellular positioning configuration.

Public Members

int32_t timeout

Timeout (in milliseconds) of how long the cellular positioning procedure can take. SYS_FOREVER_MS means that the timer is disabled.

Default value is 30000 (30 seconds). It is applied when location_config_defaults_set() function is called and can be changed at build time with CONFIG_LOCATION_REQUEST_DEFAULT_CELLULAR_TIMEOUT configuration.

Timeout only applies to neighbor cell search, not the cloud communication. Timeout for the entire location request specified in location_config structure is still valid. When CONFIG_LOCATION_SERVICE_EXTERNAL is enabled, this timeout stops when event LOCATION_EVT_CLOUD_LOCATION_EXT_REQUEST is sent. However, timeout specified in location_config structure is still valid.

enum location_service service

Used cellular positioning service.

Default value is LOCATION_SERVICE_ANY. It is applied when location_config_defaults_set() function is called.

This parameter is ignored when CONFIG_LOCATION_SERVICE_EXTERNAL is enabled.

uint8_t cell_count

Number of cells to be requested for cellular positioning.

Default value is 4. It is applied when location_config_defaults_set() function is called and can be changed at build time with CONFIG_LOCATION_REQUEST_DEFAULT_CELLULAR_CELL_COUNT configuration.

Maximum value is 15.

The number of cells mean GCI cells including current cell. Normal neighbor cells are received and used but they do not count towards the cell count. If the number of cells is bigger than one, GCI (surrounding) cells are requested. Hence, zero and one mean that only normal neighbor cell search is performed but no GCI search.

Note that even if there are a lot of cells available, the number of cells used for positioning may be lower than the requested number of cells due to the behavior of the search algorithm. Also, the number of cells used for positioning may be higher than the requested number of cells if there are more cells in the history information (including current cell).

struct location_wifi_config

#include <location.h>

Wi-Fi positioning configuration.

Public Members

int32_t timeout

Timeout (in milliseconds) of how long the Wi-Fi positioning procedure can take. SYS_FOREVER_MS means that the timer is disabled.

Default value is 30000 (30 seconds). It is applied when location_config_defaults_set() function is called and can be changed at build time with CONFIG_LOCATION_REQUEST_DEFAULT_WIFI_TIMEOUT configuration.

Timeout only applies to Wi-Fi scan, not the cloud communication. Timeout for the entire location request specified in location_config structure is still valid.

When CONFIG_LOCATION_SERVICE_EXTERNAL is enabled, this timeout stops when event LOCATION_EVT_CLOUD_LOCATION_EXT_REQUEST is sent. However, timeout specified in location_config structure is still valid.

enum location_service service

Used Wi-Fi positioning service.

Default value is LOCATION_SERVICE_ANY. It is applied when location_config_defaults_set() function is called.

This parameter is ignored when CONFIG_LOCATION_SERVICE_EXTERNAL is enabled.

struct location_method_config

#include <location.h>

Location method configuration.

Public Members

enum location_method method

Location method.

struct location_cellular_config cellular

Configuration for LOCATION_METHOD_CELLULAR.

struct location_gnss_config gnss

Configuration for LOCATION_METHOD_GNSS.

struct location_wifi_config wifi

Configuration for LOCATION_METHOD_WIFI.

struct location_config

#include <location.h>

Location request configuration.

Public Members

uint8_t methods_count

Number of location methods in ‘methods’.

struct location_method_config methods[CONFIG_LOCATION_METHODS_LIST_SIZE]

Selected location methods and associated configurations in priority order.

Index 0 has the highest priority. Number of used methods is indicated in ‘methods_count’ and it can be smaller than the size of this table.

Wi-Fi and cellular scan results are combined into single cloud request, that is, these methods are handled together, if the following conditions are met:

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

• mode is LOCATION_REQ_MODE_FALLBACK

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

uint16_t interval

Position update interval in seconds.

Set to 0 for a single position update. For periodic position updates the valid range is 1…65535 seconds.

Default value is 0. It is applied when location_config_defaults_set() function is called and can be changed at build time with CONFIG_LOCATION_REQUEST_DEFAULT_INTERVAL configuration.

int32_t timeout

Timeout (in milliseconds) for the entire location request.

SYS_FOREVER_MS means that the timer is disabled.

Default value is 300000 (5 minutes). It is applied when location_config_defaults_set() function is called and can be changed at build time with CONFIG_LOCATION_REQUEST_DEFAULT_TIMEOUT configuration.

This is intended to be a safety timer preventing location request from getting stuck in any of its phases, because parts of the method-specific functionality are not covered by method-specific timeouts. You should use a rather large value that can be one minute or more larger than the sum of method-specific timeouts.

enum location_req_mode mode

Location acquisition mode.

Default value is LOCATION_REQ_MODE_FALLBACK. It is applied when location_config_defaults_set() function is called.