GPS / GNSS

The Gps component provides a driver for UART-attached GNSS receivers which output standard NMEA-0183 sentences (e.g. the ATGM336H on the M5Stack Cardputer LoRa+GPS Cap, or the u-blox MIA-M10Q on the LilyGo T-Deck Plus). It reads and parses the NMEA stream in a background task and provides the latest fix (position, altitude, speed, course, satellites, UTC time) thread-safely or via callback.

The NmeaParser class provides the underlying platform-independent NMEA parsing and can be used on its own.

API Reference

Header File

Classes

class Gps : public espp::BaseComponent

Driver for UART-attached GNSS receivers which output NMEA-0183 sentences, such as the ATGM336H (M5Stack Cardputer-Adv LoRa+GPS Cap) or the u-blox MIA-M10Q (LilyGo T-Deck Plus).

The driver installs the UART driver, then runs a task which reads the NMEA stream, parses it (see espp::NmeaParser), and maintains the latest fix, which can be retrieved thread-safely with fix() or delivered via the fix callback.

Example

  espp::Gps gps({.uart_port = UART_NUM_1,
                 .tx_io_num = (gpio_num_t)CONFIG_EXAMPLE_GPS_TX_GPIO,
                 .rx_io_num = (gpio_num_t)CONFIG_EXAMPLE_GPS_RX_GPIO,
                 .baud_rate = CONFIG_EXAMPLE_GPS_BAUD_RATE,
                 .on_fix =
                     [&](const espp::GpsFix &fix) {
                       if (fix.valid) {
                         logger.info("Fix: {:.6f}, {:.6f} alt {:.1f} m, {} sats, hdop {:.1f}, "
                                     "{:02}:{:02}:{:04.1f} UTC",
                                     fix.latitude, fix.longitude, fix.altitude, fix.num_satellites,
                                     fix.hdop, fix.hour, fix.minute, fix.second);
                       } else {
                         logger.info("Waiting for fix ({} sats in use)...", fix.num_satellites);
                       }
                     },
                 .log_level = espp::Logger::Verbosity::INFO});

Public Types

typedef std::function<void(const GpsFix &fix)> fix_callback_fn

Callback invoked whenever an RMC sentence has been parsed (i.e. once per receiver update cycle), with the current fix.

typedef std::function<void(std::string_view sentence)> sentence_callback_fn

Callback invoked for every valid NMEA sentence received (before parsing), e.g. for logging or for parsing additional sentence types.

Public Functions

explicit Gps(const Config &config)

Constructor

Parameters:

config – The configuration for the driver

~Gps()

Destructor - stops the task and deletes the UART driver.

bool start(std::error_code &ec)

Install the UART driver and start the reader task.

Parameters:

ec – The error code to set if there is an error

Returns:

True if started successfully

bool stop()

Stop the reader task and delete the UART driver.

Returns:

True if stopped successfully

inline bool is_running() const

Whether the driver has been started

Returns:

True if the driver is running

GpsFix fix() const

Get a copy of the latest fix data.

Returns:

The latest fix

bool has_fix() const

Whether the receiver currently reports a valid fix

Returns:

True if the latest RMC sentence reported a valid fix

bool write(std::string_view data, std::error_code &ec)

Write raw data to the receiver (e.g. NMEA/PCAS/UBX configuration commands). Requires tx_io_num to be set.

Parameters:

  • data – The data to write

  • ec – The error code to set if there is an error

Returns:

True if the data was written

inline const std::string &get_name() const

Get the name of the component

Note

This is the tag of the logger

Returns:

A const reference to the name of the component

inline void set_log_tag(const std::string_view &tag)

Set the tag for the logger

Parameters:

tag – The tag to use for the logger

inline espp::Logger::Verbosity get_log_level() const

Get the log level for the logger

See also

Logger::Verbosity

See also

Logger::set_verbosity

Returns:

The verbosity level of the logger

inline void set_log_level(espp::Logger::Verbosity level)

Set the log level for the logger

See also

Logger::Verbosity

See also

Logger::set_verbosity

Parameters:

level – The verbosity level to use for the logger

inline void set_log_verbosity(espp::Logger::Verbosity level)

Set the log verbosity for the logger

See also

set_log_level

See also

Logger::Verbosity

See also

Logger::set_verbosity

Note

This is a convenience method that calls set_log_level

Parameters:

level – The verbosity level to use for the logger

inline espp::Logger::Verbosity get_log_verbosity() const

Get the log verbosity for the logger

See also

get_log_level

See also

Logger::Verbosity

See also

Logger::get_verbosity

Note

This is a convenience method that calls get_log_level

Returns:

The verbosity level of the logger

inline void set_log_rate_limit(std::chrono::duration<float> rate_limit)

Set the rate limit for the logger

See also

Logger::set_rate_limit

Note

Only calls to the logger that have _rate_limit suffix will be rate limited

Parameters:

rate_limit – The rate limit to use for the logger

struct Config

Configuration for the Gps driver.

Public Members

uart_port_t uart_port = UART_NUM_1

The UART port to use.

gpio_num_t tx_io_num = GPIO_NUM_NC

GPIO connected to the receiver’s RX pin (for sending configuration commands); may be NC

gpio_num_t rx_io_num = GPIO_NUM_NC

GPIO connected to the receiver’s TX pin.

uint32_t baud_rate = 9600

UART baud rate (9600 for most receivers; the M5Stack LoRa+GPS Cap ships configured for 115200)

size_t rx_buffer_size = 2048

UART RX ring buffer size.

fix_callback_fn on_fix = nullptr

Optional callback invoked on each fix update.

sentence_callback_fn on_sentence = nullptr

Optional callback invoked per NMEA sentence.

bool auto_start = true

Whether to install the driver and start the read task on construction

espp::Task::BaseConfig task_config  = {.name = "gps",.stack_size_bytes = 6 * 1024,}

Configuration for the reader task.

Logger::Verbosity log_level = {Logger::Verbosity::WARN}

Log verbosity for the driver.

Header File

Classes

class NmeaParser

Incremental parser for NMEA-0183 sentences from a GNSS receiver.

Feed it complete sentences (with or without the trailing CR/LF) via parse(); it validates the checksum and updates the fix state from the sentences it understands (xxRMC, xxGGA - any talker id: GP, GN, BD, …). This class performs no I/O and is usable on any platform; see espp::Gps for a UART-attached wrapper.

Public Functions

bool parse(std::string_view sentence)

Parse a single NMEA sentence and update the fix state.

Parameters:

sentence – The sentence, from ‘$’ through the checksum (trailing CR/LF permitted)

Returns:

True if the sentence was valid (good checksum) and recognized

bool parse_unchecked(std::string_view sentence)

Parse a single NMEA sentence whose checksum has ALREADY been validated, updating the fix state. This skips the checksum check, so callers on a hot path that have already gated on checksum_valid() can avoid computing the checksum a second time. Use parse() instead if you want the checksum validated for you.

Parameters:

sentence – The sentence, from ‘$’ through the checksum (trailing CR/LF permitted)

Returns:

True if the sentence was recognized (RMC/GGA) and parsed

inline const GpsFix &fix() const

Get the current fix state, assembled from all sentences parsed so far.

Returns:

The current fix

Public Static Functions

static bool checksum_valid(std::string_view sentence)

Verify the checksum of an NMEA sentence.

Parameters:

sentence – The sentence, from ‘$’ through the checksum

Returns:

True if the sentence has a valid checksum

Header File