Skip to content

armgit / moss

Public Imported from GitHub
0

MOSS: a small, mostly 3D-printed litter-picking rover. Cleaner streets, one maker at a time.

Python
39.6 KB
Raw Blame
#!/usr/bin/env python3
"""MOSS flight check: every organ the MOSS stack needs, probed read-only, one verdict each.

Runs on the robot, from the root of this checkout, before a stack is launched
(and by `tools/moss-fly.sh check` and the launcher's gate 1):

    .venv/bin/python tools/moss_preflight.py            the whole check (the lidar spins ~5 s)
    .venv/bin/python tools/moss_preflight.py --no-spin  everything but the lidar spin
    .venv/bin/python tools/moss_preflight.py --quick    no lidar spin, no firmware listen
    .venv/bin/python tools/moss_preflight.py --json     one JSON document on stdout instead of lines
    ... --save <file>                                    also write that JSON document to <file>

Sections, in order: stack, ports, firmware, lidar, camera (RealSense), wrist
camera, gamepad, system, software, state dir. One line per probe,
"  OK |KO  label - detail", a summary "N/M OK - ready to fly" or
"N/M OK - KO: a, b", exit 1 on any KO.

Read-only by construction:
- the motor board (QT Py) is opened only when no dimOS stack runs and no other
  process holds it, exactly as tools/moss-teleop.sh gate 3 does: a plain open at
  115200 (DTR asserted, which the firmware needs before it streams), 1.5 s of
  listening, not one byte written. The firmware stays disarmed;
- the lidar is opened under the same conditions; it spins for a few seconds and
  is stopped again (C1Scanner.close sends STOP);
- the RealSense is enumerated, never streamed;
- sudo is only asked whether it would run without a password (`sudo -n true`),
  and only when dimOS would need it at launch (loopback multicast, its route
  or the socket buffers not set yet). It runs nothing as root.
The one thing it may create is the MOSS state dir (and its recordings/).

The MOSS_* on/off switches (MOSS_CAMERA, MOSS_WRIST, MOSS_MOCK_BUS,
MOSS_REQUIRE_PAD) are read the way the stack reads them
(moss_dimos.robot_profile.env_on): unset or empty = the default, 0 / false /
no / off = off, anything else = on. A camera switched off is skipped here, as
the stack skips it.

A check that cannot run because a stack owns the device is reported as skipped
("held by the stack"), never as a failure and never by fighting the stack for
the port: two readers on one serial line corrupt each other's frames.

Every probe is a module-level function so benches/bench_moss_preflight_cold.py
can replace it; nothing runs at import.
"""
from __future__ import annotations

import argparse
import contextlib
import glob
import importlib
import json
import os
import re
import subprocess
import sys
import time
from pathlib import Path

ROOT = Path(__file__).resolve().parent.parent
if str(ROOT) not in sys.path:
    sys.path.insert(0, str(ROOT))

BYID_DIR = "/dev/serial/by-id"
V4L_DIR = "/dev/v4l/by-id"
JS_PATH = "/dev/input/js0"
QTPY_GLOB = "*QT_Py*"
C1_GLOB = "*CP2102N*"
WRIST_GLOBS = ("*KD-USB*-video-index0", "*Sonix*-video-index0")   # known arm cameras first
WRIST_ANY_GLOB = "*-video-index0"                                   # then any other UVC camera...
WRIST_NOT = ("realsense",)                                          # ...except the nose camera
FIRMWARE_BAUD = 115200
LISTEN_S = 1.5              # five telemetry lines at the firmware's 200 ms period
LIDAR_TURNS = 3
LIDAR_MIN_PPS = 200.0       # the C1 gives ~1500 points/s; 200 = a scan that is barely alive
BATTERY_FLOOR_MV = 10800    # launcher floor (moss-teleop.sh gate 3): margin above the cut under load
BMS_CUT_MV = 10200          # the 3S pack's BMS cuts here
DISK_MIN_GB = 5.0
RAM_MIN_KB = 2.5e6
RMEM_TARGET = 67_108_864    # what dimOS's LCM buffer configurator asks for
IFF_MULTICAST = 0x1000
MCAST_PREFIX = "224.0.0.0/4"   # the route dimOS's LCM multicast configurator checks
PAD_SHANWAN = "2563:0526"
PAD_SWITCH_PRO = "057e:2009"
MOSS_BLUEPRINTS = ("moss-nav", "moss-explore", "moss-gamepad")
DISTRIBUTION = "moss-dimos"     # the blueprint namespace: dimos run moss-dimos.<name>
# pyrealsense2 is not here: the camera section checks it, and only when the camera is on.
SOFTWARE_IMPORTS = ("dimos", "kiss_icp", "serial", "numpy", "pygame")
REINSTALL = ("uv pip install --python .venv/bin/python -e . --no-deps"
             " (a venv made with python -m venv: .venv/bin/pip install -e . --no-deps)")
LCM_FIX = ("install tools/lcm-loopback.service to set it at boot (docs/cockpit.md),"
           " or give this user passwordless sudo")

RESULTS: list[dict] = []
_SECTION = [""]
_QUIET = [False]


# ── output ─────────────────────────────────────────────────────────────────
def _say(text: str) -> None:
    if not _QUIET[0]:
        print(text, flush=True)


def section(name: str) -> None:
    _SECTION[0] = name
    _say(name)


def verdict(ok: bool, label: str, detail: str = "") -> None:
    RESULTS.append({"ok": bool(ok), "label": label, "detail": detail, "section": _SECTION[0]})
    _say(f"  {'OK ' if ok else 'KO '} {label}" + (f" - {detail}" if detail else ""))


def skipped(label: str, why: str) -> None:
    """A probe deliberately not run: not a failure, not counted in N/M."""
    RESULTS.append({"ok": True, "skipped": True, "label": label,
                    "detail": f"skipped: {why}", "section": _SECTION[0]})
    _say(f"  --  {label} - skipped: {why}")


# ── probes (each one replaced by the cold bench) ─────────────────────────────
def _ls(pattern: str) -> list[str]:
    return sorted(glob.glob(pattern))


def _exists(path: str) -> bool:
    return os.path.exists(path)


def _read_text(path) -> str | None:
    try:
        return Path(path).read_text(encoding="utf-8")
    except OSError:
        return None


def _pad_name(js: str) -> str:
    try:
        return Path(f"/sys/class/input/{os.path.basename(js)}/device/name").read_text(encoding="utf-8").strip()
    except OSError:
        return os.path.basename(js)


def _pad_init_axes(js: str, listen_s: float = 1.0) -> list[int] | None:
    """The joystick API's initial axis values (events flagged 0x80 on open): a pad the receiver has
    never heard reports every axis at -32767; a live pad at rest reports its sticks at 0."""
    import select
    import struct

    fmt, size = "IhBB", struct.calcsize("IhBB")
    try:
        fd = os.open(js, os.O_RDONLY | os.O_NONBLOCK)
    except OSError:
        return None
    axes: dict[int, int] = {}
    try:
        deadline = time.monotonic() + listen_s
        while time.monotonic() < deadline:
            r, _, _ = select.select([fd], [], [], 0.1)
            if not r:
                if axes:
                    break
                continue
            try:
                data = os.read(fd, size * 64)
            except OSError:
                break
            for i in range(0, len(data) - size + 1, size):
                _, value, typ, num = struct.unpack(fmt, data[i:i + size])
                if typ & 0x80 and typ & 0x02:
                    axes[num] = value
    finally:
        os.close(fd)
    return [axes[k] for k in sorted(axes)]


def _runs_dir() -> Path:
    """dimOS's run registry, where dimOS, tools/moss-fly.sh and the cockpit
    look for it (XDG_STATE_HOME when set and not empty)."""
    return Path(os.environ.get("XDG_STATE_HOME") or Path.home() / ".local/state") / "dimos" / "runs"


def _pid_alive(pid: int) -> bool:
    return pid > 0 and os.path.exists(f"/proc/{pid}")


def _proc_cmdlines() -> list[tuple[int, str]]:
    """(pid, cmdline with NULs as spaces) for every readable process. Each read
    is guarded: a process that exits between listdir and open is normal."""
    out = []
    try:
        pids = os.listdir("/proc")
    except OSError:
        return out
    for pid in pids:
        if not pid.isdigit():
            continue
        try:
            with open(f"/proc/{pid}/cmdline", "rb") as f:
                raw = f.read()
        except OSError:
            continue
        out.append((int(pid), raw.replace(b"\0", b" ").decode(errors="replace").strip()))
    return out


def _port_holders(dev: str) -> list[int]:
    """PIDs with `dev` open, from /proc/*/fd (no sudo: fds of other users'
    processes are unreadable and skipped - every MOSS process runs as us)."""
    real = os.path.realpath(dev)
    me = os.getpid()
    holders = []
    try:
        pids = os.listdir("/proc")
    except OSError:
        return holders
    for pid in pids:
        if not pid.isdigit() or int(pid) == me:
            continue
        try:
            for fd in os.listdir(f"/proc/{pid}/fd"):
                try:
                    if os.readlink(f"/proc/{pid}/fd/{fd}") == real:
                        holders.append(int(pid))
                        break
                except OSError:
                    continue
        except OSError:
            continue
    return holders


def _open_serial(port: str, baud: int):
    """A plain pyserial open, as moss-teleop.sh gate 3: DTR is asserted on open
    (the QT Py's USB CDC only streams to a host holding DTR), and this exact
    open does not reset the board."""
    import serial

    return serial.Serial(port, baud, timeout=0.05)


def _usb_devices() -> set[str]:
    """'vvvv:pppp' of every enumerated USB device, from sysfs (no lsusb needed)."""
    out = set()
    for d in glob.glob("/sys/bus/usb/devices/*"):
        try:
            vid = Path(d, "idVendor").read_text().strip()
            pid = Path(d, "idProduct").read_text().strip()
        except OSError:
            continue
        out.add(f"{vid}:{pid}".lower())
    return out


def _statvfs(path: str):
    return os.statvfs(path)


def _meminfo() -> dict[str, int]:
    info = {}
    with open("/proc/meminfo") as f:
        for line in f:
            k, v = line.split(":", 1)
            info[k] = int(v.split()[0])
    return info


def _sysctl(name: str) -> str | None:
    try:
        return Path("/proc/sys", *name.split(".")).read_text().strip()
    except OSError:
        return None


