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