Skip to content
LeaderOneProPublic

About

Headless MAVLink ground control station CLI (ArduPilot-first), designed for AI coding agents and humans

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

mavctl

English | 简体中文

Headless, agent-first MAVLink ground-control CLI for ArduPilot vehicles.


Quick start — paste this into any coding agent:

uv tool install mavctl
npx skills add LeaderOnePro/mavctl -y -g

Connected to a flight controller and you can tell your Agent what to do in plain language — take off, hover, land, RTL, one instruction at a time.


mavctl is ArduPilot-first and built to be driven by both humans on a terminal and AI coding agents (Claude Code, Codex, OpenClaw, …). A resident daemon keeps the MAVLink link alive and caches vehicle state; every CLI call is one short, structured request to that daemon.

Status: developed and verified against ArduPilot SITL. It has not been proven across the breadth of real MAVLink vehicles and is not presented as ready for production flight on a real aircraft.

Why mavctl

GUI ground stations such as Mission Planner or QGroundControl are excellent for a human at the controls — and a poor interface for a shell script or an LLM agent: clickable UIs, no stable exit codes, no machine-readable output.

mavctl takes the other side of that trade:

  • the daemon owns the MAVLink connection and continuously caches telemetry, so each command is quick and stateless;
  • every command prints human-readable output by default and structured JSON with --json;
  • failures carry explicit exit codes (3 daemon down, 4 link lost, 5 guard rejection, 6 vehicle NACK / timeout) instead of stack traces;
  • dangerous operations pass safety guards before anything reaches the vehicle;
  • mavctl embeds no LLM — it is designed to be called by agents such as Claude Code, Codex or OpenClaw, or by plain bash.

Current capabilities

Implemented commands — this is the complete list:

mavctl daemon start|stop|status
mavctl status
mavctl telemetry
mavctl arm
mavctl disarm
mavctl mode <MODE>
mavctl takeoff --alt <metres>
mavctl land
mavctl rtl
mavctl mission upload <mission.json> --confirm [--dry-run]
mavctl mission download [--output <mission.json>] [--json]
mavctl mission clear --confirm [--dry-run]
mavctl mission start --confirm [--wait] [--timeout]   # 0.4.0; mock- and ArduCopter SITL-validated
mavctl operation get <operation_id> [--json]

Cross-cutting behaviour:

Flag / behaviour Meaning
--json structured output on stdout; errors as {"error": {...}} on stderr
--confirm required on every state-changing command; without it exit code 5
--dry-run run the exact same guards, never reach the vehicle
--wait --timeout <s> block until the target state is reached (default 60 s)
idempotent repeats re-applying an achieved change succeeds ("already armed")
transaction safety ACK/NACK handling, serialized commands, link-loss abort

Mission upload/download/clear are validated against ArduPilot SITL (lossless upload → download round-trip, including takeoff items): the automated suite runs on a dedicated MAVProxy-free loopback instance, and the shared sim_vehicle + MAVProxy relay topology was validated with the same suite plus a manual CLI acceptance. mavctl uses its own GCS identity (default source system 254, configurable via mavctl daemon start --source-system <1..255>) so it never shares an on-wire identity with the GCS it was validated against (MAVProxy 1.8.74, default 255/230); transfers additionally converge on duplicated relay traffic. Mission support is ArduPilot SITL validated only — no real-aircraft claim. The SITL conformance ran against a locally modified ArduPilot checkout at revision 4c98c9221a; the only reviewed source modification was a macOS host-build/linker workaround in AP_FWVersion.h that does not alter mission/GCS runtime code.

Mission start (0.4.0, mock- and ArduCopter-SITL-validated): mavctl mission start --confirm arms nothing and takes off nothing — it sends MAV_CMD_MISSION_START to a vehicle that already has a verified stored mission, an armed heartbeat, and a fresh link. On ArduCopter the vehicle handler may transition to AUTO and start or resume execution — explicit, confirmation-gated behavior. --wait observes the bounded start milestone (mission ACTIVE + mode AUTO), never whole-mission completion. SITL execution conformance passed against an isolated no-MAVProxy loopback ArduCopter instance (automated in tests/test_mission_execution_sitl.py: guard negative paths, the start milestone, idempotent re-start, RTL supersession); no real-aircraft claim.

