Location module

The location module controls the GNSS, cellular and Wi-Fi positioning functionality. It can be used to retrieve the location of the device in the form of events containing a position, velocity and time (PVT) structure.

Features

This section documents the various features implemented by the module.

Location control

The module uses the Location library to communicate with the nRF91 Series modem and control its GNSS and LTE neighbor cell measurement functionalities as well as with the nRF7002 Wi-Fi positioning functionality. A location request starts when the module receives an APP_EVT_DATA_GET event and the APP_DATA_LOCATION type is listed in the event’s data_list member containing the data types that shall be sampled.

The default configuration for the location request is set as follows:

  • GNSS, Wi-Fi and cellular positioning are set in priority order of the location methods. Wi-Fi is omitted if it is not built into the application. If GNSS fails, both Wi-Fi and cellular positioning are tried. The priority order of the methods can be changed through Location library Kconfig options. Methods that should not be used can be configured by adding them into No Data List. See Real-time configurations for more information.

  • Timeout, which can be configured as part of Real-time configurations with Location timeout.

The location module receives configuration updates as payload in the following two events:

  • DATA_EVT_CONFIG_INIT - The event contains the value configured at build time or received from cloud and stored to flash. The event is distributed from the data module as part of the application initialization.

  • DATA_EVT_CONFIG_READY - The event is received when the data module has processed an incoming message from cloud with a configuration update.

The module sends the following events based on the outcome of the location request:

GNSS LNA configuration

Different devices have different GNSS antenna and LNA setups depending on the antenna type (onboard or external). The application uses the Modem antenna library for configuring the LNA. The library has Kconfig options to control the LNA using either the COEX0 or MAGPIO interface of the nRF91 Series device. See the library documentation for more details on how to configure the antenna and LNA.

GPS assistance data

The location module receives requests for GPS assistance data from the Location library. When the module receives an A-GNSS request, it distributes it to the other modules as a LOCATION_MODULE_EVT_AGNSS_NEEDED event that contains information about the type of assistance data needed. Providing the requested A-GNSS data typically reduces significantly the time it takes to acquire a GNSS fix.

Wi-Fi positioning

Wi-Fi positioning is supported with an nRF7002 EK on the nRF91 Series DK. To enable Wi-Fi positioning and especially nRF7002 functionality, use the -DSHIELD=nrf7002ek and -DEXTRA_CONF_FILE=overlay-nrf7002ek-wifi-scan-only.conf options. The following is an example of the CLI command:

 west build -p -b board_target -- -DSHIELD=nrf7002ek -DEXTRA_CONF_FILE=overlay-nrf7002ek-wifi-scan-only.conf

Replace the board_target with the board target of the DK you are using (see Requirements).

Wi-Fi positioning has the following limitations:

  • Only nRF Cloud is supported.

  • The UI module must be disabled. Functionalities related to LEDs and buttons have conflicts with the nRF7002 EK.

Note

The Wi-Fi configuration uses both flash and SRAM extensively. You can configure the number of scan results with the CONFIG_LOCATION_METHOD_WIFI_SCANNING_RESULTS_MAX_CNT Kconfig option to reduce SRAM consumption. Align the CONFIG_NRF_WIFI_SCAN_MAX_BSS_CNT Kconfig option with CONFIG_LOCATION_METHOD_WIFI_SCANNING_RESULTS_MAX_CNT. You can also change the value of the CONFIG_HEAP_MEM_POOL_SIZE Kconfig option.

Module internals

The location module is a threadless module in terms of message processing. In this sense, it differs from many other modules.

All incoming events from other modules are handled in the context of the Application Event Manager callback, because they all complete fast enough to not require a separate thread.

The Location library handles cellular and Wi-Fi positioning together when the location request method list has them next to each other. This means that LTE neighbor cell measurements and Wi-Fi scanning results are combined into the same LOCATION_EVT_CLOUD_LOCATION_EXT_REQUEST event.

The location module sends the cellular and Wi-Fi positioning request forward with LOCATION_MODULE_EVT_CLOUD_LOCATION_DATA_READY event, and waits for an event from the cloud module on the result of the positioning. This result is forwarded to the Location library. Depending on the cloud integration, positioning result from the cloud service might be requested or not. The result must be indicated with one of the following events:

Configuration options

CONFIG_LOCATION_MODULE

Enables the location module.

Module states

The location module has an internal state machine with the following states:

  • STATE_INIT - The initial state of the module in which it awaits the modem to be initialized and receive the location related configuration.

  • STATE_RUNNING - The module has performed all required initialization and can respond to requests to start a location request. The running state has two sub-states:

    • SUB_STATE_SEARCH - A location request is ongoing.

    • SUB_STATE_IDLE - The module is idling and can respond to a request to start a location request.

  • STATE_SHUTDOWN - The module has been shut down after receiving a request from the utility module.

State transitions take place based on input from other modules, such as the application module, data module, utility module and modem module.

Module events

The asset_tracker_v2/src/events/location_module_event.h header file contains a list of events sent by the location module with associated payload.

Dependencies

The module uses the following nRF Connect SDK libraries:

API documentation

Header file: asset_tracker_v2/src/events/location_module_event.h
Source files: asset_tracker_v2/src/events/location_module_event.c
group location_module_event

Location module event.

Enums

enum location_module_event_type

Location event types submitted by location module.

