GNSS

GNSS receiver driver.

Positioning API for GNSS receivers (typically the GNSS block of a cellular module). Obtain a handle with open(const char*), enable the receiver with gnss_enable and read fixes with gnss_poll. gnss_epo_update loads Extended Prediction Orbit data to shorten the time to first fix.

Types

	Name
struct	gnss_data_t Structure representing GNSS data.
enum	gnss_nav_t GNSS Navigation System Enumeration.

Functions Overview

	Name
cw_driver_return_t	gnss_enable(int hdev) Enables the GNSS functionality on the specified device.
cw_driver_return_t	gnss_disable(int hdev) Disables the GNSS functionality for a specified device.
cw_driver_return_t	gnss_poll(int hdev, gnss_data_t * data) Polls the GNSS device for current data.
cw_driver_return_t	gnss_epo_update(int hdev, const char * http_host, const char * file_path, uint8_t load_days, uint8_t threshold_days) Updates the EPO (Extended Prediction Orbit) data for the GNSS device.
cw_driver_return_t	gnss_epo_enddate(int hdev) Get the end date of the GNSS EPO data.

Types Documentation

enum gnss_nav_t

Enumerator	Description
gnssNavSysNone	No GNSS navigation system is available.
gnssNavSysGPS	GPS (Global Positioning System) navigation system is available.
gnssNavSysGLONASS	GLONASS (Global Navigation Satellite System) navigation system is available.

GNSS Navigation System Enumeration.

Note: This enumeration can be used to specify the navigation system used by a GNSS receiver.

This enumeration defines the supported GNSS navigation systems for a given location.

Function Details

function gnss_enable

cw_driver_return_t gnss_enable(
    int hdev
)

Enables the GNSS functionality on the specified device.

Parameters:

• hdev The handle of the device on which to enable GNSS functionality. The handle should correspond to a valid and initialized GNSS device.

Return: 0 on success, a negative error code if the device or driver is unavailable.

This function activates the GNSS feature for the given device handle, allowing it to begin GNSS-related operations. It interacts with the underlying driver to enable GNSS capabilities.

function gnss_disable

cw_driver_return_t gnss_disable(
    int hdev
)

Disables the GNSS functionality for a specified device.

Parameters:

• hdev The handle of the device for which the GNSS functionality is to be disabled.

Note: Ensure the device handle provided is valid to avoid unexpected behavior.

This function disables the GNSS receiver associated with the specified device handle.

function gnss_poll

cw_driver_return_t gnss_poll(
    int hdev,
    gnss_data_t * data
)

Polls the GNSS device for current data.

Parameters:

• hdev The handle of the GNSS device.
• data Pointer to a gnss_data_t structure where the received data will be stored.

Returns:

• <0 the receiver does not have a fix, yet
• 0 success

Return: An integer value indicating the success or failure of the function.

This function sends a poll command to the GNSS device specified by the handle. The received data is filled into the gnss_data_t structure.

function gnss_epo_update

cw_driver_return_t gnss_epo_update(
    int hdev,
    const char * http_host,
    const char * file_path,
    uint8_t load_days,
    uint8_t threshold_days
)

Updates the EPO (Extended Prediction Orbit) data for the GNSS device.

Parameters:

• hdev The handle of the GNSS device.
• http_host The host of the HTTP server to download the EPO data from.
• file_path The file path on the HTTP server where the EPO data is located.
• load_days The number of days of EPO data to load onto the device.
• threshold_days The number of days after which the loaded EPO data is considered expired.

Return: A driver-specific error code. Negative values represent errors, while positive values represent successful execution.

Remark:

• Extended Prediction Orbit (EPO): The EPO is essentially a set of predicted satellite orbits that extend the standard data provided by the navigation satellites. These orbits are extrapolated beyond the immediate future, providing information about where the satellites are expected to be at different times. GNSS receivers use this data to improve satellite acquisition times and position fix accuracy, especially in scenarios where the device has been powered off for a while or moved long distances since it last received satellite data.
• EPO File: An EPO file is a specific file format that contains this predicted orbit data. It typically includes information such as satellite IDs, orbital parameters, and timestamps. These files are provided by GNSS service providers and are periodically updated to ensure the most accurate predictions. GNSS receivers download and store these files, updating them as necessary to maintain accurate predictions. Overall, the Extended Prediction Orbit and its associated file format play a crucial role in improving the performance of GNSS receivers by providing extended satellite orbit predictions, thereby enhancing position accuracy and acquisition times.

This function performs an EPO update by sending an HTTP request to the specified HTTP server. The EPO data is downloaded from the specified file path on the server and then loaded onto the GNSS device.

function gnss_epo_enddate

cw_driver_return_t gnss_epo_enddate(
    int hdev
)

Get the end date of the GNSS EPO data.

Parameters:

• hdev The handle to the device.

Return: The end date of the GNSS EPO data as an unsigned integer.

This function retrieves the end date of the GNSS EPO (Extended Prediction Orbit) data for the specified device.