Using GNSS Data in Your Application

Once your GNSS receiver is set up, your application must read its measurements, convert them to sl::GNSSData, and ingest them into the Fusion module with ingestGNSSData, as shown in the Global Localization overview.

This page shows how to read GNSS data from gpsd on Linux. On Windows, see Setting up GNSS / RTK on Windows.

Reading data from gpsd

Python

To access GNSS data in Python, you can use the gpsdclient library. It provides a Python interface to the gpsd daemon, giving access to latitude, longitude, altitude, speed, estimated errors, satellites in view, and more.

You can install gpsdclient with:

pip install gpsdclient

Here is an example of a simple script using gpsdclient:

from gpsdclient import GPSDClient
# get your data as json strings:
with GPSDClient(host="127.0.0.1") as client:
    for result in client.json_stream():
        print(result)
# or as python dicts (optionally convert time information to `datetime` objects)
with GPSDClient() as client:
    for result in client.dict_stream(convert_datetime=True, filter=["TPV"]):
        print("Latitude: %s" % result.get("lat", "n/a"))
        print("Longitude: %s" % result.get("lon", "n/a"))
# you can optionally filter by report class
with GPSDClient() as client:
    for result in client.dict_stream(filter=["TPV", "SKY"]):
        print(result)

The position is contained in the TPV (Time Position Velocity) reports. The SKY reports describe the satellites in view.

C++

To access GNSS data in C++, you can use the libgpsmm library.

You can install libgpsmm with:

sudo apt install libgps-dev

Here is an example of a simple program using libgpsmm:

#include <libgpsmm.h>
#include <iostream>
int main() {
    gpsmm gps_data("localhost", DEFAULT_GPSD_PORT);
    if (gps_data.stream(WATCH_ENABLE | WATCH_JSON) == nullptr) {
        std::cerr << "Failed to open GPS connection." << std::endl;
        return 1;
    }
    while (true) {
        if (gps_data.waiting(500)) {
            struct gps_data_t* new_data = gps_data.read();
            if (new_data == nullptr) {
                std::cerr << "Error while reading GPS data." << std::endl;
            } else {
                std::cout << "Latitude: " << new_data->fix.latitude << ", Longitude: " << new_data->fix.longitude << std::endl;
            }
        }
    }
    gps_data.stream(WATCH_DISABLE);
    return 0;
}

Converting to sl::GNSSData

The sl::GNSSData structure ingested by the Fusion module contains:

The covariance must reflect the actual uncertainty of each measurement. Set it from the errors estimated by the receiver: a constant value triggers the GNSS_DATA_COVARIANCE_MUST_VARY warning described in Troubleshooting.

#include <libgpsmm.h>
#include <sl/Fusion.hpp>
// Convert a gpsd report with a valid fix (mode >= MODE_2D) to sl::GNSSData.
// Skip the reports where fix.eph or fix.epv is NaN before calling it.
sl::GNSSData toGNSSData(const gps_data_t* gpsd_data) {
    sl::GNSSData gnss_data;
    // Coordinates in degrees and meters
    gnss_data.setCoordinates(gpsd_data->fix.latitude, gpsd_data->fix.longitude, gpsd_data->fix.altMSL, false);
    // Covariance from the estimated horizontal and vertical errors, in meters
    const double eph = gpsd_data->fix.eph;
    const double epv = gpsd_data->fix.epv;
    gnss_data.position_covariance = {eph * eph, 0, 0,
                                     0, eph * eph, 0,
                                     0, 0, epv * epv};
    // Timestamp of the fix (GNSS time)
    gnss_data.ts.setMicroseconds(static_cast<uint64_t>(gpsd_data->fix.time.tv_sec) * 1000000ULL +
                                 gpsd_data->fix.time.tv_nsec / 1000);
    // Fix mode
    switch (gpsd_data->fix.mode) {
        case 1: gnss_data.gnss_mode = sl::GNSS_MODE::NO_FIX; break; // MODE_NO_FIX
        case 2: gnss_data.gnss_mode = sl::GNSS_MODE::FIX_2D; break; // MODE_2D
        case 3: gnss_data.gnss_mode = sl::GNSS_MODE::FIX_3D; break; // MODE_3D
        default: gnss_data.gnss_mode = sl::GNSS_MODE::UNKNOWN; break;
    }
    // Fix status (numeric values, as the constant names changed between gpsd versions)
    switch (gpsd_data->fix.status) {
        case 2: gnss_data.gnss_status = sl::GNSS_STATUS::DGNSS; break;     // DGPS
        case 3: gnss_data.gnss_status = sl::GNSS_STATUS::RTK_FIX; break;   // RTK fixed
        case 4: gnss_data.gnss_status = sl::GNSS_STATUS::RTK_FLOAT; break; // RTK float
        default: gnss_data.gnss_status = sl::GNSS_STATUS::SINGLE; break;   // GPS, DR, ...
    }
    return gnss_data;
}

When the status field is missing, and for the other gpsd statuses such as dead reckoning, the examples use SINGLE, as recommended for the GNSS_DATA_NEED_FIX warning. The estimated errors may also be unavailable for some reports, for example right after the first fix: gpsd then omits them from the JSON reports, and sets them to NaN in the C++ structure (check them with std::isnan). Skip these reports instead of ingesting a made-up covariance.

Timestamps

The Fusion module matches GNSS data with camera images by timestamp, and camera images are timestamped with the system clock of the host. There are two ways to timestamp the GNSS data:

• GNSS time, as in the examples above. This is the most accurate option, as it gives the instant of the measurement, but it requires the system clock to be synchronized with UTC, for example with NTP, or better, with PPS.
• Reception time, with sl::getCurrentTimeStamp() when the data is read. It works with any system clock, but includes the latency of the receiver and of the serial link, typically a few tens of milliseconds.

If the system clock is not synchronized and the GNSS time is used, the Fusion module rejects the data with an INVALID_TIMESTAMP error. See Data Synchronization for details.

Complete samples

The Global Localization samples on GitHub read GNSS data from gpsd, convert it to sl::GNSSData and ingest it into the Fusion module. They also show how to record GNSS data with an SVO file and replay it. See the samples page for a description of each sample.

Using GNSS with ROS 2

The ZED ROS 2 Wrapper reads the GNSS data from a sensor_msgs/msg/NavSatFix topic and performs the fusion for you. See Geo Tracking for the compatible drivers and the configuration of the wrapper.