def _lo_flags() -> int | None:
    try:
        return int(Path("/sys/class/net/lo/flags").read_text().strip(), 16)
    except (OSError, ValueError):
        return None


def _mcast_route() -> bool | None:
    """Whether 224.0.0.0/4 has a route, as dimOS checks it (`ip -o route show`
    prints something). None when `ip` cannot run."""
    try:
        r = subprocess.run(["ip", "-o", "route", "show", MCAST_PREFIX],
                           capture_output=True, text=True, timeout=10)
    except (OSError, subprocess.SubprocessError):
        return None
    return bool(r.stdout.strip()) if r.returncode == 0 else None


def _sudo_ok() -> bool:
    """Whether dimOS could fix the system settings itself at launch: root, or
    sudo without a password. `sudo -n true` never prompts and changes nothing."""
    if os.geteuid() == 0:
        return True
    try:
        return subprocess.run(["sudo", "-n", "true"], stdin=subprocess.DEVNULL,
                              capture_output=True, timeout=10).returncode == 0
    except (OSError, subprocess.SubprocessError):
        return False


def _lidar_probe(port: str) -> dict:
    """Info, health and LIDAR_TURNS turns, then STOP (C1Scanner.close)."""
    from moss_dimos.c1_serial import C1Scanner

    lidar = C1Scanner(port, baudrate=460800, timeout=3)
    try:
        lidar.open()
        info = lidar.info()
        health = lidar.health()
        sectors: set[int] = set()
        n = turns = 0
        t0 = time.monotonic()
        for scan in lidar.scans(min_len=50):
            turns += 1
            for _q, ang, dist in scan:
                if dist > 0:
                    sectors.add(int(ang // 10) % 36)
                    n += 1
            if turns >= LIDAR_TURNS:
                break
        dt = max(time.monotonic() - t0, 1e-6)
        return {"info": info, "health": health, "turns": turns,
                "points_per_s": n / dt, "hz": turns / dt, "sectors": len(sectors)}
    finally:
        lidar.close()


def _realsense_probe() -> list[dict]:
    """Enumeration only (no pipeline, no stream). Raises ImportError without pyrealsense2."""
    import pyrealsense2 as rs

    out = []
    for dev in rs.context().query_devices():
        def info(key, dev=dev):
            try:
                return dev.get_info(getattr(rs.camera_info, key))
            except Exception:  # noqa: BLE001 - a field a device does not report
                return None
        out.append({"name": info("name"), "serial": info("serial_number"),
                    "firmware": info("firmware_version"), "usb": info("usb_type_descriptor")})
    return out


def _import(name: str):
    return importlib.import_module(name)


def _canonical(name: str) -> str:
    """A distribution name as dimOS turns it into a namespace (PEP 503)."""
    return re.sub(r"[-_.]+", "-", name).lower()


def _on_root(entry: str) -> bool:
    try:
        return Path(entry or ".").resolve() == ROOT
    except (OSError, RuntimeError, ValueError):
        return False


def _entry_points(group: str = "dimos.blueprints") -> set[str]:
    """Local names of the blueprints registered by THIS distribution only:
    `dimos run moss-dimos.moss-nav` resolves through the moss-dimos namespace,
    so the same local name registered by another installed package proves
    nothing. Read from the installed distributions, as the stack's dimOS reads
    them: the checkout itself is left out, because the moss_dimos.egg-info an
    editable install leaves there is not on the stack's path."""
    from importlib.metadata import distributions

    path = [p for p in sys.path if not _on_root(p)]
    for dist in distributions(path=path):
        dist_name = dist.metadata.get("Name")
        if dist_name and _canonical(dist_name) == DISTRIBUTION:
            # the first one found is the one Python uses
            return {ep.name for ep in dist.entry_points if ep.group == group}
    return set()


def _module_file() -> str | None:
    """Where `import moss_dimos` lands for the stack: a fresh interpreter of
    this venv, started from this checkout as the launcher starts dimOS, without
    the current directory on sys.path (dimOS runs as a console script, which
    does not add it). None when moss_dimos does not import there."""
    code = ("import sys\n"
            "if sys.path and sys.path[0] == '':\n"
            "    del sys.path[0]\n"
            "import moss_dimos\n"
            "sys.stdout.write(moss_dimos.__file__ or '')\n")
    try:
        r = subprocess.run([sys.executable, "-c", code], cwd=str(ROOT), stdin=subprocess.DEVNULL,
                           capture_output=True, text=True, timeout=60)
    except (OSError, subprocess.SubprocessError):
        return None
    return (r.stdout.strip() or None) if r.returncode == 0 else None


def _robot_profile():
    """The geometry the MOSS stack will fly (MOSS with its MOSS_* overrides)."""
    from moss_dimos import robot_profile

    p = robot_profile.current()
    return p, robot_profile.derived(p)


def _state_dir() -> Path:
    """MOSS_STATE_DIR resolved exactly as the recorder resolves it (absolute)."""
    from moss_dimos import robot_profile

    return robot_profile.moss_state_dir()


# ── robot.env: what the robot IS (driver, pad layout, measured numbers) ──────────────────────
ROBOT_ENV_NAME = "robot.env"


def load_robot_env(text: str) -> dict[str, str]:
    """KEY=VALUE lines (optional `export `, # comments, quotes stripped). Pure: tests/benches."""
    out: dict[str, str] = {}
    for raw in text.splitlines():
        line = raw.strip()
        if not line or line.startswith("#"):
            continue
        if line.startswith("export "):
            line = line[7:].strip()
        if "=" not in line:
            continue
        key, val = line.split("=", 1)
        key, val = key.strip(), val.strip()
        if len(val) >= 2 and val[0] == val[-1] and val[0] in "\"'":
            val = val[1:-1]
        if re.fullmatch(r"[A-Z][A-Z0-9_]*", key):
            out[key] = val
    return out


def apply_robot_env(env: dict | None = None) -> tuple[Path, dict[str, str]]:
    """The launchers source <MOSS_STATE_DIR>/robot.env; the flight check reads the same file so its
    verdicts match what the stack will run with. The shell's own values win (setdefault)."""
    e = os.environ if env is None else env
    path = _state_dir() / ROBOT_ENV_NAME
    text = _read_text(path)
    pairs = load_robot_env(text) if text is not None else {}
    for key, val in pairs.items():
        e.setdefault(key, val)
    return path, pairs


def driver_verdict(expected: str, reported) -> tuple[bool, str]:
    """MOSS_DRIVER (robot.env) against the firmware's `driver` key. Pure.
    No expectation: informative. Expectation and a different (or missing) driver: a KO with the fix."""
    exp = (expected or "").strip().lower()
    rep = (str(reported).strip().lower() if reported else "")
    if not exp:
        return True, (rep or "not reported (a firmware build older than the driver key)") + \
            "; set MOSS_DRIVER in robot.env to make this a check"
    if rep == exp:
        return True, f"{rep} = MOSS_DRIVER"
    if not rep:
        return False, f"not reported, robot.env expects {exp}: reflash the {exp} build (bench/README.md)"
    return False, f"firmware built for {rep}, robot.env expects {exp}: reflash the {exp} build (bench/README.md)"


PAD_MUTE_AXIS = -32767   # the kernel's initial value for an axis the pad never reported


def pad_verdict(name: str, init_axes, layout: str) -> tuple[bool, str]:
    """One pad as SDL will take it: alive at neutral, in the layout the stack will use. Pure.
    init_axes: the joystick API's initial axis values (None = could not read)."""
    lay = (layout or "android").strip().lower() or "android"
    n = (name or "").lower()
    if lay == "auto":
        from moss_dimos.gamepad import layout_for_name
        lay = f"auto -> {layout_for_name(name)}"
    if init_axes is None:
        return False, f"{name}: cannot read it (permissions? held exclusively?)"
    if init_axes and all(int(v) == PAD_MUTE_AXIS for v in init_axes):
        return False, (f"{name}: MUTE - every axis at its never-reported value: the receiver sees no pad "
                       "(pad off, or not paired with this dongle); the stack will never see it at neutral")
    if lay.startswith("auto"):
        return True, f"{name} alive, layout {lay}"
    xbox = ("x-box" in n or "xbox" in n or "x box" in n)
    if xbox and lay != "xinput":
        return False, f"{name}: an Xbox 360 pad to the kernel (the pad on its cable), MOSS_PAD_LAYOUT is {lay}: set MOSS_PAD_LAYOUT=xinput in robot.env"
    if "shanwan" in n and lay == "xinput":
        return False, f"{name}: the dongle in Android mode, MOSS_PAD_LAYOUT is xinput: set MOSS_PAD_LAYOUT=android in robot.env"
    return True, f"{name} alive, layout {lay}"


# ── helpers ────────────────────────────────────────────────────────────────
def _env_on(name: str, default: bool) -> bool:
    """A MOSS_* switch, parsed by the stack's own parser."""
    from moss_dimos import robot_profile

    return robot_profile.env_on(name, default)


def _raw(name: str) -> str:
    """A switch's value as written, for the messages."""
    return os.environ.get(name, "").strip()


def _first(patterns) -> str | None:
    for pat in patterns:
        hits = _ls(pat)
        if hits:
            return hits[0]
    return None


def _nearest_existing(path: Path) -> Path:
    p = path
    while not p.exists() and p != p.parent:
        p = p.parent
    return p


def _is_dimos_run(cmdline: str) -> bool:
    """`<venv>/bin/dimos [root options] run <blueprint>`: root options such as
    `--rerun-open none` sit BETWEEN `dimos` and `run`, so a plain substring
    'bin/dimos run' never matches a real launch."""
    toks = cmdline.split()
    for i, t in enumerate(toks):
        if t.endswith("bin/dimos"):
            return "run" in toks[i + 1:]
    return False


# ── checks ─────────────────────────────────────────────────────────────────
def check_stack(ctx: dict) -> None:
    """A running stack owns the board and the lidar: the probes that would open
    them are skipped, and the launcher's own gate 0 refuses a second stack."""
    section("stack (dimOS)")
    me = os.getpid()
    cmdlines = dict(_proc_cmdlines())
    live, stale = None, 0
    for f in sorted(_runs_dir().glob("*.json")):
        try:
            entry = json.loads(f.read_text())
            pid = int(entry.get("pid", 0))
        except (OSError, ValueError, TypeError):
            stale += 1
            continue
        # A registry file outlives a reboot and its pid can be reused by any
        # process: only a live pid that IS a `dimos ... run` makes a stack.
        if _pid_alive(pid) and _is_dimos_run(cmdlines.get(pid, "")):
            live = (entry.get("run_id") or f.stem, pid)
        else:
            stale += 1
    procs = [(pid, cmd) for pid, cmd in cmdlines.items() if pid != me and _is_dimos_run(cmd)]
    note = f" ({stale} stale registry entr{'y' if stale == 1 else 'ies'})" if stale else ""
    if live:
        ctx["stack"] = f"run {live[0]} pid {live[1]}"
        verdict(True, "stack", f"{live[0]} pid {live[1]}{note}")
    elif procs:
        ctx["stack"] = f"unregistered dimos run pid {procs[0][0]}"
        verdict(True, "stack", f"unregistered dimos run pid {procs[0][0]} (a zombie? moss-fly.sh gate 0 sweeps it){note}")
    else:
        ctx["stack"] = None
        verdict(True, "stack", f"none{note}")


def _resolve(env_name: str, pattern: str) -> tuple[str | None, str]:
    """The path the stack will open: the env override when set, else the by-id glob."""
    env = os.environ.get(env_name)
    if env:
        return env, f"{env_name}"
    hits = _ls(os.path.join(BYID_DIR, pattern))
    return (hits[0] if hits else None), f"by-id {pattern}"


def check_ports(ctx: dict) -> None:
    section("ports (by-id)")
    ctx["qtpy"] = ctx["c1"] = None
    for key, label, env_name, pattern, missing in (
            ("qtpy", "motor board (QT Py)", "MOSS_PORT", QTPY_GLOB,
             "not on USB - cable, power, or the board sits in its bootloader (by-id 'Espressif')"),
            ("c1", "lidar (RPLidar C1 on CP2102N)", "MOSS_LIDAR_PORT", C1_GLOB,
             "not on USB - lidar cable or hub")):
        if key == "qtpy" and _env_on("MOSS_MOCK_BUS", False):
            verdict(True, label, f"MOSS_MOCK_BUS={_raw('MOSS_MOCK_BUS')}: fake firmware, the board is not needed")
            continue
        path, how = _resolve(env_name, pattern)
        if not path or not _exists(path):
            verdict(False, label, f"{path or pattern} {missing}")
            continue
        holders = [] if ctx.get("stack") else _port_holders(path)
        if holders:
            verdict(False, f"{label} free", f"held by pid {', '.join(map(str, holders))} - stop that process first")
            continue
        ctx[key] = path
        verdict(True, label, f"{os.path.basename(path)} ({how})"
                + (" - in use by the stack" if ctx.get("stack") else ", free"))
    # On MOSS /dev/ttyUSB0 IS the lidar: a MOSS_PORT naming it (or the CP2102N
    # by-id path) would send motor commands into the lidar.
    if ctx["qtpy"] and ctx["c1"] and os.path.realpath(ctx["qtpy"]) == os.path.realpath(ctx["c1"]):
        verdict(False, "motor port is not the lidar", f"MOSS_PORT and the lidar are both {os.path.realpath(ctx['c1'])}"
                " - unset MOSS_PORT (the QT Py by-id is found on its own)")
        ctx["qtpy"] = None


def _battery(t: dict) -> None:
    mv = t.get("bus_mV")
    if t.get("ina_ok") is not True or mv is None:
        verdict(False, "battery", "INA219 not seen (ina_ok false, no bus_mV) - check its STEMMA cable")
        return
    v = int(mv) / 1000.0
    if mv >= BATTERY_FLOOR_MV:
        verdict(True, "battery", f"{v:.2f} V")
    elif mv >= BMS_CUT_MV:
        verdict(False, "battery", f"{v:.2f} V - under 10.8 V: the BMS cuts at 10.2 V under load, charge first")
    else:
        verdict(False, "battery", f"{v:.2f} V - under the BMS cut (10.2 V): charge before anything")


def check_firmware(ctx: dict, quick: bool) -> None:
    section("firmware (QT Py, listen only)")
    if _env_on("MOSS_MOCK_BUS", False):
        skipped("firmware telemetry", f"MOSS_MOCK_BUS={_raw('MOSS_MOCK_BUS')} (fake firmware)")
        return
    if ctx.get("stack"):
        skipped("firmware telemetry", f"held by the stack ({ctx['stack']})")
        return
    if quick:
        skipped("firmware telemetry", "--quick")
        return
    port = ctx.get("qtpy")
    if not port:
        skipped("firmware telemetry", "no free QT Py port (see ports)")
        return
    try:
        ser = _open_serial(port, FIRMWARE_BAUD)
    except Exception as exc:  # noqa: BLE001
        verdict(False, "firmware telemetry", f"cannot open {port}: {exc!r} - dialout group? another process?")
        return
    last, n, buf = None, 0, b""
    try:
        with contextlib.suppress(Exception):
            ser.reset_input_buffer()     # a partial line from before the open
        deadline = time.monotonic() + LISTEN_S
        while time.monotonic() < deadline:
            buf += ser.read(4096) or b""
            while b"\n" in buf:
                line, buf = buf.split(b"\n", 1)
                line = line.strip()
                if not line.startswith(b"{"):
                    continue
                try:
                    doc = json.loads(line)
                except ValueError:
                    continue
                if isinstance(doc, dict):
                    last, n = doc, n + 1
    finally:
        with contextlib.suppress(Exception):
            ser.close()
    if last is None:
        verdict(False, "firmware telemetry", f"mute for {LISTEN_S:.1f} s - power-cycle the board, or reflash it")
        return
    verdict(True, "firmware telemetry", f"{n} line(s) in {LISTEN_S:.1f} s")
    fw = last.get("fw")
    verdict(isinstance(fw, str) and bool(fw), "firmware version", str(fw) if fw else "no 'fw' key - a build older than v3?")
    mode = last.get("mode")
    verdict(mode == 0, "firmware disarmed",
            "mode 0 (off)" if mode == 0 else f"mode {mode} ({last.get('reason')}) - something else is driving it")
    ok, detail = driver_verdict(_raw("MOSS_DRIVER"), last.get("driver"))
    verdict(ok, "motor driver", detail)
    _battery(last)
    ticks = last.get("ticks")
    good = isinstance(ticks, list) and len(ticks) == 2 and all(isinstance(x, int) for x in ticks)
    verdict(good, "encoder ticks", f"L {ticks[0]} R {ticks[1]}" if good else f"missing or malformed: {ticks!r}")


def check_lidar(ctx: dict, spin: bool) -> None:
    section("lidar (RPLidar C1, ~5 s spin)")
    if ctx.get("stack"):
        skipped("lidar scan", f"held by the stack ({ctx['stack']})")
        return
    if not spin:
        skipped("lidar scan", "--quick/--no-spin")
        return
    port = ctx.get("c1")
    if not port:
        skipped("lidar scan", "no free lidar port (see ports)")
        return
    try:
        r = _lidar_probe(port)
    except Exception as exc:  # noqa: BLE001
        verdict(False, "lidar answers", f"{type(exc).__name__}: {exc} - unplug/replug the lidar cable, then rerun")
        return
    info = r.get("info") or {}
    verdict(True, "lidar answers", f"model {info.get('model')} serial {info.get('serial')}")
    status, code = (r.get("health") or ("?", -1))
    verdict(status == "Good", "lidar health", f"{status} ({code})")
    pps, sectors = float(r.get("points_per_s", 0.0)), int(r.get("sectors", 0))
    verdict(pps > LIDAR_MIN_PPS and sectors == 36, "lidar scan",
            f"{r.get('turns')} turns, {pps:.0f} points/s, {sectors}/36 sectors seen"
            + ("" if sectors == 36 else " - something sits in the scan plane, or the spin is weak"))


def check_realsense(ctx: dict) -> None:
    section("camera (RealSense, enumeration only)")
    if not _env_on("MOSS_CAMERA", True):
        skipped("RealSense", f"MOSS_CAMERA={_raw('MOSS_CAMERA')}: this flight builds no RealSense")
        return
    wanted = os.environ.get("MOSS_RS_SERIAL") or None
    try:
        devices = _realsense_probe()
    except ImportError as exc:
        verdict(False, "RealSense", f"pyrealsense2 not importable: {exc} - install it (Software.md),"
                " or fly without the camera: MOSS_CAMERA=0")
        return
    except Exception as exc:  # noqa: BLE001
        verdict(False, "RealSense", f"enumeration failed: {exc}")
        return
    d455 = [d for d in devices if "D455" in str(d.get("name") or "")
            and (wanted is None or d.get("serial") == wanted)]
    if not d455:
        seen = ", ".join(f"{d.get('name')} {d.get('serial')}" for d in devices) or "nothing"
        verdict(False, "RealSense D455", f"no D455{' with serial ' + wanted if wanted else ''} (seen: {seen})"
                " - plug it on USB 3, or fly without the camera: MOSS_CAMERA=0")
        return
    d = d455[0]
    usb = str(d.get("usb") or "")
    desc = f"{d.get('name')} serial {d.get('serial')} fw {d.get('firmware')} USB {usb or '?'}"
    if usb.startswith("3"):
        verdict(True, "RealSense D455", desc)
    elif usb.startswith("2"):
        verdict(False, "RealSense D455", f"{desc} - on USB 2: 5 fps max, replug on a USB 3 port/cable")
    else:
        verdict(False, "RealSense D455", f"{desc} - unknown USB link")


def check_wrist(ctx: dict) -> None:
    section("wrist camera (UVC)")
    if not _env_on("MOSS_WRIST", True):
        skipped("wrist camera", f"MOSS_WRIST={_raw('MOSS_WRIST')}: this flight builds no wrist camera")
        return
    path = _first(os.path.join(V4L_DIR, g) for g in WRIST_GLOBS)
    if path is None:
        others = [h for h in _ls(os.path.join(V4L_DIR, WRIST_ANY_GLOB))
                  if not any(x in os.path.basename(h).lower() for x in WRIST_NOT)]
        path = others[0] if others else None
    # The stack skips a missing wrist camera with a warning (no wrist_image):
    # its absence is a warning here too, not a refusal.
    verdict(True, "wrist camera", path or f"WARN not seen (no {' or '.join(WRIST_GLOBS)} and no other "
            f"{WRIST_ANY_GLOB} besides the RealSense under {V4L_DIR}); the stack runs without wrist_image")


def check_gamepad(ctx: dict) -> None:
    section("gamepad")
    pads = _ls("/dev/input/js*")   # any number: the pad on its cable keeps js1 after the dongle's js0
    if pads:
        try:
            index = max(0, int(_raw("MOSS_PAD_INDEX") or "0"))
        except ValueError:
            index = 0
        js = pads[index] if index < len(pads) else pads[0]
        name = _pad_name(js)
        ok, detail = pad_verdict(name, _pad_init_axes(js), _raw("MOSS_PAD_LAYOUT"))
        others = [f"{os.path.basename(j)}={_pad_name(j)}" for j in pads if j != js]
        verdict(ok, "gamepad", f"{os.path.basename(js)}: {detail}" + (f"; also plugged: {', '.join(others)}" if others else ""))
        return
    usb = _usb_devices()
    if PAD_SHANWAN in usb:
        why = f"receiver visible ({PAD_SHANWAN}), no js device: replug or reboot"
    elif PAD_SWITCH_PRO in usb:
        why = (f"pad enumerated as a Nintendo Pro Controller ({PAD_SWITCH_PRO}) without a driver: "
               "switch the pad to its Android/X-input mode and replug")
    else:
        why = "no pad (no js device, no known receiver on USB)"
    # A missing pad stops nothing from running: the map builds, the cockpit shows, exploration
    # can be armed; only hand driving is lost. MOSS_REQUIRE_PAD=1 turns this into a refusal.
    required = _env_on("MOSS_REQUIRE_PAD", False)
    verdict(not required, "gamepad", ("" if required else "WARN nothing drives by hand in moss-nav; ") + why)


def check_system(ctx: dict) -> None:
    section("system")
    try:
        where = _nearest_existing(_state_dir())
        st = _statvfs(str(where))
        free_gb = st.f_bavail * st.f_frsize / 1e9
        verdict(free_gb > DISK_MIN_GB, "disk for recordings", f"{free_gb:.1f} GB free on {where}")
    except Exception as exc:  # noqa: BLE001 - an unresolvable state dir, a failed statvfs
        verdict(False, "disk for recordings", f"{type(exc).__name__}: {exc}")
    try:
        avail = _meminfo().get("MemAvailable", 0)
        verdict(avail > RAM_MIN_KB, "RAM available", f"{avail / 1e6:.1f} GB")
    except (OSError, ValueError) as exc:
        verdict(False, "RAM available", str(exc))
    rmem = _sysctl("net.core.rmem_max")
    try:
        r = int(rmem) if rmem is not None else None
    except ValueError:
        r = None
    flags = _lo_flags()
    lo_on = flags is not None and bool(flags & IFF_MULTICAST)
    route = _mcast_route()
    # dimOS sets what is missing with sudo at every launch, and its multicast
    # setting is critical: a launch that cannot run sudo dies on it. The
    # launcher starts dimOS in the background (and the cockpit page has no
    # terminal at all), so only passwordless sudo, or the boot unit, works.
    needs_fix = not lo_on or not route or (r is not None and r < RMEM_TARGET)
    sudo = _sudo_ok() if needs_fix else True
    if r is None:
        verdict(True, "socket buffers", "net.core.rmem_max unreadable (warning only)")
    elif r >= RMEM_TARGET:
        verdict(True, "socket buffers", f"rmem_max {r}")
    elif sudo:
        verdict(True, "socket buffers", f"warning: rmem_max {r} < {RMEM_TARGET} - dimOS raises it with sudo at launch")
    else:
        verdict(True, "socket buffers", f"warning: rmem_max {r} < {RMEM_TARGET} and no passwordless sudo:"
                f" LCM runs with small buffers - {LCM_FIX}")
    if lo_on:
        verdict(True, "loopback multicast", "on")
    elif sudo:
        verdict(True, "loopback multicast", "off - dimOS turns it on with sudo at launch")
    else:
        verdict(False, "loopback multicast", f"off, and no passwordless sudo here: dimOS cannot turn it on at launch"
                f" - {LCM_FIX}")
    if route is None:
        verdict(False, "multicast route", "cannot run `ip` (iproute2): dimOS needs it to check and set LCM multicast")
    elif route:
        verdict(True, "multicast route", f"{MCAST_PREFIX} routed")
    elif sudo:
        verdict(True, "multicast route", f"no {MCAST_PREFIX} route - dimOS adds it on lo with sudo at launch")
    else:
        verdict(False, "multicast route", f"no {MCAST_PREFIX} route, and no passwordless sudo here: dimOS cannot"
                f" add it at launch - {LCM_FIX}")


def check_software(ctx: dict) -> None:
    section("software")
    # pygame prints a banner on import unless told not to (as moss_dimos/gamepad.py does)
    os.environ.setdefault("PYGAME_HIDE_SUPPORT_PROMPT", "1")
    for name in SOFTWARE_IMPORTS:
        try:
            mod = _import(name)
            verdict(True, f"import {name}", str(getattr(mod, "__version__", "") or ""))
        except Exception as exc:  # noqa: BLE001
            verdict(False, f"import {name}", f"{type(exc).__name__}: {exc}")
    try:
        names = _entry_points()
    except Exception as exc:  # noqa: BLE001
        names = set()
        verdict(False, "blueprint entry points", f"cannot read: {exc}")
    for bp in MOSS_BLUEPRINTS:
        verdict(bp in names, f"blueprint {bp}",
                f"registered as {DISTRIBUTION}.{bp}" if bp in names
                else f"missing from {DISTRIBUTION} - reinstall in {ROOT}: {REINSTALL}")
    try:
        src = _module_file()
    except Exception:  # noqa: BLE001 - reported as not importable
        src = None
    if src is None:
        verdict(False, "moss-dimos install", f"moss_dimos does not import in this venv ({sys.executable})"
                f" - install it in {ROOT}: {REINSTALL}")
    elif Path(src).resolve().is_relative_to(ROOT):
        verdict(True, "moss-dimos install", "the stack imports moss_dimos from this checkout")
    else:
        verdict(False, "moss-dimos install", f"the stack would import moss_dimos from {Path(src).resolve().parent},"
                f" not from this checkout - reinstall in {ROOT}: {REINSTALL}")
    try:
        p, d = _robot_profile()
        name = getattr(p, "name", None)
        lethal = d.get("lethal_clearance_m") if isinstance(d, dict) else getattr(d, "lethal_clearance_m", None)
        verdict(True, "robot profile",
                f"{name}: width {p.robot_width_m} m, pivot {p.pivot_diameter_m} m, "
                f"lidar {p.lidar_height_m} m up, lethal {lethal:.2f} m (placeholders until measured)")
    except Exception as exc:  # noqa: BLE001
        verdict(False, "robot profile", f"{type(exc).__name__}: {exc}")


def check_state_dir(ctx: dict) -> None:
    section("state dir")
    try:
        d = _state_dir()
        (d / "recordings").mkdir(parents=True, exist_ok=True)
        ok = os.access(d / "recordings", os.W_OK)
        verdict(ok, "MOSS state dir", f"{d} (recordings/ {'writable' if ok else 'NOT writable'})")
    except Exception as exc:  # noqa: BLE001 - unresolvable or unwritable
        verdict(False, "MOSS state dir", f"{os.environ.get('MOSS_STATE_DIR') or '~/.local/state/moss'}: {exc}")


# ── main ───────────────────────────────────────────────────────────────────
def document(flags: dict) -> dict:
    counted = [r for r in RESULTS if not r.get("skipped")]
    ko = [r["label"] for r in counted if not r["ok"]]
    n_ok = len(counted) - len(ko)
    summary = f"{n_ok}/{len(counted)} OK" + (f" - KO: {', '.join(ko)}" if ko else " - ready to fly")
    return {"ts": time.time(), "checks": list(RESULTS), "ok_count": n_ok, "ko_count": len(ko),
            "skipped_count": len(RESULTS) - len(counted), "summary": summary, "flags": flags}


def _save(path: str, doc: dict) -> None:
    p = Path(os.path.expanduser(path))
    p.parent.mkdir(parents=True, exist_ok=True)
    tmp = p.with_name(p.name + ".tmp")
    tmp.write_text(json.dumps(doc, indent=1))
    os.replace(tmp, p)   # the cockpit never reads half a document


def run(quick: bool = False, no_spin: bool = False) -> None:
    ctx: dict = {}
    section("robot.env (what the robot is: driver, pad layout, measured numbers)")
    env_path, pairs = apply_robot_env()
    verdict(True, "robot.env", (f"{env_path}: " + ", ".join(f"{k}={v}" for k, v in pairs.items())) if pairs
            else f"{env_path} absent: nothing declared (MOSS_DRIVER, MOSS_PAD_LAYOUT...) - the checks stay informative")
    check_stack(ctx)
    check_ports(ctx)
    check_firmware(ctx, quick)
    check_lidar(ctx, spin=not (quick or no_spin))
    check_realsense(ctx)
    check_wrist(ctx)
    check_gamepad(ctx)
    check_system(ctx)
    check_software(ctx)
    check_state_dir(ctx)


def main(argv: list[str] | None = None) -> int:
    ap = argparse.ArgumentParser(description="MOSS flight check (read-only)")
    ap.add_argument("--json", action="store_true", help="print one JSON document instead of lines")
    ap.add_argument("--quick", action="store_true", help="skip the lidar spin and the firmware listen")
    ap.add_argument("--no-spin", action="store_true", help="skip only the lidar spin")
    ap.add_argument("--save", metavar="FILE", help="also write the JSON document to FILE (atomically)")
    a = ap.parse_args(argv)
    RESULTS.clear()
    _QUIET[0] = a.json
    flags = {"quick": a.quick, "no_spin": a.no_spin or a.quick}
    if a.json:
        # imports (dimos above all) may print: keep stdout for the document only
        with contextlib.redirect_stdout(sys.stderr):
            run(a.quick, a.no_spin)
    else:
        run(a.quick, a.no_spin)
    doc = document(flags)
    if a.save:
        try:
            _save(a.save, doc)
        except OSError as exc:
            print(f"(could not save {a.save}: {exc})", file=sys.stderr)
    if a.json:
        print(json.dumps(doc, indent=1))
    else:
        print(f"\n{doc['summary']}" + (f" ({doc['skipped_count']} skipped)" if doc["skipped_count"] else ""))
    return 1 if doc["ko_count"] else 0


if __name__ == "__main__":
    raise SystemExit(main())