pynmeagps

Common errors

• NMEAParseError: Unknown msgID GNACN, msgmode GET

  cause Attempting to parse an NMEA message with an unknown or unsupported message ID while `VALMSGID` validation is active.
  fix Either disable `VALMSGID` validation (e.g., `validate=VALCKSUM`) to parse it to a nominal structure, or provide a `userdefined` payload definition dictionary if it's a proprietary message.

• AttributeError: 'NMEAReader' object has no attribute 'iterate'

  cause Using the `iterate()` method on an `NMEAReader` instance, which was removed.
  fix Replace calls to `NMEAReader.iterate()` with direct iteration over the `NMEAReader` object itself (e.g., `for raw, parsed in nmr: ...`).

• Incorrect latitude values (e.g., negative) in parsed GLL sentences from Unicore UM9* firmware.

  cause A known firmware error in certain Unicore UM9* devices generates malformed NMEA GLL sentences with incorrect negative latitude values.
  fix Version 1.1.2 includes a workaround for this specific Unicore firmware error. Update to `pynmeagps` version 1.1.2 or later.

Warnings

• breaking The `NMEAReader.iterate()` method was removed in Release 1.0.26.
  Fix: Use the standard Python iterator pattern directly on the `NMEAReader` object. E.g., `for raw, parsed in NMEAReader(stream): ...`
• deprecated The command-line utility `nmeadump` has been removed and replaced by `gnssdump`.
  Fix: Install the `pygnssutils` package (`pip install pygnssutils`) and use its `gnssdump` utility.
• gotcha Python 3.8 support was officially dropped as of Release 1.0.43.
  Fix: Ensure your project uses Python 3.10 or later (currently requires Python >=3.10).
• gotcha Parsing unknown or proprietary NMEA message types might raise `NMEAParseError` if strict validation (`VALMSGID`) is enabled.
  Fix: From release 1.0.41 onwards, unknown messages can be parsed to a nominal structure by *not* setting the `VALMSGID` flag. For user-defined proprietary messages, pass a `userdefined` dictionary to `NMEAReader` or `NMEAReader.parse()`.

Install

• pip install pynmeagps Pip
• conda install -c conda-forge pynmeagps Conda

Imports

• NMEAReader

  from pynmeagps import NMEAReader

  Used for reading and parsing NMEA messages from a stream or static strings.
• NMEAMessage

  from pynmeagps import NMEAMessage

  Represents a parsed NMEA message object and can be used for generating messages.
• NMEA_TALKERS

  from pynmeagps.nmeatypes_core import NMEA_TALKERS

  Dictionary of recognised NMEA talker IDs. Also NMEA_MSGIDS, NMEA_MSGIDS_PROP for message IDs.
• VALCKSUM

  from pynmeagps import VALCKSUM, VALMSGID, ERR_LOG

  Constants for validation flags and error handling modes.

Quickstart

This quickstart demonstrates how to parse an NMEA message from a string using `NMEAReader.parse()` and how to construct a new NMEA message using the `NMEAMessage` class. It includes basic error handling and illustrates accessing parsed attributes and generating checksummed NMEA output. Note that NMEA messages should generally be byte strings (e.g., `b'$GPGGA...'`).

from pynmeagps import NMEAReader, NMEAMessage, VALCKSUM, VALMSGID

# Example 1: Parsing an NMEA message string
nmea_string = b'$GPGGA,123519,4807.038,N,01131.000,E,1,08,0.9,545.4,M,46.9,M,,*47\r\n'

try:
    # Using NMEAReader.parse() for individual messages
    parsed_message = NMEAReader.parse(nmea_string, validate=VALCKSUM | VALMSGID)
    print(f"Parsed GGA message: {parsed_message}")
    print(f"  Talker: {parsed_message.talker}")
    print(f"  Message ID: {parsed_message.msgID}")
    print(f"  Latitude: {parsed_message.lat}° {parsed_message.lat_dir}")
    print(f"  Longitude: {parsed_message.lon}° {parsed_message.lon_dir}")
except Exception as e:
    print(f"Error parsing message: {e}")

# Example 2: Creating an NMEA message (e.g., GLL)
# For a real application, ensure correct talker, msgID, and payload values
# This example uses nominal values for illustration
from datetime import datetime, time

try:
    msg = NMEAMessage(
        talker='GP', 
        msgID='GLL', 
        msgmode=0, 
        lat=48.12345, 
        lat_dir='N', 
        lon=11.67890, 
        lon_dir='E', 
        time=time(10, 30, 0),
        status='A',
        posMode='A'
    )
    # The to_nmea() method returns the checksummed NMEA message as bytes
    generated_nmea = msg.to_nmea()
    print(f"Generated GLL message: {generated_nmea.decode('ascii').strip()}")
except Exception as e:
    print(f"Error generating message: {e}")