nmealib 0.6.1

Python bindings for nmealib (NMEA 0183 and NMEA 2000 parsing)

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
• 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 Usage

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

Use the library in your C++ project

#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.

Use the library in PlatformIO

Add the dependency in your platformio.ini:

lib_deps = fliuzzi02/nmealib

The published PlatformIO package is built with exceptions disabled:

• -fno-exceptions
• -DNMEALIB_NO_EXCEPTIONS

In that configuration, parse failures do not throw. Factory methods return nullptr.

#include <nmealib.h>

auto message = nmealib::nmea0183::Nmea0183Factory::create(rawSentence);
if (!message) {
    return;
}

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

---

Build from Source

Requirements

• CMake 3.20+
• C++20 compiler:
  • GCC 10+
  • Clang 12+
  • MSVC 2019+
• Build system: Ninja, GNU Make, or Visual Studio
• Optional (development): GoogleTest, clang-tidy, cppcheck

Build

git clone https://github.com/fliuzzi02/nmealib.git
cd nmealib

cmake --preset gcc-release
cmake --build --preset build-release
cmake --install out/build/gcc-release --prefix out/install/gcc-release

Artifacts are installed under:

out/install/gcc-release

---

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

NMEA 0183

Message	Notes
APB	Autopilot Sentence "B"
DBT	Depth Below Transducer
DPT	Depth of Water
GGA	Global Positioning System Fix Data
GLL	Geographic Position
GSA	GPS DOP and Active Satellites
GSV	GPS Satellites in View
HDG	Heading, Deviation and Variation
HDM	Heading, Magnetic
MTW	Mean Temperature of Water
MWV	Wind Speed and Angle
RMA	Recommended Minimum Specific Loran-C Data
RMB	Recommended Minimum Navigation Information
RMC	Recommended Minimum Navigation Data
VHW	Water Speed and Heading
VLW	Distance Traveled Through Water
VTG	Course Over Ground and Ground Speed
VWR	Relative Wind Speed and Angle
XDR	Transducer Measurements
XTE	Cross-Track Error, Measured
ZDA	Time and Date

NMEA 2000

Message / Transport	Notes
Single-frame messages	Standard one-frame CAN payloads
Fast-packet transport	Multi-frame transport handling
PGN 127250	Vessel Heading
PGN 128259	Speed, Water Referenced
PGN 130306	Wind Data

Messages/PGNs not listed are currently considered not implemented.

---

Compatibility

Platform	Compiler	Standard
Linux	GCC 10+, Clang 12+	C++20
Windows	MSVC 2019+	C++20
macOS	Clang 12+	C++20

PlatformIO support is also available through library.json with broad platform/framework declaration (*). Target toolchains must support C++20.

---

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.