pynmea2 NMEA 0183 Protocol Parser

Common errors

• pynmea2.ChecksumError: Checksum doesn't match

  cause The NMEA sentence provided to `pynmea2.parse()` has an incorrect or missing checksum.
  fix Verify the integrity of your NMEA data source. If you're generating sentences, ensure the checksum is calculated correctly. For parsing, wrap `pynmea2.parse()` in a `try-except pynmea2.ChecksumError` block to handle bad data, or consider disabling checksum validation if data integrity is not paramount (e.g., `pynmea2.parse(data, checksum=False)`).

• pynmea2.ParseError: sentence did not start with '$' or '!'

  cause The input string passed to `pynmea2.parse()` does not begin with the standard NMEA start character (`$` or `!`), indicating it's not a valid NMEA sentence or it's part of a larger string.
  fix Pre-process your input data to extract only the raw NMEA sentence, ensuring it starts with `$` or `!` and includes the full sentence up to the checksum and newline. This often involves buffering and line-splitting when reading from a stream.

• AttributeError: 'RMC' object has no attribute 'some_invalid_field'

  cause You are trying to access a field that does not exist for the specific NMEA sentence type (e.g., trying to get 'altitude' from an RMC sentence, which doesn't have it).
  fix Consult the NMEA 0183 specification or the `pynmea2` documentation for the fields available for each sentence type. Use `msg.sentence_type` to dynamically determine the type and access fields conditionally.

Warnings

• gotcha `pynmea2.parse()` performs checksum validation by default. If your NMEA sentences have invalid or missing checksums, it will raise a `pynmea2.ChecksumError`.
  Fix: Wrap calls to `pynmea2.parse()` in a `try-except pynmea2.ChecksumError` block. If you absolutely must, you can disable checksum validation by passing `checksum=False` to `pynmea2.parse()`, but this is generally not recommended for reliable data.
• gotcha When receiving NMEA data from a stream (e.g., serial port, socket), you often receive incomplete lines. `pynmea2.parse()` expects a complete NMEA sentence starting with `$` or `!` and ending with a newline, including the checksum.
  Fix: Implement a buffer that accumulates data until a complete NMEA sentence (from `$` or `!` to `*XX` and newline) is received before passing it to `pynmea2.parse()`. Libraries like `pyserial` often handle line-by-line reading.
• gotcha NMEA sentences have fixed fields, and attempting to access a non-existent field (e.g., `msg.speed` on a GGA sentence) will result in an `AttributeError`.
  Fix: Always check the `msg.sentence_type` or `msg.talker_id` and refer to the NMEA 0183 standard or pynmea2 documentation for the available fields for that specific sentence type before accessing them.

Install

• pip install pynmea2 Install pynmea2

Imports

• parse

  import pynmea2
  msg = pynmea2.parse('$GPGGA,...')

  The primary function for parsing NMEA strings.
• GGA
  wrong:

  from pynmea2.types.talker import GGA

  correct:

  from pynmea2 import GGA
  msg = GGA('GP', 'GGA', (...))

  While sentence types exist in `pynmea2.types.talker`, they are conveniently exposed directly under the `pynmea2` namespace for easier access, especially for creation.
• ChecksumError

  from pynmea2 import ChecksumError

  Exception raised when an NMEA sentence has an invalid checksum.
• ParseError

  from pynmea2 import ParseError

  General exception for malformed NMEA sentences.

Quickstart

This quickstart demonstrates how to parse an existing NMEA 0183 GGA sentence and how to construct a new GGA sentence from scratch. It includes basic error handling for common parsing issues.

import pynmea2
import datetime

# Example 1: Parsing an NMEA sentence
raw_gga = '$GPGGA,184353.07,1929.045,S,02410.506,E,1,04,2.6,100.00,M,-33.9,M,,0000*6D'
try:
    msg = pynmea2.parse(raw_gga)
    print(f"Parsed sentence type: {msg.sentence_type}")
    print(f"Timestamp: {msg.timestamp}")
    print(f"Latitude: {msg.latitude}, Longitude: {msg.longitude}")
except pynmea2.ChecksumError as e:
    print(f"Checksum error: {e}")
except pynmea2.ParseError as e:
    print(f"Parse error: {e}")

# Example 2: Creating an NMEA sentence
# GGA fields: (timestamp, lat, lat_dir, lon, lon_dir, fix_quality, num_sats, hdop, alt, alt_units, geoid_sep, geoid_units, age_of_diff, diff_ref_id)
# Note: lat/lon can be floats, others mostly strings/ints
timestamp_val = datetime.time(12, 0, 0)
lat_val = '3404.70417'
lat_dir_val = 'N'
lon_val = '11808.66539'
lon_dir_val = 'W'

try:
    new_gga = pynmea2.GGA('GP', 'GGA', (
        timestamp_val, lat_val, lat_dir_val, lon_val, lon_dir_val,
        1, 8, 0.9, 500.0, 'M', 25.0, 'M', '', ''
    ))
    print(f"\nCreated NMEA sentence: {str(new_gga)}")
except ValueError as e:
    print(f"Error creating GGA sentence: {e}")