Crate marlin_nmea_0183

Expand description

§marlin-nmea-0183

Sans-I/O typed decoders for NMEA 0183 sentences. Built on marlin-nmea-envelope.

The envelope crate produces RawSentence values — verified framing, checksum-checked, fields split as byte slices. This crate turns those into typed Rust structs:

 bytes → marlin_nmea_envelope → RawSentence → marlin_nmea_0183 → Nmea0183Message

§Supported sentence types

$__GGA — GgaData — position + fix quality + satellites
$__HDT — HdtData — true heading
$__VTG — VtgData — course & speed over ground
$PSXN — PsxnData — Kongsberg-family proprietary motion; slot meanings are install-configurable via PsxnLayout / DecodeOptions
$PRDID — PrdidData — proprietary attitude with multiple vendor dialects; default refuses to guess (emits PrdidData::Raw). Select a dialect via DecodeOptions::with_prdid_dialect.

The talker ID is preserved as metadata on each typed struct rather than dispatched on; $GPGGA, $INGGA, $GNGGA all decode to GgaData with different talker values.

§Quickstart

use marlin_nmea_envelope::{OneShot, SentenceSource};
use marlin_nmea_0183::{decode, Nmea0183Message};

// Classic NMEA 0183 GGA example (checksum 0x47 = XOR of body bytes).
let mut parser = OneShot::new();
parser.feed(b"$GPGGA,123519,4807.038,N,01131.000,E,1,08,0.9,545.4,M,46.9,M,,*47");

let raw = parser.next_sentence().unwrap().unwrap();
match decode(&raw).unwrap() {
    Nmea0183Message::Gga(gga) => {
        assert_eq!(gga.talker, Some(*b"GP"));
        assert_eq!(gga.satellites_used, Some(8));
    }
    _ => panic!("expected GGA"),
}

§Extension

Each sentence type has a public per-sentence decoder (decode_gga, decode_hdt, …). Downstream crates that need proprietary sentences this crate doesn’t decode can build their own enum and delegate to these decoders. See the crate README for a full example.

§Policy

Unknown sentence types are returned as Nmea0183Message::Unknown with the raw sentence preserved. They are not silently dropped and not returned as errors — the caller decides what to do with them.

Structs§

DecodeOptions: Runtime configuration for ambiguous sentence decodings.
GgaData: Decoded fields of a $__GGA sentence.
GllData: Decoded fields of a $__GLL sentence.
HdtData: Decoded fields of a $__HDT sentence.
Nmea0183Parser: Typed-message parser built on top of any envelope-level SentenceSource that produces RawSentence values.
PrdidPitchRollHeading: PRDID decoded with field order pitch, roll, heading — the canonical Teledyne RDI ADCP ordering.
PrdidRollPitchHeading: PRDID decoded with field order roll, pitch, heading — an alternative ordering seen on some integration guides. Not compatible with the Teledyne RDI ordering; swapping them produces wrong data silently.
PsxnData: Decoded fields of a $PSXN sentence.
PsxnLayout: Configuration for how PSXN dataN slots map to motion quantities.
RawSentence: A single NMEA 0183 sentence, borrowed from the parser’s internal buffer.
RmcData: Decoded fields of an $__RMC sentence.
UtcDate: UTC calendar date as carried by RMC’s ddmmyy field.
UtcTime: UTC time-of-day with millisecond resolution.
VtgData: Decoded fields of a $__VTG sentence.

Enums§

DataStatus: Two-state validity flag from the RMC and GLL Status field.
DecodeError: Errors that can occur while decoding a typed NMEA sentence.
GgaFixQuality: GPS fix quality indicator — first field after time/lat/lon/hemi.
Nmea0183Error: Errors surfacing from Nmea0183Parser::next_message (and from the Parser enum’s delegating method).
Nmea0183Message: A typed NMEA 0183 message.
Parser: Runtime selector between one-shot and streaming typed parsers.
PrdidData: Typed payload of a $PRDID sentence.
PrdidDialect: Runtime selector for which PRDID field ordering to decode with.
PsxnLayoutParseError: Error from parsing a legacy PSXN layout string like "rphx1".
PsxnSlot: Meaning of one of the six dataN slots in a PSXN sentence.
RmcNavStatus: NMEA 4.10+ navigational-status byte — 13th field of RMC.
VtgMode: NMEA 2.3+ mode indicator — 9th field of VTG.

Functions§

decode: Decode a RawSentence into a typed Nmea0183Message using the default DecodeOptions.
decode_gga: Decode a GGA sentence into typed fields.
decode_gll: Decode a GLL sentence into typed fields.
decode_hdt: Decode an HDT sentence.
decode_prdid: Decode a PRDID sentence using the given dialect.
decode_prdid_pitch_roll_heading: Decode a PRDID sentence as pitch, roll, heading (Teledyne RDI canonical ordering).
decode_prdid_roll_pitch_heading: Decode a PRDID sentence as roll, pitch, heading (alternative ordering).
decode_psxn: Decode a $PSXN sentence using the provided layout.
decode_rmc: Decode an RMC sentence into typed fields.
decode_vtg: Decode a VTG sentence into typed fields.
decode_with: Decode a RawSentence into a typed Nmea0183Message using the supplied DecodeOptions.