# rtcm3
[](https://github.com/hz2/rtcm3/actions/workflows/ci.yml)
[](https://crates.io/crates/rtcm3)
[](https://docs.rs/rtcm3)
[](LICENSE)
[](#)
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
| [`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
| 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).