yarbo-local 0.1.0.dev0__py3-none-any.whl

yarbo_local/__init__.py

@@ -0,0 +1,93 @@
+"""Local-first library and tooling for Yarbo robots over their LAN MQTT broker.
+
+The library talks to the anonymous broker on the robot and to nothing else.
+``YarboRobot`` is the entry point; ``Session`` is the protocol layer under it;
+``Simulator`` stands in for a robot when there is none on the bench.
+"""
+
+from __future__ import annotations
+
+from .blackbox import FlightRecorder
+from .client import YarboRobot
+from .exceptions import (
+    CommandError,
+    CommandRefusedError,
+    ConnectionLostError,
+    ControllerError,
+    PlanStartError,
+    PreflightError,
+    ReplyTimeoutError,
+    RobotNotFoundError,
+    YarboError,
+)
+from .feedback import AreaProgress, BarrierPoints, PlanFeedback, RechargeFeedback
+from .lifecycle import EventKind, FinishReason, LifecycleEvent, Phase, PlanTracker
+from .models import (
+    Activity,
+    ChargingPoint,
+    Fault,
+    Feedback,
+    GgaFix,
+    GpsReference,
+    PlanError,
+    PlanSummary,
+    RobotState,
+    SiteMap,
+    Zone,
+)
+from .obstacles import Barrier, ObstacleTracker, Run
+from .preflight import Action, Refusal
+from .registry import Command, Registry
+from .resolve import resolve
+from .session import Session
+from .simulator import Simulator
+from .transport import FakeBroker, FakeTransport, MqttTransport
+
+__version__ = "0.1.0.dev0"
+
+__all__ = [
+    "Action",
+    "Activity",
+    "AreaProgress",
+    "Barrier",
+    "BarrierPoints",
+    "ChargingPoint",
+    "Command",
+    "CommandError",
+    "CommandRefusedError",
+    "ConnectionLostError",
+    "ControllerError",
+    "EventKind",
+    "FakeBroker",
+    "FakeTransport",
+    "Fault",
+    "Feedback",
+    "FinishReason",
+    "FlightRecorder",
+    "GgaFix",
+    "GpsReference",
+    "LifecycleEvent",
+    "MqttTransport",
+    "ObstacleTracker",
+    "Phase",
+    "PlanError",
+    "PlanFeedback",
+    "PlanStartError",
+    "PlanSummary",
+    "PlanTracker",
+    "PreflightError",
+    "RechargeFeedback",
+    "Refusal",
+    "Registry",
+    "ReplyTimeoutError",
+    "RobotNotFoundError",
+    "RobotState",
+    "Run",
+    "Session",
+    "Simulator",
+    "SiteMap",
+    "YarboError",
+    "YarboRobot",
+    "Zone",
+    "resolve",
+]

yarbo_local/blackbox.py