Health observation (0.4.1, observe-only; ArduCopter SITL-validated): status --json carries a health block with raw vehicle-reported observations — the estimator (EKF_STATUS_REPORT: raw flag mask, dialect flag names, variance floats, independent monotonic age), raw SYS_STATUS sensor present/enabled/health bitmasks, and the most recent PreArm:/Arm:/PreArm_EKF: diagnostic from STATUSTEXT. It is strictly observe-only: no health CLI command, no health/pre-arm guard, and MAV_CMD_RUN_PREARM_CHECKS is never sent. estimator.status is unknown or observed — it never claims healthy; unknown (never received or stale) is not a health judgement, and a stale cached observation is history, not permission. ArduPilot's own pre-arm checks remain the final authority. Automated in tests/test_health_observation.py (mock) and tests/test_health_sitl.py (live loopback observation).

Not implemented — current scope only, not a roadmap promise:

Mission pause/resume/stop/set-current (mission start ships mock- and
ArduCopter-SITL-validated in 0.4.0)
Operation cancel
Parameters
Geofence
Log download / analysis
Firmware flashing
Multi-vehicle orchestration

Notable in 0.4.1:

  • Health observation runtime v1 (observe-only): status --json gains a health block — raw EKF_STATUS_REPORT observation (flag mask, dialect-known flag names, variance fields, independent monotonic age), raw SYS_STATUS sensor present/enabled/health bitmasks, and the most recent locked-autopilot PreArm:/Arm:/PreArm_EKF: STATUSTEXT diagnostic with its own freshness age. Strictly observe-only: no health CLI command, no health advisory or hard guard, MAV_CMD_RUN_PREARM_CHECKS is never sent, unknown/stale is never healthy, and ArduPilot's pre-arm checks remain the final authority.

Notable in 0.4.0:

  • Operation foundation (Phase 3B-0): takeoff --wait, land --wait and rtl --wait run their milestone observation through a daemon-owned operation: the command lock is released as soon as the vehicle accepts the command, so rtl / land / status stay available while a wait is in progress.
  • A later accepted command supersedes an in-flight wait: the superseded command reports exit 6 operation_superseded — it was executed (ACKed), not cancelled; re-check the vehicle with mavctl status.
  • --timeout expiry reports exit 6 operation_wait_timeout with operation_still_running: true — the accepted vehicle action is not cancelled by the client timeout.
  • mavctl operation get <id> observes an operation (read-only). If the daemon restarted, the operation is unknown — re-check mavctl status; that does not mean the vehicle action did not happen.
  • Mission start (Phase 3B-1): mavctl mission start --confirm [--wait] [--timeout] — explicit, confirmation-gated execution. On ArduCopter it may transition the vehicle to AUTO and start/resume the stored mission; it never motor-arms or takes off implicitly, and --wait observes the bounded startup milestone (mission ACTIVE + mode AUTO), never whole-mission completion.
  • Guard semantics fix found by SITL conformance: an empty ArduPilot mission answers MISSION_COUNT == 1 (the vehicle-managed home slot is re-written on every unlocked arming), so the mission-start guard requires wire count >= 2.

Notable in 0.3.0:

  • Mission Protocol Core (Phase 3A): mavctl mission upload / download / clear — ArduPilot-first Mission JSON v1 (takeoff/waypoint/land/ rtl), lossless-or-fail download, fresh-ground guards, clear verified by count read-back.
  • ArduPilot compatibility: home-slot wire convention, float MISSION_REQUEST upload pacing, relay-residue settle quarantine on the validated shared MAVProxy topology.
  • Distinct mavctl GCS identity (default source system 254, component 190; mavctl daemon start --source-system <1..255>) so mavctl coexists with a conventional GCS on 255.
  • Mission support is ArduPilot SITL validated only — no real-aircraft claim; mission execution / start / AUTO was intentionally not included in 0.3.0 (mission start shipped in 0.4.0).

