rtcm3-cli 0.1.0

Command-line decoder for RTCM3 GNSS RTK correction streams, built on rtcm3
# rtcm3

[![CI](https://github.com/hz2/rtcm3/actions/workflows/ci.yml/badge.svg)](https://github.com/hz2/rtcm3/actions/workflows/ci.yml)
[![crates.io](https://img.shields.io/crates/v/rtcm3.svg)](https://crates.io/crates/rtcm3)
[![docs.rs](https://img.shields.io/docsrs/rtcm3)](https://docs.rs/rtcm3)
[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![no_std](https://img.shields.io/badge/no__std-yes-brightgreen.svg)](#)

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`]https://github.com/semuconsulting/pyrtcm and, for
  the harder MSM7 message, independently against
  [RTKLIB]https://github.com/tomojitakasu/RTKLIB's C source.
- **Fuzz-tested with [proptest]https://docs.rs/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]#formal-verification, not just tests.

## Crates

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

## Quick start

```rust
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:

```sh
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`](crates/rtcm3/src/message/gps_msm7.rs).

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

## C FFI

[`rtcm3-ffi`](crates/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`](crates/rtcm3-ffi/include/rtcm3.h)
for the generated header and
[`crates/rtcm3-ffi/tests/smoke.c`](crates/rtcm3-ffi/tests/smoke.c) for a
worked example.

## Building

This project is built and checked with [Nix](https://nixos.org/):

```sh
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](https://github.com/model-checking/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`:

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

## License

MIT. See [LICENSE](LICENSE).