This is the documentation for the latest (main) development branch of Zephyr. If you are looking for the documentation of previous releases, use the drop-down menu on the left and select the desired version.

GNSS (Global Navigation Satellite System)

Overview

GNSS is a general term which covers satellite systems used for navigation, like GPS (Global Positioning System). GNSS services are usually accessed through GNSS modems which receive and process GNSS signals to determine their position, or more specifically, their antennas position. They usually additionally provide a precise time synchronization mechanism, commonly named PPS (Pulse-Per-Second).

Subsystem support

The GNSS subsystem is based on the Modem modules. The GNSS subsystem covers everything from sending and receiving commands to and from the modem, to parsing, creating and processing NMEA0183 messages.

Adding support for additional NMEA0183 based GNSS modems requires little more than implementing power management and configuration for the specific GNSS modem.

Adding support for GNSS modems which use other protocols and/or buses than the usual NMEA0183 over UART is possible, but will require a bit more work from the driver developer.

Configuration Options

Related configuration options:

GNSS API Reference

Related code samples

GNSS

Connect to a GNSS device to obtain time, navigation data, and satellite information.

group gnss_interface

GNSS Interface.

Since

3.6

Version

0.1.0

Defines

GNSS_DATA_CALLBACK_DEFINE(_dev, _callback)

Register a callback structure for GNSS data published.

Parameters:

  • _dev – Device pointer

  • _callback – The callback function

GNSS_SATELLITES_CALLBACK_DEFINE(_dev, _callback)

Register a callback structure for GNSS satellites published.

Parameters:

  • _dev – Device pointer

  • _callback – The callback function

Typedefs

typedef int (*gnss_set_fix_rate_t)(const struct device *dev, uint32_t fix_interval_ms)

API for setting fix rate.

typedef int (*gnss_get_fix_rate_t)(const struct device *dev, uint32_t *fix_interval_ms)

API for getting fix rate.

typedef int (*gnss_set_periodic_config_t)(const struct device *dev, const struct gnss_periodic_config *periodic_config)

API for setting periodic tracking configuration.

typedef int (*gnss_get_periodic_config_t)(const struct device *dev, struct gnss_periodic_config *periodic_config)

API for setting periodic tracking configuration.

typedef int (*gnss_set_navigation_mode_t)(const struct device *dev, enum gnss_navigation_mode mode)

API for setting navigation mode.

typedef int (*gnss_get_navigation_mode_t)(const struct device *dev, enum gnss_navigation_mode *mode)

API for getting navigation mode.

typedef uint32_t gnss_systems_t

Type storing bitmask of GNSS systems.

typedef int (*gnss_set_enabled_systems_t)(const struct device *dev, gnss_systems_t systems)

API for enabling systems.

typedef int (*gnss_get_enabled_systems_t)(const struct device *dev, gnss_systems_t *systems)

API for getting enabled systems.

typedef int (*gnss_get_supported_systems_t)(const struct device *dev, gnss_systems_t *systems)

API for getting enabled systems.

typedef void (*gnss_data_callback_t)(const struct device *dev, const struct gnss_data *data)

Template for GNSS data callback.

typedef void (*gnss_satellites_callback_t)(const struct device *dev, const struct gnss_satellite *satellites, uint16_t size)

Template for GNSS satellites callback.

Enums

enum gnss_pps_mode

GNSS PPS modes.

Values:

enumerator GNSS_PPS_MODE_DISABLED = 0

PPS output disabled.

enumerator GNSS_PPS_MODE_ENABLED = 1

PPS output always enabled.

enumerator GNSS_PPS_MODE_ENABLED_AFTER_LOCK = 2

PPS output enabled from first lock.

enumerator GNSS_PPS_MODE_ENABLED_WHILE_LOCKED = 3

PPS output enabled while locked.

enum gnss_navigation_mode

GNSS navigation modes.

Values:

enumerator GNSS_NAVIGATION_MODE_ZERO_DYNAMICS = 0

Dynamics have no impact on tracking.

enumerator GNSS_NAVIGATION_MODE_LOW_DYNAMICS = 1

Low dynamics have higher impact on tracking.

enumerator GNSS_NAVIGATION_MODE_BALANCED_DYNAMICS = 2

Low and high dynamics have equal impact on tracking.

enumerator GNSS_NAVIGATION_MODE_HIGH_DYNAMICS = 3

High dynamics have higher impact on tracking.

enum gnss_system

Systems contained in gnss_systems_t.

Values:

enumerator GNSS_SYSTEM_GPS = BIT(0)

Global Positioning System (GPS)

enumerator GNSS_SYSTEM_GLONASS = BIT(1)

GLObal NAvigation Satellite System (GLONASS)

enumerator GNSS_SYSTEM_GALILEO = BIT(2)

Galileo.

enumerator GNSS_SYSTEM_BEIDOU = BIT(3)

BeiDou Navigation Satellite System.

enumerator GNSS_SYSTEM_QZSS = BIT(4)

Quasi-Zenith Satellite System (QZSS)

enumerator GNSS_SYSTEM_IRNSS = BIT(5)

Indian Regional Navigation Satellite System (IRNSS)

enumerator GNSS_SYSTEM_SBAS = BIT(6)

Satellite-Based Augmentation System (SBAS)

enumerator GNSS_SYSTEM_IMES = BIT(7)

Indoor Messaging System (IMES)

enum gnss_fix_status

GNSS fix status.

Values:

enumerator GNSS_FIX_STATUS_NO_FIX = 0

No GNSS fix aqcuired.

enumerator GNSS_FIX_STATUS_GNSS_FIX = 1

GNSS fix aqcuired.

enumerator GNSS_FIX_STATUS_DGNSS_FIX = 2

