GPS

The GPS interface exposes an API to access GPS devices. The API offers functionality to initialize and configure a device, to start and stop GPS search, and to request and provide GPS assistance data (A-GPS).

API documentation

Header file: include/drivers/gps.h

group gpsapi

Defines

GPS_NMEA_SENTENCE_MAX_LENGTH

GPS_PVT_MAX_SV_COUNT

GPS_SOCKET_NOT_PROVIDED

Typedefs

typedef void (*gps_event_handler_t)(const struct device *dev, struct gps_event *evt)

Callback API on GPS event.

Parameters

• dev – Pointer to GPS device

• evt – Pointer to event data

typedef int (*gps_start_t)(const struct device *dev, struct gps_config *cfg)

Callback API for starting GPS operation.

See gps_start() for argument description

typedef int (*gps_stop_t)(const struct device *dev)

Callback API for stopping GPS operation.

See gps_stop() for argument description

typedef int (*gps_agps_write_t)(const struct device *dev, enum gps_agps_type type, void *data, size_t data_len)

Callback API for writing to A-GPS data to GPS module.

See gps_write() for argument description

typedef int (*gps_init_t)(const struct device *dev, gps_event_handler_t handler)

Callback API for initializing GPS device.

See gps_init() for argument description

typedef int (*gps_deinit_t)(const struct device *dev)

Callback API for deinitializing GPS device.

See gps_deinit() for argument description

Enums

enum gps_nav_mode

Values:

enumerator GPS_NAV_MODE_SINGLE_FIX

Search will be stopped after first fix.

enumerator GPS_NAV_MODE_CONTINUOUS

Search continues until explicitly stopped.

enumerator GPS_NAV_MODE_PERIODIC

Periodically start search, stops on fix.

enum gps_use_case

Values:

enumerator GPS_USE_CASE_SINGLE_COLD_START

Target best single cold start performance.

enumerator GPS_USE_CASE_MULTIPLE_HOT_START

Target best multiple hot starts performance.

enum gps_accuracy

Values:

enumerator GPS_ACCURACY_NORMAL

Use normal accuracy thresholds for producing GPS fix.

enumerator GPS_ACCURACY_LOW

Allow low accuracy fixes using 3 satellites. Note that one of the two conditions must be met:

• Altitude, accurate within 10s of meters provided using gps_agps_write(). Valid for 24 hours.

• One fix using 5 or more satellites in the previous 24 hours, without the device rebooting in the meantime.

See the GNSS documentation for more details.

enum gps_power_mode

Values:

enumerator GPS_POWER_MODE_DISABLED

Best GPS performance.

enumerator GPS_POWER_MODE_PERFORMANCE

Lower power, without significant GPS performance degradation.

enumerator GPS_POWER_MODE_SAVE

Lowest power option, with acceptable GPS performance.

enum gps_agps_type

GPS assistance data types.

Values:

enumerator GPS_AGPS_UTC_PARAMETERS

UTC parameters.

enumerator GPS_AGPS_EPHEMERIDES

Ephemerides.

enumerator GPS_AGPS_ALMANAC

Almanac.

enumerator GPS_AGPS_KLOBUCHAR_CORRECTION

Ionospheric correction parameters, Klobuchar model.

enumerator GPS_AGPS_NEQUICK_CORRECTION

Ionospheric correction parameters, NeQuick model.

enumerator GPS_AGPS_GPS_TOWS

Time of week.

enumerator GPS_AGPS_GPS_SYSTEM_CLOCK_AND_TOWS

GPS system clock and time of week

enumerator GPS_AGPS_LOCATION

Approximate location.

enumerator GPS_AGPS_INTEGRITY

Satellite integrity data.

enum gps_event_type

GPS event types.

Values:

enumerator GPS_EVT_SEARCH_STARTED

enumerator GPS_EVT_SEARCH_STOPPED

enumerator GPS_EVT_SEARCH_TIMEOUT

enumerator GPS_EVT_PVT

enumerator GPS_EVT_PVT_FIX

enumerator GPS_EVT_NMEA

enumerator GPS_EVT_NMEA_FIX

enumerator GPS_EVT_OPERATION_BLOCKED

enumerator GPS_EVT_OPERATION_UNBLOCKED

enumerator GPS_EVT_AGPS_DATA_NEEDED

enumerator GPS_EVT_ERROR

enum gps_error

GPS errors.

Values:

enumerator GPS_ERROR_GPS_DISABLED

Functions

static inline int gps_start(const struct device *dev, struct gps_config *cfg)

