nmealib

Modern C++20 library for parsing NMEA 0183 sentences and NMEA 2000 CAN messages, with typed models, validation, and extensible message handling.

Why nmealib

• Unified parsing for NMEA 0183 and NMEA 2000
• Python and C++ libraries with consistent APIs
• Typed message classes for safer integrations
• Built-in validation (including NMEA 0183 checksum handling)
• Extensible architecture for new sentence/PGN support
• CLI tool for quick parsing and debugging
• Unit-tested codebase

Quick Start

CLI

Download the latest release from GitHub Releases, then parse a sentence:

./nmealib-cli '$GPGGA,123519,4807.038,N,01131.000,E,1,08,0.9,545.4,M,46.9,M,,*47'

Parse from a file/pipe:

cat nmea_sentences.txt | ./nmealib-cli

C++ Library

Add the library to your CMake project (see Installation Guide), then include and use it:

#include <nmealib.h>

int main() {
    std::string sentence = "$GPGGA,123519,4807.038,N,01131.000,E,1,08,0.9,545.4,M,46.9,M,,*47";
    try {
        auto msg = nmealib::NMEA0183::GGA::parse(sentence);
        std::cout << "Parsed GGA message: " << msg.toString() << std::endl;
        std::cout << "Latitude: " << msg.getLatitude() << std::endl;
        // Access other fields as needed
    } catch (const nmealib::ParseException& e) {
        std::cerr << "Failed to parse sentence: " << e.what() << std::endl;
    }
    return 0;
}

See using-nmealib for a full example project demonstrating library usage.

Python Library (PyPI)

Install from PyPI:

python -m pip install nmealib

Quick usage example:

import nmealib

raw_0183 = "$GPRMC,123519,A,4807.038,N,01131.000,E,022.4,084.4,230394,003.1,W,A,V*6A\r\n"
raw_2000 = "09F11260:342C71FF7FFF7FFD"

try:
    msg_0183 = nmealib.nmea0183.Nmea0183Factory.create(raw_0183)
    print(type(msg_0183).__name__)  # RMC
    print(msg_0183.get_latitude(), msg_0183.get_longitude())

    msg_2000 = nmealib.nmea2000.Nmea2000Factory.create(raw_2000)
    print(type(msg_2000).__name__)  # PGN127250
except nmealib.NmeaException as exc:
    print(f"Parse error: {exc}")

Use in PlatformIO

The library is published on the PlatformIO registry:

https://registry.platformio.org/libraries/fliuzzi02/nmealib

Add the dependency in your platformio.ini:

lib_deps =
    fliuzzi02/nmealib

Or install it with the PlatformIO CLI:

pio pkg install --library "fliuzzi02/nmealib"

An embedded reference example is available in examples/platformio-esp32.

Documentation

• Installation Guide
• API Reference
• Examples
• Contributing

Companion usage repository: using-nmealib

Project Structure

nmealib/
├── .github/                  # CI workflow files
├── app/                      # CLI entrypoint
├── docs/                     # Documentation
├── examples/                 # Usage examples (including PlatformIO)
├── include/
│   ├── nmealib.h             # Main umbrella header
│   └── nmealib/
│       ├── nmeaException.h   # Custom exception class
│       ├── message.h         # Base Message class and utilities
│       ├── nmea0183.h        # Base NMEA 0183 class and utilities
│       ├── nmea2000.h        # Base NMEA 2000 class and utilities
│       ├── detail/           # Internal shared parsing/error helpers
│       ├── nmea0183/         # NMEA 0183 message type headers
│       └── nmea2000/         # NMEA 2000 message type headers
├── scripts/                  # CI/dev utility scripts
├── src/                      # Library implementation and parsing logic
├── tests/                    # Unit tests
├── CMakeLists.txt            # Root CMake project configuration
├── CMakePresets.json         # Preset build/test configurations
├── README.md                 # This file
└── library.json              # PlatformIO package manifest

Supported Protocols

All messages/PGNs listed in the Protocol Support are currently implemented and supported.

Messages/PGNs not listed are currently considered not implemented.

License

Licensed under MIT. See LICENSE.

Support

• Open an issue in this repository for bugs/feature requests.
• For usage questions, include sample input data and expected output.