Notable in 0.2.1:

  • mavctl --version prints the installed version — no daemon or vehicle needed.
  • status --json carries per-stream freshness ages: telemetry_age_s, gps_age_s, battery_age_s, home_position_age_s, landed_state_age_s (monotonic-clock based; they keep counting after heartbeat loss so cache staleness stays visible).
  • Ordinary non-force disarm requires fresh positive ground evidence; stale apparent ground evidence is rejected as ground_state_stale (exit 5).

Quickstart with ArduPilot SITL

Requires Python >= 3.10 and uv. Always bring up SITL first; do not point an agent-driven workflow at a real vehicle.

Terminal 1 — start ArduPilot SITL:

sim_vehicle.py -v ArduCopter --out udp:127.0.0.1:14550

Terminal 2 — install from source and connect:

uv sync
uv run mavctl daemon start --connect udp:127.0.0.1:14550
uv run mavctl status --json

Safe takeoff to 10 m and return to launch:

uv run mavctl mode GUIDED --confirm --wait
uv run mavctl arm --confirm
# Poll status --json until armed=true (the arm ACK can beat the heartbeat)
uv run mavctl takeoff --alt 10 --confirm --wait --timeout 45
uv run mavctl rtl --confirm --wait --timeout 120
uv run mavctl daemon stop

Safety notes — read before pointing mavctl at anything that flies:

  • Validate every workflow in SITL first; treat real-aircraft use as its own review process.
  • After arm, poll status --json until armed=true before takeoff: the COMMAND_ACK can arrive about one heartbeat before reported state catches up.
  • End flights with rtl / land, not disarm. Ordinary disarm requires provable ground contact (ground_state_unknown otherwise).
  • disarm --force is an emergency motor stop only — in flight it can cause a crash.
  • There is no arm --force anywhere in mavctl; pre-arm checks cannot be bypassed.

Install from PyPI

mavctl 0.4.0 is published on production PyPI. Install with:

uv tool install --upgrade mavctl
# or run once without a persistent install:
uvx mavctl --help
# or:
pipx install mavctl

Verify the install — mavctl --version needs no daemon or vehicle:

mavctl --version

Before pointing mavctl at anything that flies, walk through the SITL-first quickstart above. Release history and the publishing runbook live in docs/PUBLISHING.md.

Install from source

For development from source, use uv sync and uv run mavctl …:

git clone https://github.com/LeaderOnePro/mavctl.git
cd mavctl
uv sync
uv run mavctl --help

Agent Skill

mavctl bundles a portable Agent Skill under skills/mavctl-flight/ (entrypoint plus workflows / safety / troubleshooting references). It is a source asset of this repo: installing the Skill is independent of installing the mavctl CLI from PyPI, e.g. uv tool install mavctl.

Install the bundled Agent Skill globally:

npx skills add LeaderOnePro/mavctl -y -g

The community skills CLI manages installation for the agent runtimes it supports, according to its current environment and configuration. See docs/SKILLS_CLI_ACCEPTANCE.md for tested behaviour and compatibility notes.

Safety model

Short version; full details in skills/mavctl-flight/references/safety.md:

  • the daemon owns the vehicle link; CLI calls are short transactions;
  • state-changing commands require --confirm; --dry-run previews decisions;
  • exit 4 = no live vehicle state (link lost / heartbeat expired), including mid---wait loss (link_lost_during_wait);
  • exit 5 = guard rejection with structured reason + hint;
  • exit 6 = vehicle NACK / ACK timeout / wait timeout;
  • force-arm does not exist at any layer (CLI option, RPC field, adapter verb);
  • ordinary disarm needs positive ground evidence, else ground_state_unknown (exit 5);
  • after link loss, status reflects stale cache: armed renders unknown/n/a, never silently disarmed.

Development

uv sync
uv run ruff check .
uv run mypy .
uv run pytest -m "not sitl"
uv run pytest -m sitl   # requires a running ArduPilot SITL

Further reading:

License

MIT — Copyright (c) 2026 LeaderOnePro.

About

Headless MAVLink ground control station CLI (ArduPilot-first), designed for AI coding agents and humans

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages