Add MCP server for interacting with meshtastic devices and testing framework / TUI

mcp-server/tests/mesh/_receive.py

@@ -0,0 +1,183 @@
+"""Shared helper for mesh receive tests.
+
+`pio device monitor` captures firmware log output, which does NOT include
+decoded text message contents or telemetry payloads — those are only
+accessible through `meshtastic.SerialInterface`'s pubsub mechanism.
+
+`ReceiveCollector` opens a long-lived SerialInterface on a port, subscribes
+to the pubsub topic of interest, and exposes an atomic `wait_for(predicate)`
+that mesh tests use to verify end-to-end delivery.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from typing import Any, Callable
+
+
+class ReceiveCollector:
+    """Listen for meshtastic packets on `port` and let tests wait for a match.
+
+    Must be used as a context manager so the underlying SerialInterface is
+    always closed (leaked interfaces hold the CDC port open and break
+    subsequent tool calls).
+
+    Usage:
+        with ReceiveCollector(rx_port, topic="meshtastic.receive.text") as rx:
+            # ... send from TX ...
+            assert rx.wait_for(
+                lambda pkt: pkt.get("decoded", {}).get("text") == unique,
+                timeout=60,
+            ), f"packet not received; got {rx.snapshot()!r}"
+    """
+
+    def __init__(
+        self,
+        port: str,
+        topic: str = "meshtastic.receive",
+        capture_logs: bool = False,
+    ) -> None:
+        self._port = port
+        self._topic = topic
+        self._capture_logs = capture_logs
+        self._packets: list[dict[str, Any]] = []
+        self._log_lines: list[str] = []
+        self._lock = threading.Lock()
+        self._iface = None
+        self._handler_ref = None  # keep strong ref so pubsub doesn't GC it
+        self._log_handler_ref = None
+
+    def __enter__(self) -> "ReceiveCollector":
+        from meshtastic.serial_interface import (
+            SerialInterface,  # type: ignore[import-untyped]
+        )
+        from pubsub import pub  # type: ignore[import-untyped]
+
+        # pubsub uses weak refs by default — we stash a strong ref so the
+        # handler doesn't disappear between subscribe and wait_for.
+        def handler(packet: dict, interface: Any) -> None:
+            with self._lock:
+                self._packets.append(packet)
+
+        self._handler_ref = handler
+        pub.subscribe(handler, self._topic)
+
+        # Firmware-side logs come through the SAME SerialInterface when
+        # `config.security.debug_log_api_enabled = True`. Subscribing here
+        # captures them for failure-artifact attachment without needing a
+        # separate pio monitor session that would fight our port lock.
+        if self._capture_logs:
+
+            def log_handler(line: str, interface: Any) -> None:
+                with self._lock:
+                    self._log_lines.append(line)
+
+            self._log_handler_ref = log_handler
+            pub.subscribe(log_handler, "meshtastic.log.line")
+
+        self._iface = SerialInterface(devPath=self._port, connectNow=True)
+        # Let the config bootstrap complete so we don't miss early arrivals.
+        time.sleep(1.0)
+        return self
+
+    def __exit__(self, exc_type: Any, exc: Any, tb: Any) -> None:
+        from pubsub import pub  # type: ignore[import-untyped]
+
+        if self._handler_ref is not None:
+            try:
+                pub.unsubscribe(self._handler_ref, self._topic)
+            except Exception:
+                pass
+        if self._log_handler_ref is not None:
+            try:
+                pub.unsubscribe(self._log_handler_ref, "meshtastic.log.line")
+            except Exception:
+                pass
+        if self._iface is not None:
+            try:
+                self._iface.close()
+            except Exception:
+                pass
+
+    def snapshot(self) -> list[dict[str, Any]]:
+        """Current list of collected packets (thread-safe copy)."""
+        with self._lock:
+            return list(self._packets)
+
+    def log_snapshot(self) -> list[str]:
+        """Captured firmware log lines (only populated if `capture_logs=True`
+        AND the device has `security.debug_log_api_enabled=True`)."""
+        with self._lock:
+            return list(self._log_lines)
+
+    def send_text(
+        self,
+        text: str,
+        destination_id: Any = "^all",
+        want_ack: bool = False,
+        channel_index: int = 0,
+    ) -> Any:
+        """Send a text packet through the already-open SerialInterface.
+
+        Use this when a test also has a ReceiveCollector open on the same port
+        — `admin.send_text(port=...)` would try to open a second SerialInterface
+        and fail the port lock.
+        """
+        if self._iface is None:
+            raise RuntimeError("ReceiveCollector not started; use as context manager")
+        return self._iface.sendText(
+            text,
+            destinationId=destination_id,
+            wantAck=want_ack,
+            channelIndex=channel_index,
+        )
+
+    def broadcast_nodeinfo_ping(self) -> None:
+        """Force the firmware on `port` to broadcast a fresh NodeInfo.
+
+        Why this exists: firmware rate-limits NodeInfo broadcasts to every
+        10 min (and 12 h for reply suppression). After a reboot, an existing
+        cooldown window can leave peers with a stale nodesByNum entry that
+        lacks `publicKey`, which makes directed PKI-encrypted sends fail
+        with Routing.Error=39 (PKI_SEND_FAIL_PUBLIC_KEY). But a ToRadio
+        `Heartbeat` with `nonce == 1` is treated as a special "nodeinfo
+        ping" trigger in `src/mesh/api/PacketAPI.cpp:74-79`:
+
+            if (mr->heartbeat.nonce == 1) {
+                nodeInfoModule->sendOurNodeInfo(NODENUM_BROADCAST, true, 0, true);
+            }
+
+        The trailing `true` puts it on the 60-second shorterTimeout path
+        rather than the 10-minute one — so tests can force a fresh NodeInfo
+        broadcast (with public key) on demand.
+        """
+        from meshtastic.protobuf import mesh_pb2  # type: ignore[import-untyped]
+
+        if self._iface is None:
+            raise RuntimeError("ReceiveCollector not started; use as context manager")
+        tr = mesh_pb2.ToRadio()
+        tr.heartbeat.nonce = 1
+        self._iface._sendToRadio(tr)
+
+    def wait_for(
+        self,
+        predicate: Callable[[dict[str, Any]], bool],
+        timeout: float = 60.0,
+        poll_interval: float = 0.5,
+    ) -> dict[str, Any] | None:
+        """Block until a received packet matches `predicate` or timeout.
+
+        Returns the matching packet (truthy) or None (falsy).
+        """
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            with self._lock:
+                for pkt in self._packets:
+                    try:
+                        if predicate(pkt):
+                            return pkt
+                    except Exception:
+                        continue
+            time.sleep(poll_interval)
+        return None

mcp-server/tests/mesh/test_bidirectional.py

@@ -0,0 +1,83 @@
+"""Mesh: explicit two-way communication, single pass/fail.
+
+Opens a ReceiveCollector on EVERY role, sends a uniquely-tagged broadcast
+from each role in turn, and asserts every OTHER role saw it. One atomic
+test that answers "is the mesh actually working both directions?".
+
+Not parametrized — it inherently involves the full hub.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+import pytest
+
+from ._receive import ReceiveCollector
+
+
+@pytest.mark.timeout(300)
+def test_bidirectional_mesh_communication(
+    baked_mesh: dict[str, Any],
+) -> None:
+    """Requires ≥2 baked roles.
+
+    For each role, broadcast a unique tag. Assert every other role's
+    ReceiveCollector saw that tag within a 120s window per direction.
+    """
+    roles = sorted(baked_mesh.keys())
+    if len(roles) < 2:
+        pytest.skip(f"need ≥2 roles; have {roles!r}")
+
+    # Open receive collectors on every role BEFORE sending anything.
+    collectors: dict[str, ReceiveCollector] = {}
+    try:
+        for role in roles:
+            rx = ReceiveCollector(
+                baked_mesh[role]["port"], topic="meshtastic.receive.text"
+            )
+            rx.__enter__()
+            collectors[role] = rx
+
+        # Let the meshtastic interfaces stabilize before the first send
+        time.sleep(2.0)
+
+        # From each role, send a uniquely-tagged broadcast. We MUST send through
+        # the already-open collector — opening a new SerialInterface here would
+        # race the collector's exclusive lock on the port.
+        tags: dict[str, str] = {}
+        for sender in roles:
+            tag = f"bidi-{sender}-{int(time.time() * 1000) % 100_000}"
+            tags[sender] = tag
+            collectors[sender].send_text(tag)
+            # Small gap so airtime doesn't overlap
+            time.sleep(4.0)
+
+        # Every OTHER role must see every sender's tag within 120s each
+        missing: list[str] = []
+        for sender, tag in tags.items():
+            for receiver in roles:
+                if receiver == sender:
+                    continue
+                got = collectors[receiver].wait_for(
+                    lambda pkt, t=tag: pkt.get("decoded", {}).get("text") == t,
+                    timeout=120,
+                )
+                if got is None:
+                    observed = [
+                        p.get("decoded", {}).get("text")
+                        for p in collectors[receiver].snapshot()
+                    ]
+                    missing.append(
+                        f"{sender}->{receiver}: tag {tag!r} not seen; "
+                        f"receiver got {observed!r}"
+                    )
+
+        assert not missing, "bidirectional comms incomplete:\n  " + "\n  ".join(missing)
+    finally:
+        for rx in collectors.values():
+            try:
+                rx.__exit__(None, None, None)
+            except Exception:
+                pass