@@ -0,0 +1,110 @@
+"""A flight recorder: the last few minutes of traffic, kept in memory, redacted on the way out.
+
+A report that says "it stopped" cannot be acted on; one that carries what the robot and the
+app said in the minutes before can. This keeps that, bounded in count and age, and costs
+nothing until someone asks for it. Nothing is written to disk and nothing leaves the process.
+
+What is kept: every command the app or we sent, every reply, the feedback topics thinned to
+one in ``THIN_EVERY`` seconds, and a state frame only when one of the fields that tell the
+story changed (with the frame before it, so the change can be read). Map blobs and paths are
+cut to their size: the site's shape is not needed to debug a protocol exchange.
+"""
+
+from __future__ import annotations
+
+from collections import deque
+from collections.abc import Callable
+from typing import Any
+
+from . import codec
+from .redact import Redactor
+from .session import MessageEvent, Session
+
+MAX_RECORDS = 600
+MAX_AGE_S = 900.0
+THIN_EVERY = 10.0
+BIG = 2000  # characters; anything longer is a map, a path or a blob
+
+STORY_KEYS = (
+    "StateMSG.on_going_planning",
+    "StateMSG.planning_paused",
+    "StateMSG.on_going_recharging",
+    "StateMSG.error_code",
+    "StateMSG.plan_msg",
+    "StateMSG.car_controller",
+    "StateMSG.machine_controller",
+    "StateMSG.charging_status",
+    "BatteryMSG.status",
+    "HeadMsg.head_type",
+    "RTKMSG.status",
+)
+QUIET_APP = frozenset({"cmd_vel", "cmd_roller"})  # joystick streams; forbidden and noisy
+
+
+def _cut(value: Any) -> Any:
+    """Replace anything large with its size, keeping the shape of the message."""
+    if isinstance(value, dict):
+        return {k: _cut(v) for k, v in value.items()}
+    if isinstance(value, list):
+        return f"<{len(value)} items>" if len(value) > 20 else [_cut(v) for v in value]
+    if isinstance(value, str) and len(value) > BIG:
+        return f"<{len(value)} chars>"
+    return value
+
+
+class FlightRecorder:
+    """Attach to a session; ``dump()`` returns the recent past, redacted."""
+
+    def __init__(self, *, max_records: int = MAX_RECORDS, max_age: float = MAX_AGE_S) -> None:
+        self._records: deque[dict[str, Any]] = deque(maxlen=max_records)
+        self._max_age = max_age
+        self._story: tuple[Any, ...] | None = None
+        self._held: dict[str, Any] | None = None  # the latest state frame not yet recorded
+        self._last_thin: dict[str, float] = {}
+        self._serials: set[str] = set()
+
+    def attach(self, session: Session) -> Callable[[], None]:
+        return session.add_message_listener(self.on_message)
+
+    def note(self, at: float, what: str, **detail: Any) -> None:
+        """Something the consumer knows and the wire does not: a refusal, a reconnect."""
+        self._records.append({"t": round(at, 3), "note": what, **detail})
+
+    def on_message(self, event: MessageEvent) -> None:
+        self._serials.add(event.serial)
+        if event.side == "app" and event.leaf in QUIET_APP:
+            return
+        record = {
+            "t": round(event.at, 3),
+            "from": "us" if event.echo else event.side,
+            "leaf": event.leaf,
+            "value": _cut(event.value),
+        }
+        if event.side == "device" and event.leaf == "DeviceMSG" and isinstance(event.value, dict):
+            flat = codec.flatten(event.value)
+            story = tuple(flat.get(key) for key in STORY_KEYS)
+            record["value"] = dict(zip(STORY_KEYS, story, strict=True))
+            if story == self._story:
+                self._held = record
+                return
+            if self._held is not None:
+                self._records.append(self._held)
+            self._story, self._held = story, None
+        elif event.side == "device" and event.leaf != "data_feedback":
+            last = self._last_thin.get(event.leaf)
+            if last is not None and event.at - last < THIN_EVERY:
+                return
+            self._last_thin[event.leaf] = event.at
+        self._records.append(record)
+        while self._records and event.at - self._records[0]["t"] > self._max_age:
+            self._records.popleft()
+
+    def dump(self) -> list[dict[str, Any]]:
+        """The recent past, oldest first, with serials, positions and identifiers redacted."""
+        redactor = Redactor()
+        for serial in self._serials:
+            redactor.register_serial(serial)
+        records = list(self._records)
+        if self._held is not None:
+            records.append(self._held)
+        return [redactor.redact_value(record) for record in sorted(records, key=lambda r: r["t"])]

yarbo_local/capture.py

