mavkit 0.1.0

Async MAVLink SDK for vehicle control, missions, and parameters
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112

# MAVKit

MAVKit (crate name: `mavkit`) is an async Rust SDK for MAVLink vehicles.

It provides a transport-agnostic `Vehicle` API for:
- connection and link state
- telemetry and status watches
- vehicle actions (arm/disarm, mode, takeoff, guided goto)
- mission upload/download/clear/set-current
- parameter download and write operations

The crate is designed to be embedded in desktop/mobile apps, CLIs, or backend services.

## Features

- `udp` (default): enable MAVLink UDP transport strings (via `mavlink`)
- `tcp`: enable MAVLink TCP transport strings
- `serial` (default): enable MAVLink direct serial transport strings
- `ardupilot` (default): ArduPilot mode-name mapping helpers
- `stream`: byte-stream transport adapters for BLE/SPP/custom links

Default features: `udp`, `serial`, `ardupilot`.

## Install

```toml
[dependencies]
mavkit = "0.1"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
```

## Quick start

```rust,no_run
use mavkit::Vehicle;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
  let vehicle = Vehicle::connect_udp("0.0.0.0:14550").await?;

  let mut state_rx = vehicle.state();
  state_rx.changed().await?;
  let state = state_rx.borrow().clone();
  println!("mode={} armed={}", state.mode_name, state.armed);

  vehicle.disconnect().await?;
  Ok(())
}
```

## Mission wire semantics

For `MissionType::Mission`, MAVLink wire transfer is normalized as:
- upload: a home item is prepended at `seq=0` (or placeholder if missing)
- download: wire `seq=0` is extracted as home and remaining items are resequenced from `0`

For `MissionType::Fence` and `MissionType::Rally`, items pass through unchanged.

These semantics are implemented in:
- `items_for_wire_upload`
- `plan_from_wire_download`

## Examples

- `examples/connect_udp.rs`
- `examples/mission_upload_download.rs`
- `examples/params_roundtrip.rs`

Run an example:

```bash
cargo run --example connect_udp
```

## Development

Common local checks:

```bash
cargo check
cargo clippy --all-targets --all-features -- -D warnings
cargo test
```

SITL helper targets:

```bash
make bridge-up
make test-sitl
make test-sitl-strict
make bridge-down
```

## SITL integration testing

Ignored integration tests in `tests/sitl_roundtrip.rs` can be run against ArduPilot SITL.

Environment variables:
- `MAVKIT_SITL_UDP_BIND` (default: `0.0.0.0:14550`)
- `MAVKIT_SITL_STRICT` (`1` to fail on strict timeout/unsupported behavior)

Run:

```bash
MAVKIT_SITL_UDP_BIND=0.0.0.0:14550 \
cargo test --test sitl_roundtrip -- --ignored --nocapture --test-threads=1
```

## Notes

- `Vehicle::from_connection(...)` is the transport-agnostic entry point for custom links.
- `Vehicle::identity()` currently reflects autopilot and vehicle type; system/component ids are not yet exposed from the current state channels.