GNSS module

The GNSS module controls the GNSS functionality of the nRF9160. It can be used to acquire the location of the device, either in the form of events containing a position, velocity and time (PVT) structure or NMEA sentences.

Features

This section documents the various features implemented by the module.

GNSS control

The module uses the GNSS interface to communicate with the nRF9160 modem and control its GNSS functionality. A GNSS search is started when the module receives an APP_EVT_DATA_GET event and the APP_DATA_GNSS type is listed in the event’s data_list member containing the data types that shall be sampled.

The default GNSS configuration is set as follows:

  • Single-fix mode, where the GNSS searches for a defined interval until it acquires a position fix or times out.

  • Timeout set to either the value configured at build time or to the dynamically updated value set by the cloud side and stored to flash. Values stored in flash take precedence.

The GNSS 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.

When a position fix is acquired, the GNSS_EVT_DATA_READY event is sent from the module. If a timeout occurred, GNSS_EVT_TIMEOUT is sent.

LNA configuration

Different devices have different 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 nRF9160. See the library documentation for more details on how to configure the antenna and LNA.

GPS assistance data

The GNSS module receives requests for GPS assistance data from the nRF9160 modem. When an A-GPS request is received, the module distributes it to the other modules as a GNSS_EVT_AGPS_NEEDED event that contains information about the type of assistance data needed. Providing the requested A-GPS data may reduce the time it takes to acquire a position fix.

The module can also store the last known location if CONFIG_GNSS_MODULE_PGPS_STORE_LOCATION is enabled. This can improve the time to fix when predicted GPS assistance data is used.

Module internals

The GNSS module is a threadless module in terms of message processing. In this sense, it differs from the other modules. It has a thread for processing GNSS events from the modem library, whereas other modules use a thread for processing messages. The thread is used to offload data processing from the GNSS callbacks coming from the modem library, as these are called from interrupt context and no time consuming tasks should be performed there.

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

Configuration options

CONFIG_GNSS_MODULE

Enables the GNSS module. The module can report data either as a structure of position, velocity, and time (PVT) information, or as an NMEA string of GGA type.

CONFIG_GNSS_MODULE_PVT

Selects the PVT format. Includes position, velocity, and time (PVT) information in the GNSS_EVT_DATA_READY events that are sent when the GNSS acquires a position fix.

CONFIG_GNSS_MODULE_NMEA

Selects the NMEA format. Includes an NMEA string of the GGA type in the GNSS_EVT_DATA_READY events that are sent when the GNSS acquires a position fix.

If P-GPS is used, the last known position from a GNSS fix can be stored and injected to the modem together with the relevant ephemeris. This may, depending on the use case and the device’s movements, reduce the time to fix. To enable this feature, use the following option:

CONFIG_GNSS_MODULE_PGPS_STORE_LOCATION

This stores and injects the last known position from a GNSS fix to the modem with the relevant ephemeris.

For more information on P-GPS, see nRF Cloud P-GPS.

Module states

The GNSS 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 GNSS configuration.

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

    • SUB_STATE_SEARCH - A GNSS search is ongoing.

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

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

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

Module events

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

Dependencies

The module uses the following nRF Connect SDK libraries:

API documentation

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

GNSS module event.

Defines

NMEA_MAX_LEN

Enums

enum gnss_module_event_type

GNSS event types submitted by GNSS module.

Values:

enumerator GNSS_EVT_DATA_READY

A valid GNSS fix has been obtained and the data is ready to be used.

    The event has associated payload of the type ``struct gnss_module_data`` in
    the event struct member ``data.gnss``.
    All struct members within `data.gnss`` contain valid data.

    The format of the location data from the GNSS fix is specified in the
    event struct member ``data.gnss.format`` and decides how you can access
    the anonymous union containing the location data.

    If the format is ``GNSS_MODULE_DATA_FORMAT_PVT``, the PVT data is available in the
    event struct member ``data.gnss.pvt``.

    If the format is ``GNSS_MODULE_DATA_FORMAT_NMEA``, the NMEA string is available in the
    event struct member ``data.gnss.nmea``.

enumerator GNSS_EVT_TIMEOUT

The GNSS search timed out without acquiring a fix.

    The event has associated payload of the type ``struct gnss_module_data`` in
    the event struct member ``data.gnss``.
    The ``data.gnss`` struct members ``search_time`` and ``data.satellites_tracked``
    contain valid data.

enumerator GNSS_EVT_ACTIVE

An active GNSS search has started.

enumerator GNSS_EVT_INACTIVE

A GNSS search has stopped, either as a result of timeout or acquired fix.

enumerator GNSS_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, which contains the module ID used shen acknowledging a shutdown request from the util module.

enumerator GNSS_EVT_AGPS_NEEDED

The modem has reported that it needs GPS assistance data. The event has associated payload of the type struct nrf_modem_gnss_agps_data_frame in the event struct member data.agps_request, which contains the types of A-GPS data that the modem needs.

enumerator GNSS_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, which contains the original error code from that triggered the sending of this event.

enum gnss_module_format

GNSS data format for associated payload of GNSS_EVT_DATA_READY event type.

Values:

enumerator GNSS_MODULE_DATA_FORMAT_INVALID
enumerator GNSS_MODULE_DATA_FORMAT_PVT
enumerator GNSS_MODULE_DATA_FORMAT_NMEA
struct gnss_module_pvt
#include <gnss_module_event.h>

Position, velocity and time (PVT) data.

Public Members

double longitude

Longitude in degrees.

double latitude

Latitude in degrees.

float altitude

Altitude above WGS-84 ellipsoid in meters.

float accuracy

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

float speed

Horizontal speed in m/s.

float heading

Heading of user movement in degrees.

struct gnss_module_data
#include <gnss_module_event.h>

GNSS module data for associated payload for events of GNSS_EVT_TIMEOUT and GNSS_EVT_DATA_READY types.

Public Members

union gnss_module_data.[anonymous] [anonymous]

Location data in the form of a PVT structure or an NMEA GGA sentence.

uint32_t search_time

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

struct gnss_module_event
#include <gnss_module_event.h>

GNSSS module event.