Function to start GPS operation.

If gps is already running a call to this function will restart the gps.

Parameters

• dev – Pointer to GPS device

• cfg – Pointer to GPS configuration.

static inline int gps_stop(const struct device *dev)

Function to stop GPS operation.

Parameters

• dev – Pointer to GPS device

static inline int gps_agps_write(const struct device *dev, enum gps_agps_type type, void *data, size_t data_len)

Function to write A-GPS data to GPS module.

Parameters

• dev – Pointer to GPS device

• type – A-GPS data type

• data – Pointer to A-GPS data

• data_len – Length of data

Returns

Zero on success or (negative) error code otherwise.

static inline int gps_init(const struct device *dev, gps_event_handler_t handler)

Initializes GPS device.

Parameters

• dev – Pointer to GPS device.

• handler – Pointer to GPS event handler.

Returns

Zero on success or (negative) error code otherwise.

static inline int gps_deinit(const struct device *dev)

Deinitializes GPS device.

Parameters

• dev – Pointer to GPS device.

Returns

Zero on success or (negative) error code otherwise.

int gps_agps_request_send(struct gps_agps_request request, int socket)

Function to send a request for A-GPS data to the configured A-GPS data source. See the A-GPS Library Kconfig documentation for alternatives.

Parameters

• request – Assistance data to request from A-GPS service.

• socket – GPS socket to which assistance data will be written when it’s received from the selected A-GPS service. If zero the GPS driver will be used to write the data instead of directly to the provided socket.

Returns

Zero on success or (negative) error code otherwise.

int gps_process_agps_data(const uint8_t *buf, size_t len)

Processes A-GPS data.

Parameters

• buf – Pointer to A-GPS data.

• len – Buffer size of data to be processed.

Returns

Zero on success or (negative) error code otherwise.

int gps_get_last_cell_location(double *const lat, double *const lon)

Gets most recent location from cell-based location request.

Parameters

• lat – Pointer where last cell-based latitude is to be copied.

• lon – Pointer where last cell-based longitude is to be copied.

Returns

0 if successful, otherwise a (negative) error code.

struct gps_nmea

#include <gps.h>

struct gps_datetime

#include <gps.h>

struct gps_sv

#include <gps.h>

Public Members

uint16_t sv

SV number 1…32 for GPS.

uint16_t cn0

0.1 dB/Hz.

int16_t elevation

SV elevation angle in degrees.

int16_t azimuth

SV azimuth angle in degrees.

uint8_t signal

Signal type. 0: invalid, 1: GPS L1C/A.

uint8_t in_fix

Satellite used in fix calculation.

uint8_t unhealthy

Satellite is marked as unhealthy.

struct gps_pvt

#include <gps.h>

struct gps_config

#include <gps.h>

GPS search configuration.

Public Members

enum gps_nav_mode nav_mode

GPS navigation mode, gps_nav_mode.

enum gps_power_mode power_mode

Power mode, gps_power_mode.

enum gps_use_case use_case

GPS use case, gps_use_case.

enum gps_accuracy accuracy

Accuracy threshold for producing fix, gps_accuracy.

uint32_t interval

Interval, in seconds, at which to start GPS search. The value is ignored outside periodic mode. Minimum accepted value is 10 seconds.

int32_t timeout

Time to search for fix before giving up. If used in periodic mode, the timeout repeats every interval. K_FOREVER or 0 indicate that the GPS will search until it gets a valid PVT estimate, except in continuous mode, where it will stay on until explicitly stopped also in case of valid PVT.

bool delete_agps_data

Delete stored assistance data before starting GPS search.

bool priority

Give GPS priority in competition with other radio resource users. This may affect the operation of other protocols, such as LTE in the case of nRF9160.

struct gps_agps_request

#include <gps.h>

Public Members

uint32_t sv_mask_ephe

Bit mask indicating the satellite PRNs for which the assistance GPS ephemeris data is needed.

uint32_t sv_mask_alm

Bit mask indicating the satellite PRNs for which the assistance GPS almanac data is needed.

uint8_t utc

GPS UTC parameters.

uint8_t klobuchar

Klobuchar parameters.

uint8_t nequick

NeQuick parameters.

uint8_t system_time_tow

GPS system time and SV TOWs.

uint8_t position

Position assistance parameters.

uint8_t integrity

Integrity assistance parameters.

struct gps_event

#include <gps.h>

struct gps_driver_api

#include <gps.h>

GPS driver API.

This is the API all GPS drivers must expose.