rtcm3-cli 0.1.0

Command-line decoder for RTCM3 GNSS RTK correction streams, built on rtcm3
rtcm3-cli-0.1.0 is not a library.

rtcm3

CI crates.io docs.rs license: MIT no_std

A no_std, allocation-free parser and encoder for RTCM3 GNSS RTK correction messages, the binary wire format used to distribute differential GNSS/RTK corrections between base stations, NTRIP casters, and rover receivers.

  • Three message types, decode and encode: Stationary RTK Reference Station ARP (1005), GLONASS Code-Phase Biases (1230), and GPS MSM7 (1077, the actual pseudorange/carrier-phase/Doppler/CNR observation data). Every test fixture is a real captured frame, cross-checked against pyrtcm and, for the harder MSM7 message, independently against RTKLIB's C source.
  • Fuzz-tested with proptest: message decode never panics on arbitrary bytes, for both arbitrary and known-message-type payloads.
  • A genuine bit-level codec: unlike a byte-aligned protocol, RTCM3 packs arbitrary-bit-width fields MSB-first, including MSM's mask-driven, variable-length repeat groups (a satellite mask and signal mask determine a cell mask, and only after reading all three does the number of repeated field groups become known).
  • no_std, no alloc: works on bare-metal targets with no allocator.
  • Zero mandatory dependencies. The bit-level codec and CRC-24Q are hand-rolled.
  • #![forbid(unsafe_code)].
  • Formal verification of the CRC-24Q and frame layer with Kani, not just tests.

Crates

Crate Description
rtcm3 The no_std, no-alloc parser/encoder library.
rtcm3-cli A small command-line decoder (installs as rtcm3).
rtcm3-ffi C FFI bindings, for calling from C/C++.

Quick start

let message = rtcm3::decode(&frame_bytes)?;

let rtcm3::Rtcm3Message::StationArp(arp) = message else {
    panic!("expected a Stationary RTK Reference Station ARP message");
};
println!("x={:.4}m y={:.4}m z={:.4}m", arp.x_meters(), arp.y_meters(), arp.z_meters());

Add it to a project with:

cargo add rtcm3

Message type coverage

Type What
1005 Stationary RTK Reference Station ARP
1230 GLONASS Code-Phase Biases
1077 GPS Full Pseudoranges and PhaseRanges plus CNR (MSM7)

A real captured MSM7 frame can carry trailing padding bits beyond what its own mask-derived field counts require (confirmed independently via RTKLIB's own decoder, whose length check is >= not ==); this crate's decoder tolerates that the same way, documented in crates/rtcm3/src/message/gps_msm7.rs.

See crates/rtcm3/src/lib.rs for the crate's module layout and crates/rtcm3/src/message for each message type, each with its own real-fixture tests.

C FFI

rtcm3-ffi exposes a C API over the core decoder: an opaque message handle, a small error enum, and one rtcm3_message_as_<type> accessor per message type. See crates/rtcm3-ffi/include/rtcm3.h for the generated header and crates/rtcm3-ffi/tests/smoke.c for a worked example.

Building

This project is built and checked with Nix:

nix develop        # dev shell: toolchain, rust-analyzer
nix flake check -L # fmt, clippy (pedantic), tests, no_std/no_alloc cross-compile, FFI header/smoke checks
nix build           # rtcm3-cli (default package)
nix build .#rtcm3
nix build .#rtcm3-ffi

CI runs the identical nix flake check -L, so there is one source of truth for what "passing" means, locally and in GitHub Actions.

Without Nix, a standard cargo build / cargo test from the workspace root also works with a recent stable Rust toolchain (edition 2024, MSRV tracked in Cargo.toml).

Formal verification

The CRC-24Q checksum and frame layer (src/crc.rs, src/frame.rs) are proven, not just tested, using Kani, a bounded model checker for Rust. Where the test suite samples inputs, these harnesses (gated behind #[cfg(kani)], so they add nothing to normal builds) prove properties over every input in a bounded space:

  • CRC-24Q computation never panics, for any input - including the nested-loop accumulator, which needs an explicit unwind bound CBMC doesn't infer on its own.
  • Frame parsing never panics on arbitrary bytes.
  • Encoding a frame and parsing it back recovers the original payload exactly.

Kani requires its own toolchain download (a pinned nightly + CBMC), which needs network access and isn't run inside the hermetic Nix sandbox, so it's a manual step rather than part of nix flake check:

cargo install --locked kani-verifier
cargo kani setup
cargo kani -p rtcm3

License

MIT. See LICENSE.