Differential GNSS fix acquired.

enumerator GNSS_FIX_STATUS_ESTIMATED_FIX = 3

Estimated fix acquired.

enum gnss_fix_quality

GNSS fix quality.

Values:

enumerator GNSS_FIX_QUALITY_INVALID = 0

Invalid fix.

enumerator GNSS_FIX_QUALITY_GNSS_SPS = 1

Standard positioning service.

enumerator GNSS_FIX_QUALITY_DGNSS = 2

Differential GNSS.

enumerator GNSS_FIX_QUALITY_GNSS_PPS = 3

Precise positioning service.

enumerator GNSS_FIX_QUALITY_RTK = 4

Real-time kinematic.

enumerator GNSS_FIX_QUALITY_FLOAT_RTK = 5

Floating real-time kinematic.

enumerator GNSS_FIX_QUALITY_ESTIMATED = 6

Estimated fix.

Functions

int gnss_set_fix_rate(const struct device *dev, uint32_t fix_interval_ms)

Set the GNSS fix rate.

Parameters:

  • dev – Device instance

  • fix_interval_ms – Fix interval to set in milliseconds

Returns:

0 if successful

Returns:

-errno negative errno code on failure

int gnss_get_fix_rate(const struct device *dev, uint32_t *fix_interval_ms)

Get the GNSS fix rate.

Parameters:

  • dev – Device instance

  • fix_interval_ms – Destination for fix interval in milliseconds

Returns:

0 if successful

Returns:

-errno negative errno code on failure

int gnss_set_periodic_config(const struct device *dev, const struct gnss_periodic_config *config)

Set the GNSS periodic tracking configuration.

Parameters:

  • dev – Device instance

  • config – Periodic tracking configuration to set

Returns:

0 if successful

Returns:

-errno negative errno code on failure

int gnss_get_periodic_config(const struct device *dev, struct gnss_periodic_config *config)

Get the GNSS periodic tracking configuration.

Parameters:

  • dev – Device instance

  • config – Destination for periodic tracking configuration

Returns:

0 if successful

Returns:

-errno negative errno code on failure

int gnss_set_navigation_mode(const struct device *dev, enum gnss_navigation_mode mode)

Set the GNSS navigation mode.

Parameters:

  • dev – Device instance

  • mode – Navigation mode to set

Returns:

0 if successful

Returns:

-errno negative errno code on failure

int gnss_get_navigation_mode(const struct device *dev, enum gnss_navigation_mode *mode)

Get the GNSS navigation mode.

Parameters:

  • dev – Device instance

  • mode – Destination for navigation mode

Returns:

0 if successful

Returns:

-errno negative errno code on failure

int gnss_set_enabled_systems(const struct device *dev, gnss_systems_t systems)

Set enabled GNSS systems.

Parameters:

  • dev – Device instance

  • systems – Systems to enable

Returns:

0 if successful

Returns:

-errno negative errno code on failure

int gnss_get_enabled_systems(const struct device *dev, gnss_systems_t *systems)

Get enabled GNSS systems.

Parameters:

  • dev – Device instance

  • systems – Destination for enabled systems

Returns:

0 if successful

Returns:

-errno negative errno code on failure

int gnss_get_supported_systems(const struct device *dev, gnss_systems_t *systems)

Get supported GNSS systems.

Parameters:

  • dev – Device instance

  • systems – Destination for supported systems

Returns:

0 if successful

Returns:

-errno negative errno code on failure

struct gnss_periodic_config
#include <gnss.h>

GNSS periodic tracking configuration.

Note

Setting either active_time or inactive_time to 0 will disable periodic function.

Public Members

uint32_t active_time_ms

The time the GNSS will spend in the active state in ms.

uint32_t inactive_time_ms

The time the GNSS will spend in the inactive state in ms.

struct gnss_info
#include <gnss.h>

GNSS info data structure.

Public Members

uint16_t satellites_cnt

Number of satellites being tracked.

uint32_t hdop

Horizontal dilution of precision in 1/1000.

enum gnss_fix_status fix_status

The fix status.

enum gnss_fix_quality fix_quality

The fix quality.

struct gnss_time
#include <gnss.h>

GNSS time data structure.

Public Members

uint8_t hour

Hour [0, 23].

uint8_t minute

Minute [0, 59].

uint16_t millisecond

Millisecond [0, 59999].

uint8_t month_day

Day of month [1, 31].

uint8_t month

Month [1, 12].

uint8_t century_year

Year [0, 99].

struct gnss_driver_api
#include <gnss.h>

GNSS API structure.

struct gnss_data
#include <gnss.h>

GNSS data structure.

Public Members

struct navigation_data nav_data

Navigation data acquired.

struct gnss_info info

GNSS info when navigation data was acquired.

struct gnss_time utc

UTC time when data was acquired.

struct gnss_data_callback
#include <gnss.h>

GNSS callback structure.

Public Members

const struct device *dev

Filter callback to GNSS data from this device if not NULL.

gnss_data_callback_t callback

Callback called when GNSS data is published.

struct gnss_satellite
#include <gnss.h>

GNSS satellite structure.

Public Members

uint8_t prn

Pseudo-random noise sequence.

uint8_t snr

Signal-to-noise ratio in dB.

uint8_t elevation

Elevation in degrees [0, 90].

uint16_t azimuth

Azimuth relative to True North in degrees [0, 359].

enum gnss_system system

System of satellite.

uint8_t is_tracked

True if satellite is being tracked.

struct gnss_satellites_callback
#include <gnss.h>

GNSS callback structure.

Public Members

const struct device *dev

Filter callback to GNSS data from this device if not NULL.

gnss_satellites_callback_t callback

Callback called when GNSS satellites is published.