Values:

enumerator LOCATION_MODULE_EVT_GNSS_DATA_READY

A valid GNSS location has been obtained and the data is ready to be used. The event has associated payload of the type location_module_data in the event struct member data.location. All struct members within data.location contain valid data.

enumerator LOCATION_MODULE_EVT_DATA_NOT_READY

Location could not be obtained and will not be ready for this sampling interval. The event has no associated payload.

enumerator LOCATION_MODULE_EVT_CLOUD_LOCATION_DATA_READY

Neighbor cell measurements and/or Wi-Fi access point information have been gathered and the data is ready. The event has associated payload of type location_module_cloud_location in the data.cloud_location member.

enumerator LOCATION_MODULE_EVT_TIMEOUT

The location search timed out without acquiring location. The event has associated payload of the type struct location_module_data in the event struct member data.location. The data.location struct member search_time contains valid data and satellites_tracked contain valid data for GNSS.

enumerator LOCATION_MODULE_EVT_ACTIVE

An active location search has started.

enumerator LOCATION_MODULE_EVT_INACTIVE

A location search has stopped, either as a result of timeout, error or acquired location.

enumerator LOCATION_MODULE_EVT_SHUTDOWN_READY

The module has been shut down gracefully. The event has associated payload of the type uint32 in the struct member data.id that contains the module ID used when acknowledging a shutdown request from the util module.

enumerator LOCATION_MODULE_EVT_AGNSS_NEEDED

The location library has reported that it needs GPS assistance data. The event has associated payload of the type struct nrf_modem_gnss_agnss_data_frame in the event struct member data.agnss_request, which contains the types of A-GNSS data that the modem needs.

enumerator LOCATION_MODULE_EVT_PGPS_NEEDED

The location library has reported that it needs GPS prediction data. The event has associated payload of the type struct gps_pgps_request in the event struct member data.pgps_request, which specifies the P-GPS data need.

enumerator LOCATION_MODULE_EVT_ERROR_CODE

An error has occurred, and data may have been lost. The event has associated payload of the type int in the struct member data.err, that contains the original error code that triggered the sending of this event.

struct location_module_pvt
#include <location_module_event.h>

Position, velocity and time (PVT) data.

Public Members

double latitude

Latitude in degrees.

double longitude

Longitude in degrees.

float accuracy

Position accuracy (2D 1-sigma) in meters.

float altitude

Altitude above WGS-84 ellipsoid in meters.

float altitude_accuracy

Altitude accuracy in meters.

float speed

Horizontal speed in m/s.

float speed_accuracy

Horizontal speed accuracy (1-sigma) in m/s.

float heading

Heading of user movement in degrees.

float heading_accuracy

Heading of user movement accuracy (1-sigma) in degrees.

struct location_module_neighbor_cells
#include <location_module_event.h>

Location module data for neighbor cells.

Public Members

struct lte_lc_cells_info cell_data

Information about the current cell.

struct lte_lc_ncell neighbor_cells[CONFIG_LTE_NEIGHBOR_CELLS_MAX]

Information about the neighbor cells.

int64_t timestamp

Uptime when the event was sent.

struct location_module_wifi_access_points
#include <location_module_event.h>

Location module data for Wi-Fi access points.

Public Members

struct wifi_scan_result ap_info[CONFIG_LOCATION_METHOD_WIFI_SCANNING_RESULTS_MAX_CNT]

Access points found during scan.

uint16_t cnt

The number of access points found during scan.

int64_t timestamp

Uptime when the event was sent.

struct location_module_cloud_location
#include <location_module_event.h>

Location module data for associated payload for event of LOCATION_MODULE_EVT_CLOUD_LOCATION_DATA_READY type.

Public Members

bool neighbor_cells_valid

Neighbor cell information is valid.

struct location_module_neighbor_cells neighbor_cells

Neighbor cells.

bool wifi_access_points_valid

Wi-Fi access point information is valid.

struct location_module_wifi_access_points wifi_access_points

Wi-Fi access points.

int64_t timestamp

Uptime when the event was sent.

struct location_module_data
#include <location_module_event.h>

Location module data for associated payload for events of LOCATION_MODULE_EVT_TIMEOUT and LOCATION_MODULE_EVT_GNSS_DATA_READY types.

Public Members

struct location_module_pvt pvt

Location data in the form of a PVT structure.

uint8_t satellites_tracked

Number of satellites tracked.

uint32_t search_time

Time when the search was initiated until fix or timeout occurred.

int64_t timestamp

Uptime when location was sampled.

struct location_module_event
#include <location_module_event.h>

Location module event.

Public Members

struct app_event_header header

Location module application event header.

enum location_module_event_type type

Location module event type.

struct location_module_data location

Data for event LOCATION_MODULE_EVT_GNSS_DATA_READY.

struct location_module_cloud_location cloud_location

Data for event LOCATION_MODULE_EVT_CLOUD_LOCATION_DATA_READY.

struct nrf_modem_gnss_agnss_data_frame agnss_request

Data for event LOCATION_MODULE_EVT_AGNSS_NEEDED.

struct gps_pgps_request pgps_request

Data for event LOCATION_MODULE_EVT_PGPS_NEEDED.

int err

Cause of the error for event LOCATION_MODULE_EVT_ERROR_CODE.

union location_module_event.[anonymous] data

Data for different events.