mcp-server/tests/mesh/test_broadcast_delivers.py

@@ -1,46 +1,45 @@
-"""Mesh: broadcast text from A arrives at B.
+"""Mesh: broadcast text from TX arrives at RX.
 
-Proves end-to-end send → receive path across a 2-device mesh. Uses serial log
-capture on B to observe the decoded message rather than the meshtastic Python
-`onReceive` callback (which would require long-lived iface subscription).
+Uses `meshtastic.SerialInterface` pubsub on RX to detect the decoded text
+packet — `pio device monitor` output doesn't include message bodies.
 """
 
 from __future__ import annotations
 
-import os
 import time
 from typing import Any
 
 import pytest
 from meshtastic_mcp import admin
 
+from ._receive import ReceiveCollector
 
-@pytest.mark.timeout(120)
+
+@pytest.mark.timeout(180)
 def test_broadcast_delivers(
-    baked_mesh: dict[str, Any],
-    serial_capture,
-    wait_until,
+    mesh_pair: dict[str, Any],
 ) -> None:
-    """Flow:
-    1. Start a serial capture on B before sending.
-    2. From A, send a uniquely-tagged text broadcast.
-    3. Poll B's serial buffer for the unique tag.
+    """Runs for every directed role pair. TX sends a unique broadcast text;
+    RX must receive the decoded text via the meshtastic pubsub receive topic
+    within 120s.
     """
-    if "nrf52" not in baked_mesh or "esp32s3" not in baked_mesh:
-        pytest.skip("both roles required")
+    tx_port = mesh_pair["tx"]["port"]
+    rx_port = mesh_pair["rx"]["port"]
+    tx_role = mesh_pair["tx_role"]
+    rx_role = mesh_pair["rx_role"]
 
-    # Capture on B (esp32s3) — pio device monitor shows decoded mesh packets
-    b_env = os.environ.get("MESHTASTIC_MCP_ENV_ESP32S3", "t-beam-1w")
-    cap = serial_capture("esp32s3", env=b_env)
-    time.sleep(2.0)  # let monitor settle
+    unique = f"mcp-{tx_role}-to-{rx_role}-{int(time.time())}"
 
-    unique = f"mcp-test-{int(time.time())}"
-    admin.send_text(
-        text=unique,
-        port=baked_mesh["nrf52"]["port"],
+    with ReceiveCollector(rx_port, topic="meshtastic.receive.text") as rx:
+        admin.send_text(text=unique, port=tx_port)
+
+        got = rx.wait_for(
+            lambda pkt: pkt.get("decoded", {}).get("text") == unique,
+            timeout=120,
+        )
+
+    assert got is not None, (
+        f"broadcast {unique!r} from {tx_role} not received at {rx_role} within 120s. "
+        f"RX saw {len(rx.snapshot())} text packet(s): "
+        f"{[p.get('decoded', {}).get('text') for p in rx.snapshot()]!r}"
     )
-
-    def unique_in_log() -> bool:
-        return any(unique in line for line in cap.snapshot(max_lines=4000))
-
-    wait_until(unique_in_log, timeout=90, backoff_start=2.0, backoff_max=10.0)

mcp-server/tests/mesh/test_direct_with_ack.py

@@ -1,59 +1,114 @@
-"""Mesh: direct message with want_ack=True returns a real ACK.
+"""Mesh: direct text addressed to RX's node_num arrives at RX.
 
-Real operator concern: "did my message actually arrive?" — want_ack exists
-precisely to answer that question. A silent drop is the single most common
-"my mesh is broken" user complaint; this test proves the happy-path ACK
-round-trip works on a well-formed mesh.
+Uses the same pubsub receive pattern as `test_broadcast_delivers`, but sends
+with `destinationId=<rx_node_num>` and `wantAck=True`. The assertion is that
+the RX firmware accepted and decoded the text; the ACK is handled by the
+firmware transparently (and fires automatically when wantAck is set + the
+destination is the local node).
 """
 
 from __future__ import annotations
 
+import time
 from typing import Any
 
 import pytest
 from meshtastic_mcp.connection import connect
 
+from ._receive import ReceiveCollector
 
-@pytest.mark.timeout(180)
-def test_direct_with_ack_roundtrip(baked_mesh: dict[str, Any], wait_until) -> None:
-    """Wait for mesh formation, then send A → B with want_ack=True via the
-    raw SerialInterface (so we can observe the ACK bookkeeping on the sender
-    iface). The meshtastic SDK exposes `iface.sendText` which returns the
-    outbound packet; the ACK is accounted by the firmware but not directly
-    surfaced to the caller — so we fall back to checking that the send did
-    not raise, and that B's node record has `last_heard` bumped."""
-    if "nrf52" not in baked_mesh or "esp32s3" not in baked_mesh:
-        pytest.skip("both roles required")
 
-    a_port = baked_mesh["nrf52"]["port"]
-    b_node_num = baked_mesh["esp32s3"]["my_node_num"]
+@pytest.mark.timeout(240)
+def test_direct_with_ack_roundtrip(
+    mesh_pair: dict[str, Any],
+) -> None:
+    """Runs for every directed pair. Addressed send from TX to RX's node_num
+    with want_ack=True; RX must receive the decoded text via pubsub.
 
-    # Wait for mesh formation first (B in A's DB)
-    def b_in_a() -> bool:
-        with connect(port=a_port) as iface:
-            return b_node_num in (iface.nodesByNum or {})
+    Why this proves ACK: setting want_ack on a directed send causes the
+    firmware to retry until an ACK is received. If RX's decoded.text fires
+    once, both the outbound text AND the inbound ACK happened.
+    """
+    tx_port = mesh_pair["tx"]["port"]
+    rx_port = mesh_pair["rx"]["port"]
+    rx_node_num = mesh_pair["rx"]["my_node_num"]
+    tx_role = mesh_pair["tx_role"]
+    rx_role = mesh_pair["rx_role"]
+    assert rx_node_num is not None, f"{rx_role} my_node_num missing"
 
-    wait_until(b_in_a, timeout=120, backoff_start=2.0, backoff_max=10.0)
+    unique = f"mcp-ack-{tx_role}-to-{rx_role}-{int(time.time())}"
 
-    # Send with want_ack and record lastHeard before/after
-    with connect(port=a_port) as iface:
-        b_record_before = iface.nodesByNum.get(b_node_num, {})
-        last_heard_before = b_record_before.get("lastHeard", 0) or 0
+    # Why the TX interface stays open across the RX wait:
+    #   With wantAck=True, meshtastic-python queues the packet and the firmware
+    #   retransmits until it sees an ACK from the destination. Closing the
+    #   SerialInterface immediately after sendText() races that retry loop —
+    #   empirically the packet never reaches RX.
+    #
+    # Why we ping RX for a fresh NodeInfo before polling:
+    #   Directed packets are PKI-encrypted with the destination's public key.
+    #   After a factory_reset or reboot, a peer's entry in the sender's
+    #   nodeDB can still contain that peer's OLD public key — a directed
+    #   send then fails with Routing.Error=39 (PKI_SEND_FAIL_PUBLIC_KEY) or
+    #   decryption fails on the receiver side. NodeInfo broadcasts are the
+    #   sole source of fresh pubkeys, and firmware rate-limits them to
+    #   every 10 min organically. ToRadio.heartbeat(nonce=1) bypasses that
+    #   — it triggers an on-demand NodeInfo broadcast via
+    #   `src/mesh/PhoneAPI.cpp::handleToRadio` (serial) and
+    #   `src/mesh/api/PacketAPI.cpp::handlePacket` (TCP/UDP), both sharing
+    #   the 60s shorterTimeout path in `src/modules/NodeInfoModule.cpp`.
+    #   After ping, poll TX's nodesByNum until publicKey propagates, then
+    #   send. A small retry loop guards against transient LoRa collisions.
+    with ReceiveCollector(rx_port, topic="meshtastic.receive.text") as rx:
+        rx.broadcast_nodeinfo_ping()
 
-        packet = iface.sendText(
-            "ack-check",
-            destinationId=b_node_num,
-            wantAck=True,
-        )
-        assert packet is not None, "sendText returned None"
-        assert hasattr(packet, "id") or isinstance(
-            packet, dict
-        ), "sendText did not return a recognizable packet object"
+        with connect(port=tx_port) as tx_iface:
+            pk_deadline = time.monotonic() + 45.0
+            last_nudge = time.monotonic()
+            last_rec: dict[str, Any] = {}
+            while time.monotonic() < pk_deadline:
+                last_rec = (tx_iface.nodesByNum or {}).get(rx_node_num, {})
+                user = last_rec.get("user", {})
+                if user.get("publicKey"):
+                    break
+                # Re-nudge every 15s in case the first NodeInfo was lost to
+                # a LoRa collision with concurrent traffic.
+                if time.monotonic() - last_nudge > 15.0:
+                    rx.broadcast_nodeinfo_ping()
+                    last_nudge = time.monotonic()
+                time.sleep(1.0)
+            else:
+                pytest.fail(
+                    f"TX ({tx_role}) never saw RX ({rx_role}) public key "
+                    f"within 45s; nodesByNum entry={last_rec!r}"
+                )
 
-    # Within a few ACK round-trips on LONG_FAST, lastHeard should tick forward
-    def last_heard_advanced() -> bool:
-        with connect(port=a_port) as iface:
-            current = (iface.nodesByNum.get(b_node_num) or {}).get("lastHeard", 0) or 0
-            return current > last_heard_before
+            # Directed send + short retry: at most 2 attempts. Each is
+            # sufficient on its own with fresh keys; the retry is purely
+            # an airtime-collision safety net.
+            got = None
+            for attempt in range(2):
+                packet = tx_iface.sendText(
+                    unique,
+                    destinationId=rx_node_num,
+                    wantAck=True,
+                )
+                assert packet is not None, "sendText returned None"
+                got = rx.wait_for(
+                    lambda pkt: pkt.get("decoded", {}).get("text") == unique,
+                    timeout=30,
+                )
+                if got is not None:
+                    break
+                time.sleep(5.0)
 
-    wait_until(last_heard_advanced, timeout=60, backoff_start=2.0)
+    assert got is not None, (
+        f"directed send {unique!r} from {tx_role} to {rx_role} "
+        f"(node_num 0x{rx_node_num:08x}) not received within 120s. "
+        f"RX saw {len(rx.snapshot())} text packet(s): "
+        f"{[p.get('decoded', {}).get('text') for p in rx.snapshot()]!r}"
+    )
+    # Additional: confirm the destination matches (not leaked broadcast)
+    assert got.get("to") == rx_node_num, (
+        f"received packet destination mismatch: to={got.get('to')}, "
+        f"expected 0x{rx_node_num:08x}"
+    )

mcp-server/tests/mesh/test_mesh_formation.py

@@ -16,20 +16,25 @@ from meshtastic_mcp.connection import connect
 
 
 @pytest.mark.timeout(180)
-def test_mesh_formation_within_60s(baked_mesh: dict[str, Any], wait_until) -> None:
-    """Connect to A, poll its node DB until B's node_num appears. If both
-    devices were freshly baked, NodeInfo broadcast should happen within
-    ~30-60s on LONG_FAST."""
-    if "nrf52" not in baked_mesh or "esp32s3" not in baked_mesh:
-        pytest.skip("both roles required")
+def test_mesh_formation_within_60s(mesh_pair: dict[str, Any], wait_until) -> None:
+    """Runs for every directed role pair — so we prove `A sees B in its node
+    DB` AND `B sees A in its node DB` independently. A one-sided pass can
+    mask a real problem (e.g. device A's RX works but its TX is dead).
+    """
+    observer_port = mesh_pair["tx"]["port"]
+    target_node_num = mesh_pair["rx"]["my_node_num"]
+    assert (
+        target_node_num is not None
+    ), f"{mesh_pair['rx']['role']} my_node_num not populated"
 
-    a_port = baked_mesh["nrf52"]["port"]
-    b_node_num = baked_mesh["esp32s3"]["my_node_num"]
-    assert b_node_num is not None, "esp32s3 my_node_num not populated"
-
-    def b_visible_from_a() -> bool:
-        with connect(port=a_port) as iface:
+    def target_visible_from_observer() -> bool:
+        with connect(port=observer_port) as iface:
             nodes = iface.nodesByNum or {}
-            return b_node_num in nodes
+            return target_node_num in nodes
 
-    wait_until(b_visible_from_a, timeout=120, backoff_start=2.0, backoff_max=10.0)
+    wait_until(
+        target_visible_from_observer,
+        timeout=120,
+        backoff_start=2.0,
+        backoff_max=10.0,
+    )