@h2loop/uav 1.0.0

package/bridge/README.md

@@ -0,0 +1,163 @@
+# UAV Pack — Live-Link MCP Bridge (Tier R read-only + gated Tier C param read/write)
+
+A thin, **firmware-agnostic** MCP server (stdio transport, [FastMCP]) that exposes
+ArduPilot / PX4 **telemetry and parameters** to an MCP client (Hydron's `uav`
+persona). It speaks MAVLink through `pymavlink.mavutil`, so it serves **every UAV
+lab — ArduPilot and PX4** — over a live link **or** an offline log replay.
+
+It implements the read-only **Tier R** tool contract plus a **gated Tier C
+parameter read/write** tier — the firmware-track on-ramp. See the spec:
+[`internal-docs/.../uav/10-live-link-mcp-bridge.md`](../../internal-docs/wiki/engineering/features/domain-plugins/uav/10-live-link-mcp-bridge.md).
+
+## Flight command/control is NEVER here
+
+This server registers **no flight command/control tools** — in **any** mode.
+There is no arm/disarm, no `set_mode`, no takeoff/land/goto, and no mission
+upload. A tool that is not registered cannot be called *or* sit in the client's
+context — that is the strongest gate (per the spec's "server build is the true
+hide"). Enabling a live-C2 flight surface would be a deliberate, separate change
+on a dedicated `uav-sitl` persona — and is **not** what the Tier C tier below is.
+
+## Tools (Tier R — read-only)
+
+| Tool | Purpose |
+|---|---|
+| `read_params()` | Dump current parameters as `{name: value}` (PARM / PARAM_VALUE). |
+| `get_messages(types, limit=100)` | Recent messages of the given type(s) as a list of dicts. `types` is a string or list. |
+| `tail_telemetry(seconds=5.0)` | Poll telemetry for N seconds; returns accumulated recent values (latest-per-type + samples). |
+| `get_flight_mode()` | Current / last-seen flight mode (e.g. `LOITER`). |
+| `get_status()` | Best-effort armed state, GPS fix, battery, link health. |
+
+## Tools (Tier C — parameter read/write, the firmware-track on-ramp)
+
+Tier C is **parameter read/write ONLY** — the param-upload + retest loop (e.g.
+pushing an `INS_HNTCH_*` notch-filter tune, then re-flying and comparing). It is
+**not** flight command-and-control: arm/takeoff/land/mission stay intentionally
+absent regardless of any flag.
+
+| Tool | Gate | Purpose |
+|---|---|---|
+| `param_get(name)` | always on | Read one param via `PARAM_REQUEST_READ`. Returns `{name, value, found}`. |
+| `param_get_all()` | always on | Explicit live full dump via `PARAM_REQUEST_LIST`. Returns `{count, params}` (same read path as `read_params`). |
+| `param_set(name, value)` | **gated** | Set one param via `PARAM_SET`, read back the `PARAM_VALUE` echo to confirm. Returns `{name, requested, confirmed, ok, ts}`. |
+| `param_set_batch(params)` | **gated** | Set several params, confirm each (the notch-tune push). Returns per-param `results`, confirmed `set_params`, and `started_ts`/`finished_ts` for **retest tagging**. |
+
+### Write gate (defense-in-depth, default OFF)
+
+The param **write** tools (`param_set`, `param_set_batch`) are usable **only**
+when the bridge is started **WITHOUT** `--read-only` (i.e. `--no-read-only`)
+**AND WITH** the explicit `--allow-param-write` flag. Both are required; either
+alone keeps writes off.
+
+- **Gate closed (default):** the write tools are registered as **disabled
+  stubs** that return a clear structured error — `"param write disabled (start
+  the bridge WITHOUT --read-only AND WITH --allow-param-write …)"` — never a
+  silent or accidental write.
+- **Gate open:** the real write tools are registered.
+- The param **reads** (`param_get`, `param_get_all`) are always available; they
+  have no vehicle side effects.
+
+**The persona must ALSO allow-list the write tool names.** The server gate and
+the persona permission ruleset are independent layers: in `.hydron/agent/uav.md`
+(or a dedicated tuning persona) you must `allow`/`ask` `mavlink_param_set` and
+`mavlink_param_set_batch`. With the server gate closed, those tools still refuse;
+with it open but the persona not allow-listing them, the client blocks the call.
+
+### Retest tagging hook
+
+`param_set_batch` returns the confirmed `set_params` (name→value) plus
+`started_ts`/`finished_ts`. The uav-tuning subagent uses this to **tag the next
+flight as a retest** — Hydron attaches the changed params + timestamps to the
+flight's tags. The bridge writes **no files**; it only returns structured data.
+
+The MCP tools are thin wrappers around a `MavlinkSource` class that holds all
+read/write logic, so tests (and other callers) can use
+`MavlinkSource(path).read_params()` / `.param_set(...)` directly without starting
+the server.
+
+## Connection strings
+
+The server takes a connection string from env `MAVLINK_CONNECT` (default) or the
+`--connect` arg, passed straight to `mavutil.mavlink_connection`:
+
+| Form | Example | Notes |
+|---|---|---|
+| UDP | `udp:127.0.0.1:14550` | Mission Planner / SITL forward |
+| TCP | `tcp:host:port` | |
+| Serial | `/dev/ttyUSB0` | direct flight controller |
+| **File** | `/path/to/flight.bin` or `*.tlog` | **offline replay** — how we test without a vehicle |
+
+Optional `--dialect` / env `MAVLINK_DIALECT` (e.g. `ardupilotmega`).
+
+## Register with Hydron — `config.mcp`
+
+```jsonc
+// .hydron/.../opencode.jsonc  — ArduPilot lab, read-only by default
+"mcp": {
+  "mavlink": {
+    "type": "local",
+    "command": ["python", "uav_mavlink_bridge.py", "--connect", "udp:127.0.0.1:14550", "--read-only"],
+    "environment": { "MAVLINK_DIALECT": "ardupilotmega" },
+    "timeout": 10000
+  }
+}
+```
+
+```jsonc
+// Tuning lab — Tier C param WRITE enabled (firmware-track on-ramp).
+// Pair with a persona that allow-lists mavlink_param_set / mavlink_param_set_batch.
+"mcp": {
+  "mavlink": {
+    "type": "local",
+    "command": ["python", "uav_mavlink_bridge.py", "--connect", "udp:127.0.0.1:14550",
+                "--no-read-only", "--allow-param-write"],
+    "environment": { "MAVLINK_DIALECT": "ardupilotmega" },
+    "timeout": 10000
+  }
+}
+```
+
+The bridge name (`mavlink`) becomes the tool prefix, so tools surface as
+`mavlink_read_params`, `mavlink_param_set`, etc.
+
+Persona permission additions (`.hydron/agent/uav.md`): `allow` the Tier R reads
+and the Tier C param **reads** (`mavlink_param_get`, `mavlink_param_get_all`). To
+use the param **writes**, the persona must additionally `allow`/`ask`
+`mavlink_param_set` and `mavlink_param_set_batch` — and the server must be
+launched with `--no-read-only --allow-param-write`. Continue to `deny` every
+flight command/control tool name as defense-in-depth.
+
+## Run / develop
+
+```bash
+pip install -r requirements.txt
+
+# Offline replay (no vehicle):
+python3 uav_mavlink_bridge.py --connect "/path/to/flight.bin"
+
+# Live link (Tier R + Tier C param reads):
+MAVLINK_CONNECT=udp:127.0.0.1:14550 python3 uav_mavlink_bridge.py
+
+# Live link with Tier C param WRITE enabled (firmware-track tuning):
+MAVLINK_CONNECT=udp:127.0.0.1:14550 python3 uav_mavlink_bridge.py --no-read-only --allow-param-write
+
+# Tests (offline replay against a real log):
+python3 -m pytest test_bridge.py -q
+```
+
+## Robustness
+
+- No flight command/control tools registered, **by construction**, in any mode.
+- Param **write** is gated OFF by default; the write tools are disabled stubs
+  until `--no-read-only --allow-param-write` opens the gate.
+- A write against an offline log replay is a **structured no-op** (returns
+  `ok: False` with a reason) — never a crash, never a phantom write.
+- `param_set` confirms via the `PARAM_VALUE` echo (float-rounding tolerant)
+  before reporting `ok: True`.
+- Every tool wraps its body in `try/except` and returns a structured error dict
+  (`{"error": True, "tool": ..., "message": ...}`) rather than crashing the
+  stdio server.
+- Bounded recv loops (per-tool time budget + message cap) so no tool can hang
+  forever, on a live link or a huge log.
+
+[FastMCP]: https://github.com/modelcontextprotocol/python-sdk

package/bridge/requirements.txt

@@ -0,0 +1,2 @@
+pymavlink>=2.4.49
+mcp[cli]>=1.0.0

package/bridge/test_bridge.py

@@ -0,0 +1,153 @@
+"""Offline-replay tests for the UAV MAVLink->MCP bridge.
+
+These drive ``MavlinkSource`` directly against a real DataFlash log — no live
+socket, no MCP server started. Run:
+
+    cd <hydron-uav-pack>/bridge
+    UAV_TEST_LOG=/path/to/flight.bin python3 -m pytest test_bridge.py -q
+    # or: UAV_TEST_LOG=/path/to/flight.bin python3 test_bridge.py
+"""
+
+import os
+import unittest
+
+from uav_mavlink_bridge import MavlinkSource, build_server
+
+# Point at a real DataFlash log via UAV_TEST_LOG; tests skip if unset/missing.
+LOG_PATH = os.environ.get("UAV_TEST_LOG", "")
+
+
+def _source():
+    # A fresh source per call: file replay consumes the connection, so each
+    # tool needs its own pass over the log.
+    return MavlinkSource(LOG_PATH)
+
+
+@unittest.skipUnless(os.path.exists(LOG_PATH), f"log not found: {LOG_PATH}")
+class TestMavlinkSourceOffline(unittest.TestCase):
+    def test_read_params(self):
+        params = _source().read_params()
+        self.assertIsInstance(params, dict)
+        self.assertIn("SYSID_THISMAV", params)
+        self.assertGreater(len(params), 100, "expected >100 params")
+        # Value is numeric.
+        self.assertIsInstance(params["SYSID_THISMAV"], float)
+
+    def test_get_messages_vibe(self):
+        msgs = _source().get_messages("VIBE", limit=10)
+        self.assertIsInstance(msgs, list)
+        self.assertGreater(len(msgs), 0)
+        self.assertLessEqual(len(msgs), 10)
+        for m in msgs:
+            self.assertIn("VibeZ", m)
+
+    def test_get_messages_multi_type(self):
+        msgs = _source().get_messages(["ATT", "BAT"])
+        types = {m.get("mavpackettype") for m in msgs}
+        self.assertIn("ATT", types)
+        self.assertIn("BAT", types)
+
+    def test_get_flight_mode(self):
+        res = _source().get_flight_mode()
+        self.assertIsInstance(res, dict)
+        self.assertTrue(res.get("mode"))
+        self.assertNotEqual(res["mode"], "UNKNOWN")
+
+    def test_get_status(self):
+        res = _source().get_status()
+        self.assertIsInstance(res, dict)
+        populated = [
+            res.get("armed") is not None,
+            bool(res.get("gps")),
+            bool(res.get("battery")),
+        ]
+        self.assertTrue(any(populated), f"status had nothing populated: {res}")
+
+
+@unittest.skipUnless(os.path.exists(LOG_PATH), f"log not found: {LOG_PATH}")
+class TestTierCParamReadOffline(unittest.TestCase):
+    """Tier C param READS reuse the read path and work on a log replay."""
+
+    def test_param_get_all_includes_sysid(self):
+        params = _source().param_get_all()
+        self.assertIsInstance(params, dict)
+        self.assertIn("SYSID_THISMAV", params)
+        self.assertIsInstance(params["SYSID_THISMAV"], float)
+
+    def test_param_get_single(self):
+        res = _source().param_get("SYSID_THISMAV")
+        self.assertIsInstance(res, dict)
+        self.assertTrue(res.get("found"))
+        self.assertIsInstance(res.get("value"), float)
+
+    def test_param_get_missing(self):
+        res = _source().param_get("DEFINITELY_NOT_A_REAL_PARAM")
+        self.assertFalse(res.get("found"))
+        self.assertIsNone(res.get("value"))
+
+
+@unittest.skipUnless(os.path.exists(LOG_PATH), f"log not found: {LOG_PATH}")
+class TestTierCParamWriteGate(unittest.TestCase):
+    """The param WRITE gate: closed by default, structured no-op on a file source."""
+
+    def _registered_tools(self, **kwargs):
+        mcp = build_server(LOG_PATH, **kwargs)
+        return {t.name for t in mcp._tool_manager.list_tools()}
+
+    def test_gate_off_by_default_set_returns_disabled(self):
+        # Gate OFF (default): no crash, no write — a clear "disabled" error.
+        mcp = build_server(LOG_PATH)  # read_only=True, allow_param_write=False
+        # The direct source also refuses because a file is not writable.
+        src_res = _source().param_set("INS_HNTCH_FREQ", 80)
+        self.assertFalse(src_res.get("ok"))
+        self.assertIsNone(src_res.get("confirmed"))
+        self.assertIn("reason", src_res)
+        # And the write tools are the disabled variant when the gate is closed.
+        names = {t.name for t in mcp._tool_manager.list_tools()}
+        self.assertIn("param_get", names)
+        self.assertIn("param_get_all", names)
+        # Registered (as disabled stubs) but harmless.
+        self.assertIn("param_set", names)
+
+    def test_gate_off_stub_says_disabled(self):
+        from uav_mavlink_bridge import MavlinkSource as _MS  # noqa: F401
+        mcp = build_server(LOG_PATH, read_only=True, allow_param_write=False)
+        tool = mcp._tool_manager.get_tool("param_set")
+        out = tool.fn(name="INS_HNTCH_FREQ", value=80)
+        self.assertFalse(out.get("ok"))
+        self.assertTrue(out.get("error"))
+        self.assertIn("disabled", out.get("reason", "").lower())
+        self.assertIn("allow-param-write", out.get("reason", ""))
+
+    def test_gate_on_file_source_is_noop_not_crash(self):
+        # Gate ON but the source is a log file: structured no-op, never a crash.
+        mcp = build_server(LOG_PATH, read_only=False, allow_param_write=True)
+        names = {t.name for t in mcp._tool_manager.list_tools()}
+        self.assertIn("param_set", names)
+        self.assertIn("param_set_batch", names)
+        # Direct source call: refuses because a file is not a live vehicle.
+        res = _source().param_set("INS_HNTCH_FREQ", 80)
+        self.assertFalse(res.get("ok"))
+        self.assertIsNone(res.get("confirmed"))
+        self.assertIn("log replay", res.get("reason", ""))
+
+    def test_batch_on_file_source_returns_tagging_shape(self):
+        # Even blocked, the batch result carries the timestamps/shape the
+        # uav-tuning subagent needs to tag a retest.
+        res = _source().param_set_batch({
+            "INS_HNTCH_FREQ": 80,
+            "INS_HNTCH_BW": 40,
+        })
+        self.assertFalse(res.get("ok"))
+        self.assertIn("started_ts", res)
+        self.assertIn("finished_ts", res)
+        self.assertIn("set_params", res)
+        self.assertEqual(res["set_params"], {})
+
+    def test_close_enough(self):
+        self.assertTrue(MavlinkSource._close_enough(80.0, 80.00001))
+        self.assertFalse(MavlinkSource._close_enough(80.0, 81.0))
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)