nmea

The nmea library parses NMEA 0183 sentences from GPS/GNSS receivers into canonical raw terms and provides typed semantic decoding for a selected set of common sentence types.

API documentation

Open the ../../apis/library_index.html#nmea link in a web browser.

Loading

To load this library, load the loader.lgt file:

| ?- logtalk_load(nmea(loader)).

Testing

To test this library predicates, load the tester.lgt file:

| ?- logtalk_load(nmea(tester)).

Public API

  • parse/2 parses sentences from atom(Atom), chars(List), codes(List), stream(Stream), or file(Path) sources.

  • parse/3 accepts parser options:

    • checksum(required)

    • checksum(optional)

    • checksum(ignore)

    • unknown_type(keep)

    • unknown_type(error)

  • malformed sentence identifiers and malformed supported coordinate/date fields are rejected as invalid NMEA sentences during parsing

  • talker/2, sentence_type/2, fields/2, and checksum/2 access parts of the raw parsed term.

  • data/2 maps supported sentence types into typed semantic terms.

Raw Sentence Representation

Parsed sentences are represented as:

nmea_sentence(Talker, Type, Fields, checksum(Provided, Computed))

Where:

  • Talker is a normalized lowercase talker atom such as gp or gn

  • proprietary $P... sentences use the atom proprietary

  • Type is the normalized lowercase sentence type atom

  • Fields is the ordered list of field atoms after the sentence identifier

  • Provided is either a normalized uppercase hexadecimal checksum atom or missing

  • Computed is the normalized uppercase hexadecimal checksum atom computed from the sentence payload

Typed data/2 Results

The library currently provides semantic decoding for these sentence types:

  • gga(Time, Coordinate, fix(FixQuality, SatellitesUsed, HDOP), altitude(AntennaAltitudeMeters, GeoidSeparationMeters), dgps(DifferentialAgeSeconds, StationId))

  • rmc(Time, Status, Coordinate, movement(SpeedKnots, CourseDegrees), Date, MagneticVariation, Mode)

  • gsa(SelectionMode, FixType, SatelliteIds, dop(PDOP, HDOP, VDOP), SystemId)

  • gsv(MessageCount, MessageNumber, SatellitesInView, Satellites)

  • vtg(track(TrueCourseDegrees, MagneticCourseDegrees), speed(SpeedKnots, SpeedKph), Mode)

  • gll(Coordinate, Time, Status, Mode)

Shared semantic subterms include:

  • geographic(Latitude, Longitude)

  • utc_time(Hour, Minute, Second, fraction(Numerator, Denominator))

  • date(Year, Month, Day)

  • magnetic_variation(Degrees, east|west)

  • satellite(PRN, ElevationDegrees, AzimuthDegrees, SnrDbHz)

  • missing

Date Rule

Two-digit RMC years are expanded using a fixed GPS-era rule:

  • 80..99 map to 1980..1999

  • 00..79 map to 2000..2079

Current Scope

Implemented in this first version:

  • raw parsing from text sources

  • configurable checksum handling

  • proprietary $P... sentence passthrough

  • semantic decoding for GGA, RMC, GSA, GSV, VTG, and GLL

Deliberately out of scope for this first version:

  • sentence generation

  • AIS ! sentences

  • serial or socket transport helpers

  • corrupted-stream resynchronization

  • GSV multi-fragment aggregation

  • typed proprietary sentence decoding