@@ -0,0 +1,140 @@
+"""Sniffer: subscribe to the robot's broker and write everything to JSONL.
+
+One record per message::
+
+    {"t": 1757260000.123, "ts": "2026-09-07T14:26:40.123Z",
+     "topic": "snowbot/SN/device/DeviceMSG", "bytes": 2310, "enc": "zlib",
+     "payload": {...}}
+
+Both sides of the conversation are captured (``snowbot/+/#``) so that
+commands published by the phone app are recorded next to the robot's replies.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections import Counter
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+import json
+from pathlib import Path
+import secrets
+import sys
+import time
+from typing import Any, TextIO
+
+import aiomqtt
+
+from . import codec, topics
+from .redact import Redactor
+
+
+@dataclass
+class CaptureStats:
+    """Running counters printed at the end of a capture."""
+
+    started: float = field(default_factory=time.monotonic)
+    messages: int = 0
+    bytes_total: int = 0
+    per_topic: Counter[str] = field(default_factory=Counter)
+    encodings: Counter[str] = field(default_factory=Counter)
+    serials: set[str] = field(default_factory=set)
+    first_seen: dict[str, float] = field(default_factory=dict)
+    last_seen: dict[str, float] = field(default_factory=dict)
+
+    def note(self, topic: str, size: int, enc: str, now: float) -> None:
+        self.messages += 1
+        self.bytes_total += size
+        self.per_topic[topic] += 1
+        self.encodings[enc] += 1
+        self.first_seen.setdefault(topic, now)
+        self.last_seen[topic] = now
+        parsed = topics.parse(topic)
+        if parsed:
+            self.serials.add(parsed.serial)
+
+    def render(self) -> str:
+        elapsed = max(time.monotonic() - self.started, 1e-6)
+        lines = [
+            (
+                f"messages={self.messages} bytes={self.bytes_total} elapsed={elapsed:.1f}s "
+                f"encodings={dict(self.encodings)} serials={sorted(self.serials) or '-'}"
+            ),
+            f"{'topic':60} {'count':>7} {'rate/s':>8} {'span s':>8}",
+        ]
+        for topic, count in self.per_topic.most_common():
+            span = self.last_seen[topic] - self.first_seen[topic]
+            rate = count / span if span > 0 else 0.0
+            lines.append(f"{topic:60} {count:7d} {rate:8.2f} {span:8.1f}")
+        return "\n".join(lines)
+
+
+def build_record(
+    topic: str, raw: bytes, redactor: Redactor | None, *, at: float | None = None
+) -> dict[str, Any]:
+    """One JSONL record for a raw message, redacted when a redactor is given."""
+    now = time.time() if at is None else at
+    payload, enc = codec.decode(raw)
+    if redactor is not None:
+        parsed = topics.parse(topic)
+        if parsed:
+            redactor.register_serial(parsed.serial)
+        topic = redactor.redact_topic(topic)
+        payload = redactor.redact_value(payload)
+    return {
+        "t": round(now, 3),
+        "ts": datetime.fromtimestamp(now, tz=UTC).isoformat(timespec="milliseconds"),
+        "topic": topic,
+        "bytes": len(raw),
+        "enc": enc,
+        "payload": payload,
+    }
+
+
+async def sniff(
+    host: str,
+    port: int = 1883,
+    *,
+    out: Path | None = None,
+    duration: float | None = None,
+    topic_filter: str | None = None,
+    redact: bool = False,
+    echo: TextIO | None = None,
+    stats_every: float = 15.0,
+) -> CaptureStats:
+    """Capture until ``duration`` seconds elapse or the process is interrupted."""
+    stats = CaptureStats()
+    redactor = Redactor() if redact else None
+    sub = topic_filter or topics.all_for(None)
+    log = echo or sys.stderr
+    fh = out.open("a", encoding="utf-8") if out else None
+    identifier = f"yarbo-local-sniff-{secrets.token_hex(3)}"
+
+    async def _run() -> None:
+        async with aiomqtt.Client(host, port=port, identifier=identifier) as client:
+            await client.subscribe(sub)
+            print(f"connected to {host}:{port}, subscribed {sub}", file=log)
+            next_stats = time.monotonic() + stats_every
+            async for message in client.messages:
+                raw = message.payload if isinstance(message.payload, bytes) else b""
+                rec = build_record(message.topic.value, raw, redactor)
+                stats.note(message.topic.value, rec["bytes"], rec["enc"], time.monotonic())
+                if fh:
+                    fh.write(json.dumps(rec, separators=(",", ":")) + "\n")
+                    fh.flush()
+                if stats_every and time.monotonic() >= next_stats:
+                    print(stats.render(), file=log)
+                    next_stats = time.monotonic() + stats_every
+
+    try:
+        if duration:
+            async with asyncio.timeout(duration):
+                await _run()
+        else:
+            await _run()
+    except TimeoutError:
+        pass
+    finally:
+        if fh:
+            fh.close()
+    return stats

yarbo_local/cli.py

@@ -0,0 +1,264 @@
+"""Command line: ``yarbo-local sniff|probe|discover|dump|status|sim|studio|sitecheck``."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+from pathlib import Path
+import sys
+
+from . import (
+    __version__,
+    capture,
+    discover,
+    dump,
+    probe,
+    redact,
+    simulator,
+    sitecheck,
+    status,
+)
+from .exceptions import YarboError
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="yarbo-local",
+        description="Phase 0 tooling for the Yarbo local MQTT protocol. LAN only, no cloud.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    p = sub.add_parser("sniff", help="capture every topic from a broker to JSONL")
+    p.add_argument("host")
+    p.add_argument("--port", type=int, default=1883)
+    p.add_argument("--out", type=Path, help="JSONL file to append to")
+    p.add_argument("--duration", type=float, help="stop after N seconds (default: until Ctrl-C)")
+    p.add_argument("--filter", help="MQTT subscription filter (default: snowbot/+/#)")
+    p.add_argument("--redact", action="store_true", help="redact serial, MAC, IP, coordinates")
+    p.add_argument("--stats-every", type=float, default=15.0)
+    p.add_argument(
+        "--fallback-scan",
+        metavar="CIDR",
+        help="if the host does not answer, scan this subnet for a broker and use the first hit",
+    )
+
+    p = sub.add_parser("probe", help="send one allowlisted command and show what comes back")
+    p.add_argument("host")
+    p.add_argument("command", choices=sorted(probe.PHASE0_COMMANDS))
+    p.add_argument("--serial", help="robot serial (learned from traffic when omitted)")
+    p.add_argument("--port", type=int, default=1883)
+    p.add_argument("--payload", help="JSON object overriding the default payload")
+    p.add_argument("--encoding", choices=["auto", "zlib", "json"], default="auto")
+    p.add_argument(
+        "--settle",
+        type=float,
+        default=6.0,
+        help="seconds to observe before sending; asleep heartbeats arrive every ~5 s",
+    )
+    p.add_argument("--timeout", type=float, default=8.0, help="seconds to collect after sending")
+    p.add_argument("--out", type=Path, help="append the whole probe window to this JSONL")
+    p.add_argument(
+        "--fallback-scan",
+        metavar="CIDR",
+        help="if the host does not answer, scan this subnet for a broker with this serial",
+    )
+
+    p = sub.add_parser("discover", help="scan hosts or a CIDR for brokers carrying snowbot traffic")
+    p.add_argument("hosts", help="host, comma list, or CIDR such as 192.168.40.0/24")
+    p.add_argument("--port", type=int, default=1883)
+    p.add_argument("--wait", type=float, default=6.0, help="seconds to listen per open host")
+    p.add_argument("--connect-timeout", type=float, default=0.6)
+
+    p = sub.add_parser("redact", help="re-redact an existing JSONL capture into a fixture")
+    p.add_argument("src", type=Path)
+    p.add_argument("dst", type=Path)
+    p.add_argument("--salt", help="shared salt so several files from one robot get the same tokens")
+
+    p = sub.add_parser("status", help="connect through the library and print the robot state")
+    p.add_argument("host")
+    p.add_argument("--serial", help="robot serial (learned from traffic when omitted)")
+    p.add_argument("--port", type=int, default=1883)
+    p.add_argument("--tls", action="store_true", help="use the TLS listener (usually 8883)")
+    p.add_argument("--wake", action="store_true", help="send the wake command first")
+    p.add_argument("--watch", type=float, default=0.0, help="print state changes for N seconds")
+    p.add_argument(
+        "--fallback-scan",
+        metavar="CIDR",
+        help="if the host does not answer, scan this subnet for a broker with this serial",
+    )
+
+    p = sub.add_parser("sim", help="serve a simulated robot from a fixture on an MQTT broker")
+    p.add_argument("fixture", type=Path, help="a get_device_msg fixture, see protocol/fixtures")
+    p.add_argument("--broker", default="127.0.0.1")
+    p.add_argument("--port", type=int, default=1883)
+    p.add_argument("--rate", type=float, default=1.0, help="DeviceMSG frames per second awake")
+
+    p = sub.add_parser(
+        "studio", help="local web UI: live stream, knowledge diff, fixtures, command console"
+    )
+    p.add_argument("host")
+    p.add_argument("--serial", help="robot serial (learned from traffic when omitted)")
+    p.add_argument("--port", type=int, default=1883)
+    p.add_argument("--ui-host", default="127.0.0.1", help="bind address for the web UI")
+    p.add_argument("--ui-port", type=int, default=8765)
+    p.add_argument(
+        "--protocol-dir",
+        type=Path,
+        help="a checkout's protocol/ directory to write fixtures and field semantics into",
+    )
+    p.add_argument("--no-open", action="store_true", help="do not open a browser")
+    p.add_argument(
+        "--fallback-scan",
+        metavar="CIDR",
+        help="if the host does not answer, scan this subnet for a broker with this serial",
+    )
+
+    p = sub.add_parser(
+        "sitecheck",
+        help="check a site with one or several robots and write a report that is safe to share",
+    )
+    p.add_argument("hosts", help="a subnet such as 192.168.50.0/24, an IP, or a comma list")
+    p.add_argument("--port", type=int, default=1883)
+    p.add_argument("--window", type=float, default=12.0, help="seconds to listen to each broker")
+    p.add_argument("--out", type=Path, default=Path(), help="directory for the report and log")
+
+    p = sub.add_parser("dump", help="summarise a JSONL capture")
+    p.add_argument("file", type=Path)
+    p.add_argument("--keys", action="store_true", help="print the DeviceMSG key inventory")
+    p.add_argument("--app", action="store_true", help="print app-side commands observed")
+    return parser
+
+
+def _resolve_host(host: str, port: int, fallback: str | None, serial: str | None) -> str:
+    """Return ``host`` if its broker port answers, else the first scan hit (matching serial)."""
+    if not fallback:
+        return host
+    if asyncio.run(discover.tcp_open(host, port, 1.5)):
+        return host
+    print(f"{host}:{port} not answering; scanning {fallback}", file=sys.stderr)
+    hits = asyncio.run(
+        discover.discover(
+            discover.expand(fallback), port=port, wait=6.0, heartbeat_only=True, names=False
+        )
+    )
+    for hit in hits:
+        if hit.serials and (serial is None or serial in hit.serials):
+            print(f"using {hit.host} ({hit.serials})", file=sys.stderr)
+            return hit.host
+    raise RuntimeError(f"no broker found on {fallback}")
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _build_parser().parse_args(argv)
+    try:
+        if getattr(args, "fallback_scan", None):
+            args.host = _resolve_host(
+                args.host, args.port, args.fallback_scan, getattr(args, "serial", None)
+            )
+        if args.cmd == "sniff":
+            stats = asyncio.run(
+                capture.sniff(
+                    args.host,
+                    args.port,
+                    out=args.out,
+                    duration=args.duration,
+                    topic_filter=args.filter,
+                    redact=args.redact,
+                    stats_every=args.stats_every,
+                )
+            )
+            print(stats.render(), file=sys.stderr)
+        elif args.cmd == "probe":
+            payload = json.loads(args.payload) if args.payload else None
+            result = asyncio.run(
+                probe.probe(
+                    args.host,
+                    args.command,
+                    serial=args.serial,
+                    port=args.port,
+                    payload=payload,
+                    encoding=args.encoding,
+                    settle=args.settle,
+                    timeout=args.timeout,
+                    out=args.out,
+                )
+            )
+            print(result.render())
+        elif args.cmd == "discover":
+            hits = asyncio.run(
+                discover.discover(
+                    discover.expand(args.hosts),
+                    port=args.port,
+                    wait=args.wait,
+                    connect_timeout=args.connect_timeout,
+                )
+            )
+            if not hits:
+                print("no hosts with an open MQTT port")
+            for hit in hits:
+                print(hit.render())
+        elif args.cmd == "redact":
+            count = redact.redact_file(args.src, args.dst, salt=args.salt)
+            print(f"wrote {count} records to {args.dst}", file=sys.stderr)
+        elif args.cmd == "status":
+            return asyncio.run(
+                status.show(
+                    args.host,
+                    port=args.port,
+                    tls=args.tls,
+                    serial=args.serial,
+                    wake=args.wake,
+                    watch=args.watch,
+                )
+            )
+        elif args.cmd == "sim":
+            sim = simulator.Simulator.from_fixture(args.fixture)
+            print(
+                f"simulating {sim.serial} firmware {sim.firmware} on {args.broker}:{args.port}",
+                file=sys.stderr,
+            )
+            asyncio.run(simulator.run_on_broker(sim, args.broker, args.port, rate=args.rate))
+        elif args.cmd == "studio":
+            try:
+                from .studio.server import serve  # noqa: PLC0415 - optional extra
+            except ImportError:
+                print(
+                    "the Studio needs aiohttp: pip install 'yarbo-local[studio]'", file=sys.stderr
+                )
+                return 1
+            asyncio.run(
+                serve(
+                    args.host,
+                    robot_port=args.port,
+                    serial=args.serial,
+                    ui_host=args.ui_host,
+                    ui_port=args.ui_port,
+                    protocol_dir=args.protocol_dir,
+                    open_browser=not args.no_open,
+                )
+            )
+        elif args.cmd == "sitecheck":
+            survey, findings = sitecheck.run(
+                args.hosts, port=args.port, window=args.window, out_dir=args.out
+            )
+            for finding in findings:
+                print(survey.labels.scrub(finding.render()), end="\n\n")
+            print(
+                f"report: {args.out / 'sitecheck-report.md'}\nlog:    {args.out / 'sitecheck.log'}"
+            )
+            print("Both files use labels in place of serials and addresses, and hold no position.")
+            return 0 if all(f.ok for f in findings) else 1
+        elif args.cmd == "dump":
+            print(dump.summarise(args.file).render(keys=args.keys, app=args.app))
+    except KeyboardInterrupt:
+        return 130
+    except (ValueError, RuntimeError, OSError, YarboError) as err:
+        print(f"error: {err}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())