mavwire-cli 0.1.0

Command-line decoder for MAVLink v1/v2 telemetry streams, built on mavwire
# mavwire

[![CI](https://github.com/hz2/mavwire/actions/workflows/ci.yml/badge.svg)](https://github.com/hz2/mavwire/actions/workflows/ci.yml)
[![crates.io](https://img.shields.io/crates/v/mavwire.svg)](https://crates.io/crates/mavwire)
[![docs.rs](https://img.shields.io/docsrs/mavwire)](https://docs.rs/mavwire)
[![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 **MAVLink v1/v2**
telemetry messages, the wire protocol used by most drone/autopilot flight
stacks (ArduPilot, PX4) and ground control stations.

- **Ten message types**, decode and encode: HEARTBEAT, SYS_STATUS,
  PARAM_VALUE, GPS_RAW_INT, ATTITUDE, GLOBAL_POSITION_INT, RC_CHANNELS,
  VFR_HUD, COMMAND_LONG, COMMAND_ACK, and STATUSTEXT. Every test fixture
  is a real captured frame, cross-checked against
  [`pymavlink`]https://github.com/ArduPilot/pymavlink, not synthetic
  round trips.
- **Fuzz-tested with [proptest]https://docs.rs/proptest**: message
  decode/encode never panics on arbitrary bytes.
- **Both MAVLink v1 and v2 wire framing**, including v2's trailing-zero
  payload truncation.
- **`no_std`, no `alloc`**: works on bare-metal targets with no allocator.
- **Zero mandatory dependencies.** The frame/CRC codec is hand-rolled.
- **`#![forbid(unsafe_code)]`.**
- **Formal verification** of the CRC and frame layer with
  [Kani]#formal-verification, not just tests.

## Crates

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

## Quick start

```rust
let message = mavwire::decode(&frame_bytes)?;

let mavwire::MavMessage::Heartbeat(hb) = message else {
    panic!("expected a HEARTBEAT message");
};
println!("mav_type={} autopilot={}", hb.mav_type, hb.autopilot);
```

Add it to a project with:

```sh
cargo add mavwire
```

## Message type coverage

| Message | ID |
| --- | --- |
| HEARTBEAT | 0 |
| SYS_STATUS | 1 |
| PARAM_VALUE | 22 |
| GPS_RAW_INT | 24 |
| ATTITUDE | 30 |
| GLOBAL_POSITION_INT | 33 |
| RC_CHANNELS | 65 |
| VFR_HUD | 74 |
| COMMAND_LONG | 76 |
| COMMAND_ACK | 77 |
| STATUSTEXT | 253 |

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

## C FFI

[`mavwire-ffi`](crates/mavwire-ffi) exposes a C API over the core
decoder: an opaque message handle, a small error enum, and one
`mavwire_message_as_<type>` accessor per message type. See
[`crates/mavwire-ffi/include/mavwire.h`](crates/mavwire-ffi/include/mavwire.h)
for the generated header and
[`crates/mavwire-ffi/tests/smoke.c`](crates/mavwire-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           # mavwire-cli (default package)
nix build .#mavwire
nix build .#mavwire-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 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 computation never panics, for any input.
- Frame parsing never panics on arbitrary bytes.
- Encoding a v2 frame and parsing it back recovers the original message
  id and 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 mavwire
```

## License

MIT. See [LICENSE](LICENSE).