Add USB camera and uhubctl support for new test suite. Also included some bug fixes (#10204)
* Add USB camera and uhubctl support for new test suite. Also added some bug fixes * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * Refactor test messages for clarity and consistency in regex tests --------- Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
This commit is contained in:
Ben Meadors
co-authored by
GitHub
Copilot Autofix powered by AI
GitHub
Copilot Autofix powered by AI
parent
6b15571e14
commit
de23e5199d
@@ -356,6 +356,46 @@ def shutdown(
|
||||
return {"ok": True, "shutting_down_in_s": seconds}
|
||||
|
||||
|
||||
def send_input_event(
|
||||
event_code: int | str,
|
||||
kb_char: int = 0,
|
||||
touch_x: int = 0,
|
||||
touch_y: int = 0,
|
||||
port: str | None = None,
|
||||
) -> dict[str, Any]:
|
||||
"""Inject an InputBroker event (button press / key / gesture) into the UI.
|
||||
|
||||
Wraps `AdminMessage.send_input_event` (handled in firmware at
|
||||
src/modules/AdminModule.cpp::handleSendInputEvent). Local-only — no PKI
|
||||
warmup needed since the admin message is addressed to `my_node_num`.
|
||||
|
||||
`event_code` accepts an int, a case-insensitive name
|
||||
(`"RIGHT"` / `"input_broker_right"`), or an `InputEventCode`. The
|
||||
firmware-side enum lives in src/input/InputBroker.h and is mirrored in
|
||||
`meshtastic_mcp.input_events`.
|
||||
"""
|
||||
from meshtastic.protobuf import admin_pb2 # type: ignore[import-untyped]
|
||||
|
||||
from .input_events import coerce_event_code
|
||||
|
||||
code = coerce_event_code(event_code)
|
||||
if not 0 <= kb_char <= 255:
|
||||
raise ValueError(f"kb_char out of u8 range: {kb_char}")
|
||||
if not 0 <= touch_x <= 65535:
|
||||
raise ValueError(f"touch_x out of u16 range: {touch_x}")
|
||||
if not 0 <= touch_y <= 65535:
|
||||
raise ValueError(f"touch_y out of u16 range: {touch_y}")
|
||||
|
||||
with connect(port=port) as iface:
|
||||
msg = admin_pb2.AdminMessage()
|
||||
msg.send_input_event.event_code = code
|
||||
msg.send_input_event.kb_char = kb_char
|
||||
msg.send_input_event.touch_x = touch_x
|
||||
msg.send_input_event.touch_y = touch_y
|
||||
iface.localNode._sendAdmin(msg)
|
||||
return {"ok": True, "event_code": code, "kb_char": kb_char}
|
||||
|
||||
|
||||
def factory_reset(
|
||||
port: str | None = None, confirm: bool = False, full: bool = False
|
||||
) -> dict[str, Any]:
|
||||
|
||||
@@ -0,0 +1,286 @@
|
||||
"""Cross-platform USB-webcam capture for UI tests + the `capture_screen` tool.
|
||||
|
||||
Backends:
|
||||
- `opencv` — cv2.VideoCapture (AVFoundation on macOS, V4L2 on Linux).
|
||||
- `ffmpeg` — subprocess shelling out to the system `ffmpeg` binary. Slower
|
||||
per frame, but zero Python deps beyond stdlib.
|
||||
- `null` — no-op stub returning a 1×1 black PNG. Used when no camera is
|
||||
configured; keeps code paths alive without forcing every operator to
|
||||
hook up hardware.
|
||||
|
||||
Environment variables (read at `get_camera()` call time):
|
||||
- `MESHTASTIC_UI_CAMERA_BACKEND` — one of `opencv` / `ffmpeg` / `null` /
|
||||
`auto` (default). `auto` picks opencv if `cv2` imports, else ffmpeg if
|
||||
`ffmpeg --version` resolves, else null.
|
||||
- `MESHTASTIC_UI_CAMERA_DEVICE` — generic default (index or path).
|
||||
- `MESHTASTIC_UI_CAMERA_DEVICE_<ROLE>` — per-role override, e.g.
|
||||
`MESHTASTIC_UI_CAMERA_DEVICE_ESP32S3=0` for the OLED-bearing heltec-v3.
|
||||
Role suffix is uppercased before lookup.
|
||||
|
||||
Dependencies land in the optional `[ui]` extra; imports are lazy so clients
|
||||
without `opencv-python-headless` installed can still import this module.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import io
|
||||
import os
|
||||
import shutil
|
||||
import subprocess
|
||||
import sys
|
||||
import time
|
||||
import warnings
|
||||
from pathlib import Path
|
||||
from typing import Protocol
|
||||
|
||||
|
||||
class CameraError(RuntimeError):
|
||||
"""Raised when a camera backend fails to initialize or capture."""
|
||||
|
||||
|
||||
class CameraBackend(Protocol):
|
||||
name: str
|
||||
|
||||
def capture(self) -> bytes:
|
||||
"""Return one PNG-encoded frame."""
|
||||
...
|
||||
|
||||
def close(self) -> None: ...
|
||||
|
||||
|
||||
# ---------- OpenCV backend -------------------------------------------------
|
||||
|
||||
|
||||
class OpenCVBackend:
|
||||
name = "opencv"
|
||||
|
||||
def __init__(self, device: int | str, warmup_frames: int = 5) -> None:
|
||||
try:
|
||||
import cv2 # type: ignore[import-untyped] # noqa: PLC0415
|
||||
except ImportError as exc:
|
||||
raise CameraError(
|
||||
"opencv backend requested but `cv2` is not installed. "
|
||||
"Install the mcp-server [ui] extra: pip install -e '.[ui]'"
|
||||
) from exc
|
||||
|
||||
self._cv2 = cv2
|
||||
device_arg: int | str
|
||||
if isinstance(device, str) and device.isdigit():
|
||||
device_arg = int(device)
|
||||
else:
|
||||
device_arg = device
|
||||
self._cap = cv2.VideoCapture(device_arg)
|
||||
if not self._cap.isOpened():
|
||||
raise CameraError(
|
||||
f"cv2.VideoCapture({device_arg!r}) failed to open. "
|
||||
"On macOS check TCC Camera permission; on Linux check /dev/video* and v4l2 access."
|
||||
)
|
||||
|
||||
# Drop the first few frames — auto-exposure + white-balance settle.
|
||||
for _ in range(warmup_frames):
|
||||
self._cap.read()
|
||||
# Detect a stuck black-frame camera early rather than silently
|
||||
# producing all-black captures.
|
||||
ok, frame = self._cap.read()
|
||||
if not ok or frame is None:
|
||||
self._cap.release()
|
||||
raise CameraError(f"camera {device_arg!r} opened but returned no frames")
|
||||
|
||||
def capture(self) -> bytes:
|
||||
cv2 = self._cv2
|
||||
ok, frame = self._cap.read()
|
||||
if not ok or frame is None:
|
||||
raise CameraError("cv2.VideoCapture.read() returned no frame")
|
||||
success, buf = cv2.imencode(".png", frame)
|
||||
if not success:
|
||||
raise CameraError("cv2.imencode('.png', ...) failed")
|
||||
return bytes(buf)
|
||||
|
||||
def close(self) -> None:
|
||||
try:
|
||||
self._cap.release()
|
||||
except Exception: # noqa: BLE001
|
||||
pass
|
||||
|
||||
|
||||
# ---------- ffmpeg subprocess backend --------------------------------------
|
||||
|
||||
|
||||
class FfmpegBackend:
|
||||
name = "ffmpeg"
|
||||
|
||||
def __init__(self, device: int | str) -> None:
|
||||
if shutil.which("ffmpeg") is None:
|
||||
raise CameraError("ffmpeg backend requested but `ffmpeg` is not on PATH")
|
||||
|
||||
self._device = str(device)
|
||||
# Platform-specific -f flag:
|
||||
# macOS → avfoundation (index like "0")
|
||||
# Linux → v4l2 (device like "/dev/video0" or "0")
|
||||
if sys.platform == "darwin":
|
||||
self._input_format = "avfoundation"
|
||||
self._input_spec = self._device # bare index for avfoundation
|
||||
else:
|
||||
self._input_format = "v4l2"
|
||||
self._input_spec = (
|
||||
self._device
|
||||
if self._device.startswith("/dev/")
|
||||
else f"/dev/video{self._device}"
|
||||
)
|
||||
|
||||
def capture(self) -> bytes:
|
||||
cmd = [
|
||||
"ffmpeg",
|
||||
"-hide_banner",
|
||||
"-loglevel",
|
||||
"error",
|
||||
"-f",
|
||||
self._input_format,
|
||||
"-i",
|
||||
self._input_spec,
|
||||
"-frames:v",
|
||||
"1",
|
||||
"-f",
|
||||
"image2pipe",
|
||||
"-vcodec",
|
||||
"png",
|
||||
"-",
|
||||
]
|
||||
try:
|
||||
out = subprocess.run(
|
||||
cmd, capture_output=True, check=True, timeout=15 # noqa: S603
|
||||
)
|
||||
except subprocess.CalledProcessError as exc:
|
||||
raise CameraError(
|
||||
f"ffmpeg capture failed (rc={exc.returncode}): {exc.stderr.decode(errors='replace')[:200]}"
|
||||
) from exc
|
||||
except subprocess.TimeoutExpired as exc:
|
||||
raise CameraError("ffmpeg capture timed out after 15s") from exc
|
||||
return out.stdout
|
||||
|
||||
def close(self) -> None:
|
||||
pass # stateless — each capture spawns a new process
|
||||
|
||||
|
||||
# ---------- Null backend ---------------------------------------------------
|
||||
|
||||
|
||||
# A tiny valid 1×1 transparent PNG so callers always get a decodable image.
|
||||
_BLACK_1X1_PNG = bytes.fromhex(
|
||||
"89504e470d0a1a0a0000000d49484452000000010000000108060000001f15c489"
|
||||
"0000000d49444154789c6300010000000500010d0a2db40000000049454e44ae426082"
|
||||
)
|
||||
|
||||
|
||||
class NullBackend:
|
||||
name = "null"
|
||||
|
||||
def capture(self) -> bytes:
|
||||
return _BLACK_1X1_PNG
|
||||
|
||||
def close(self) -> None:
|
||||
pass
|
||||
|
||||
|
||||
# ---------- Factory --------------------------------------------------------
|
||||
|
||||
|
||||
def _resolve_device(role: str | None) -> str | None:
|
||||
if role:
|
||||
specific = os.environ.get(f"MESHTASTIC_UI_CAMERA_DEVICE_{role.upper()}")
|
||||
if specific:
|
||||
return specific
|
||||
return os.environ.get("MESHTASTIC_UI_CAMERA_DEVICE")
|
||||
|
||||
|
||||
def get_camera(role: str | None = None) -> CameraBackend:
|
||||
"""Return a CameraBackend for the given device role (e.g. `"esp32s3"`).
|
||||
|
||||
Falls back to `NullBackend` if no camera is configured or the selected
|
||||
backend fails to init — tests should treat captures as best-effort
|
||||
evidence, not a blocker.
|
||||
"""
|
||||
backend = os.environ.get("MESHTASTIC_UI_CAMERA_BACKEND", "auto").lower()
|
||||
device = _resolve_device(role)
|
||||
|
||||
if backend in ("null", "none") or device is None:
|
||||
return NullBackend()
|
||||
|
||||
if backend == "auto":
|
||||
# Prefer opencv if importable; fall back to ffmpeg; else null.
|
||||
try:
|
||||
import cv2 # type: ignore[import-untyped] # noqa: F401,PLC0415
|
||||
|
||||
backend = "opencv"
|
||||
except ImportError:
|
||||
backend = "ffmpeg" if shutil.which("ffmpeg") else "null"
|
||||
|
||||
if backend == "opencv":
|
||||
try:
|
||||
return OpenCVBackend(device)
|
||||
except CameraError as exc:
|
||||
warnings.warn(
|
||||
f"camera backend {backend!r} failed to initialize for device "
|
||||
f"{device!r}: {exc}; falling back to null backend",
|
||||
RuntimeWarning,
|
||||
stacklevel=2,
|
||||
)
|
||||
return NullBackend()
|
||||
if backend == "ffmpeg":
|
||||
try:
|
||||
return FfmpegBackend(device)
|
||||
except CameraError as exc:
|
||||
warnings.warn(
|
||||
f"camera backend {backend!r} failed to initialize for device "
|
||||
f"{device!r}: {exc}; falling back to null backend",
|
||||
RuntimeWarning,
|
||||
stacklevel=2,
|
||||
)
|
||||
return NullBackend()
|
||||
if backend == "null":
|
||||
return NullBackend()
|
||||
|
||||
raise CameraError(f"unknown MESHTASTIC_UI_CAMERA_BACKEND: {backend!r}")
|
||||
|
||||
|
||||
def save_capture(png_bytes: bytes, path: Path) -> None:
|
||||
path.parent.mkdir(parents=True, exist_ok=True)
|
||||
path.write_bytes(png_bytes)
|
||||
|
||||
|
||||
def capture_to_file(role: str | None, path: Path) -> dict[str, object]:
|
||||
"""One-shot: open camera, capture, write PNG, close. Returns metadata."""
|
||||
started = time.monotonic()
|
||||
cam = get_camera(role)
|
||||
try:
|
||||
data = cam.capture()
|
||||
finally:
|
||||
cam.close()
|
||||
save_capture(data, path)
|
||||
return {
|
||||
"backend": cam.name,
|
||||
"path": str(path),
|
||||
"bytes": len(data),
|
||||
"elapsed_s": round(time.monotonic() - started, 3),
|
||||
}
|
||||
|
||||
|
||||
def _is_png(data: bytes) -> bool:
|
||||
return data.startswith(b"\x89PNG\r\n\x1a\n")
|
||||
|
||||
|
||||
# Exposed so callers can sanity-check a capture without a full PIL import.
|
||||
__all__ = [
|
||||
"CameraBackend",
|
||||
"CameraError",
|
||||
"FfmpegBackend",
|
||||
"NullBackend",
|
||||
"OpenCVBackend",
|
||||
"capture_to_file",
|
||||
"get_camera",
|
||||
"save_capture",
|
||||
]
|
||||
|
||||
# Keep `io` import used (pyflakes is picky) via a small guard used at import
|
||||
# time to normalize stdin/stdout if a subclass ever needs it.
|
||||
_ = io.BytesIO # noqa: SLF001
|
||||
@@ -0,0 +1,83 @@
|
||||
"""UI-capture transcript tailer for ``meshtastic-mcp-test-tui``.
|
||||
|
||||
Watches ``tests/ui_captures/<session_seed>/`` for new transcript lines
|
||||
(one per ``frame_capture()`` call from the UI tier) and posts them to
|
||||
the TUI. Enabled by ``MESHTASTIC_UI_TUI_CAMERA=1``.
|
||||
|
||||
Design mirrors ``_flashlog.py``:
|
||||
- Daemon thread, cooperative stop via ``threading.Event``.
|
||||
- Tolerates the captures directory not existing yet (UI tier hasn't run).
|
||||
- Per-file seek state so we only forward genuinely-new lines.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import pathlib
|
||||
import threading
|
||||
import time
|
||||
from typing import Callable
|
||||
|
||||
|
||||
class UiCaptureTailer(threading.Thread):
|
||||
"""Recursively watch a captures root for new `transcript.md` lines.
|
||||
|
||||
Invokes ``post(test_id, line)`` for each new line, where ``test_id``
|
||||
is derived from the path — the sanitized nodeid directory name.
|
||||
"""
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
root: pathlib.Path,
|
||||
post: Callable[[str, str], None],
|
||||
stop: threading.Event,
|
||||
*,
|
||||
poll_interval: float = 0.5,
|
||||
) -> None:
|
||||
super().__init__(daemon=True, name="uicap-tail")
|
||||
self._root = root
|
||||
self._post = post
|
||||
self._stop = stop
|
||||
self._poll_interval = poll_interval
|
||||
# path → byte offset we've already read through
|
||||
self._offsets: dict[pathlib.Path, int] = {}
|
||||
|
||||
def run(self) -> None:
|
||||
while not self._stop.is_set():
|
||||
try:
|
||||
self._scan_once()
|
||||
except Exception:
|
||||
# Best-effort tailer — never bring down the TUI because a
|
||||
# directory vanished mid-scan.
|
||||
pass
|
||||
time.sleep(self._poll_interval)
|
||||
|
||||
def _scan_once(self) -> None:
|
||||
if not self._root.is_dir():
|
||||
return
|
||||
for transcript in self._root.rglob("transcript.md"):
|
||||
test_id = transcript.parent.name
|
||||
offset = self._offsets.get(transcript, 0)
|
||||
try:
|
||||
size = transcript.stat().st_size
|
||||
except OSError:
|
||||
continue
|
||||
if size < offset:
|
||||
# File truncated / rewritten — reset and re-emit.
|
||||
offset = 0
|
||||
if size == offset:
|
||||
continue
|
||||
try:
|
||||
with transcript.open("rb") as fh:
|
||||
fh.seek(offset)
|
||||
chunk = fh.read(size - offset).decode("utf-8", errors="replace")
|
||||
except OSError:
|
||||
continue
|
||||
for line in chunk.splitlines():
|
||||
line = line.rstrip()
|
||||
if not line or line.startswith("#"):
|
||||
continue
|
||||
try:
|
||||
self._post(test_id, line)
|
||||
except Exception:
|
||||
return
|
||||
self._offsets[transcript] = size
|
||||
@@ -518,6 +518,7 @@ def _build_app(
|
||||
from . import _fwlog as _fwlog_mod
|
||||
from . import _history as _history_mod
|
||||
from . import _reproducer as _reproducer_mod
|
||||
from . import _uicap as _uicap_mod
|
||||
|
||||
# ---------------- Messages ----------------
|
||||
|
||||
@@ -548,6 +549,16 @@ def _build_app(
|
||||
self.line = line
|
||||
super().__init__()
|
||||
|
||||
class UiCaptureLine(tx.Message):
|
||||
"""Live line from the UI-tier camera transcript — one per
|
||||
`frame_capture()` call. Posted only when the camera panel is
|
||||
enabled via `MESHTASTIC_UI_TUI_CAMERA=1`."""
|
||||
|
||||
def __init__(self, test_id: str, line: str) -> None:
|
||||
self.test_id = test_id
|
||||
self.line = line
|
||||
super().__init__()
|
||||
|
||||
class DeviceSnapshot(tx.Message):
|
||||
def __init__(self, rows: list[DeviceRow]) -> None:
|
||||
self.rows = rows
|
||||
@@ -871,6 +882,10 @@ def _build_app(
|
||||
#pytest-pane { height: 50%; border-bottom: solid $primary-background; }
|
||||
#fwlog-header { height: 1; padding: 0 1; background: $panel; }
|
||||
#fwlog-pane { height: 1fr; }
|
||||
#uicap-header { height: 1; padding: 0 1; background: $boost; }
|
||||
#uicap-pane { height: 14; border-top: solid $primary-background; }
|
||||
#uicap-image { width: 36; border-right: solid $primary-background; padding: 0 1; }
|
||||
#uicap-log { width: 1fr; height: 14; }
|
||||
Tree { height: 100%; }
|
||||
RichLog { height: 100%; }
|
||||
#device-table { height: auto; max-height: 6; }
|
||||
@@ -912,6 +927,11 @@ def _build_app(
|
||||
self._device_worker: DevicePollerWorker | None = None
|
||||
self._fwlog_worker: _fwlog_mod.FirmwareLogTailer | None = None
|
||||
self._flashlog_worker: _flashlog_mod.FlashLogTailer | None = None
|
||||
self._uicap_worker: _uicap_mod.UiCaptureTailer | None = None
|
||||
# Env-gated; only mounts the UI-capture panel when operator asks for it.
|
||||
self._ui_camera_enabled = bool(
|
||||
int(os.environ.get("MESHTASTIC_UI_TUI_CAMERA", "0") or "0")
|
||||
)
|
||||
self._tree_filter: str = ""
|
||||
self._sigint_count = 0
|
||||
# Firmware-log port filter: None = all, else exact port match.
|
||||
@@ -959,6 +979,22 @@ def _build_app(
|
||||
wrap=True,
|
||||
max_lines=5000,
|
||||
)
|
||||
if self._ui_camera_enabled:
|
||||
yield tx.Static(
|
||||
"UI camera — latest capture + transcript (MESHTASTIC_UI_TUI_CAMERA=1)",
|
||||
id="uicap-header",
|
||||
)
|
||||
with tx.Horizontal(id="uicap-pane"):
|
||||
yield tx.Static(
|
||||
"(waiting…)", id="uicap-image", markup=False
|
||||
)
|
||||
yield tx.RichLog(
|
||||
id="uicap-log",
|
||||
highlight=False,
|
||||
markup=False,
|
||||
wrap=True,
|
||||
max_lines=500,
|
||||
)
|
||||
yield tx.DataTable(id="device-table", show_cursor=False)
|
||||
yield tx.Footer()
|
||||
|
||||
@@ -1023,6 +1059,21 @@ def _build_app(
|
||||
stop=self._stop,
|
||||
)
|
||||
self._flashlog_worker.start()
|
||||
# UI-capture transcript tailer — only runs when the camera panel
|
||||
# is enabled. Watches tests/ui_captures/**/transcript.md for new
|
||||
# lines as UI tests execute.
|
||||
if self._ui_camera_enabled:
|
||||
captures_root = self._root / "mcp-server" / "tests" / "ui_captures"
|
||||
# When the TUI is launched from inside mcp-server (the usual
|
||||
# case), `self._root` is already mcp-server/, so adjust:
|
||||
if not captures_root.parent.name == "mcp-server":
|
||||
captures_root = self._root / "tests" / "ui_captures"
|
||||
self._uicap_worker = _uicap_mod.UiCaptureTailer(
|
||||
root=captures_root,
|
||||
post=lambda tid, line: self.post_message(UiCaptureLine(tid, line)),
|
||||
stop=self._stop,
|
||||
)
|
||||
self._uicap_worker.start()
|
||||
self._spawn_pytest(self._pytest_args)
|
||||
# Header tick (seed / runtime / sparkline re-renders at 1 Hz).
|
||||
# Also refreshes the device-status column so the per-test elapsed
|
||||
@@ -1217,6 +1268,84 @@ def _build_app(
|
||||
log = self.query_one("#pytest-log", tx.RichLog)
|
||||
log.write(f"[flash] {message.line}")
|
||||
|
||||
def on_ui_capture_line(self, message: Any) -> None:
|
||||
"""Route a UI-capture transcript line into the camera panel.
|
||||
|
||||
Each line is already formatted by frame_capture — e.g.
|
||||
`1. **initial** — frame 2/8 name=home — OCR: ...`. We write
|
||||
the text into the RichLog AND try to render the corresponding
|
||||
PNG on the left side (requires rich-pixels, Pillow).
|
||||
"""
|
||||
if not self._ui_camera_enabled:
|
||||
return
|
||||
try:
|
||||
log_panel = self.query_one("#uicap-log", tx.RichLog)
|
||||
except Exception:
|
||||
return
|
||||
log_panel.write(f"[{message.test_id}] {message.line}")
|
||||
self._render_latest_ui_capture(message.test_id, message.line)
|
||||
|
||||
def _render_latest_ui_capture(self, test_id: str, line: str) -> None:
|
||||
"""Find the PNG that corresponds to `line` and render it on the
|
||||
left of the uicap pane. Soft-fails if rich-pixels isn't
|
||||
installed or the PNG isn't found — operator still has the text
|
||||
transcript on the right.
|
||||
"""
|
||||
try:
|
||||
from PIL import Image # type: ignore[import-untyped]
|
||||
from rich_pixels import Pixels # type: ignore[import-untyped]
|
||||
except ImportError:
|
||||
return
|
||||
|
||||
# Transcript lines look like `1. **label** — ...`. Pull the leading
|
||||
# integer to locate the capture file.
|
||||
import re as _re
|
||||
|
||||
m = _re.match(r"\s*(\d+)\.\s", line)
|
||||
if not m:
|
||||
return
|
||||
step = int(m.group(1))
|
||||
|
||||
# Captures directory is sibling of tests/ — mirror the path the
|
||||
# tailer watches. Search both likely layouts (in-mcp-server vs.
|
||||
# firmware-root invocation).
|
||||
candidates = [
|
||||
self._root / "tests" / "ui_captures",
|
||||
self._root / "mcp-server" / "tests" / "ui_captures",
|
||||
]
|
||||
captures_root = next((p for p in candidates if p.is_dir()), None)
|
||||
if captures_root is None:
|
||||
return
|
||||
|
||||
# Drill into <session_seed>/<test_id>/ — test_id is the
|
||||
# sanitized nodeid the tailer already passed through.
|
||||
matches = list(captures_root.rglob(f"{test_id}/{step:03d}-*.png"))
|
||||
if not matches:
|
||||
return
|
||||
png_path = matches[-1]
|
||||
|
||||
try:
|
||||
img = Image.open(png_path).convert("RGB")
|
||||
# Resize to fit ~32 cells wide × ~12 rows tall (half-block
|
||||
# renderer gives 2× vertical resolution, so 32×24 px input
|
||||
# lands at ~32×12 cells). Keep aspect ratio.
|
||||
target_w = 60
|
||||
w, h = img.size
|
||||
target_h = max(1, int(h * (target_w / max(1, w))))
|
||||
# Clamp: the image panel is 14 rows; half-blocks give 2 rows
|
||||
# per vertical cell, so cap pixel height at ~26.
|
||||
target_h = min(target_h, 26)
|
||||
img = img.resize((target_w, target_h))
|
||||
pixels = Pixels.from_image(img)
|
||||
except Exception:
|
||||
return
|
||||
|
||||
try:
|
||||
image_widget = self.query_one("#uicap-image", tx.Static)
|
||||
image_widget.update(pixels)
|
||||
except Exception:
|
||||
pass
|
||||
|
||||
def on_firmware_log_line(self, message: Any) -> None:
|
||||
rec = message.record
|
||||
port = rec.get("port")
|
||||
|
||||
@@ -135,3 +135,14 @@ def picotool_bin() -> Path:
|
||||
("picotool",),
|
||||
"Install via `brew install picotool` or build from https://github.com/raspberrypi/picotool.",
|
||||
)
|
||||
|
||||
|
||||
def uhubctl_bin() -> Path:
|
||||
return _hw_tool(
|
||||
"MESHTASTIC_UHUBCTL_BIN",
|
||||
("uhubctl",),
|
||||
"Install via `brew install uhubctl` (macOS) or `apt install uhubctl` "
|
||||
"(Debian/Ubuntu). On Linux without the udev rules, or on older macOS "
|
||||
"with certain hubs, you may need to run via `sudo`: "
|
||||
"https://github.com/mvp/uhubctl#linux-usb-permissions",
|
||||
)
|
||||
|
||||
@@ -0,0 +1,67 @@
|
||||
"""Python mirror of firmware `enum input_broker_event` (src/input/InputBroker.h).
|
||||
|
||||
Used by `admin.send_input_event` + `tests/ui/` so callers can say
|
||||
`InputEventCode.RIGHT` instead of hard-coding 20. Values MUST stay in sync
|
||||
with the firmware enum — unit test `tests/unit/test_input_event_codes.py`
|
||||
pins the mapping.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from enum import IntEnum
|
||||
|
||||
|
||||
class InputEventCode(IntEnum):
|
||||
"""Button / key / gesture events dispatched by the firmware InputBroker."""
|
||||
|
||||
NONE = 0
|
||||
SELECT = 10
|
||||
SELECT_LONG = 11
|
||||
UP_LONG = 12
|
||||
DOWN_LONG = 13
|
||||
UP = 17
|
||||
DOWN = 18
|
||||
LEFT = 19
|
||||
RIGHT = 20
|
||||
CANCEL = 24
|
||||
BACK = 27
|
||||
# Auto-incremented values in the C enum (27 + 1, +2, +3):
|
||||
USER_PRESS = 28
|
||||
ALT_PRESS = 29
|
||||
ALT_LONG = 30
|
||||
SHUTDOWN = 0x9B
|
||||
GPS_TOGGLE = 0x9E
|
||||
SEND_PING = 0xAF
|
||||
FN_F1 = 0xF1
|
||||
FN_F2 = 0xF2
|
||||
FN_F3 = 0xF3
|
||||
FN_F4 = 0xF4
|
||||
FN_F5 = 0xF5
|
||||
MATRIXKEY = 0xFE
|
||||
ANYKEY = 0xFF
|
||||
|
||||
|
||||
def coerce_event_code(value: int | str | InputEventCode) -> int:
|
||||
"""Accept an int, a case-insensitive name, or an `InputEventCode` and return
|
||||
the u8 wire value. Raises ValueError on unknown names / out-of-range ints.
|
||||
"""
|
||||
if isinstance(value, InputEventCode):
|
||||
return int(value)
|
||||
if isinstance(value, int):
|
||||
if not 0 <= value <= 255:
|
||||
raise ValueError(f"event_code out of u8 range: {value}")
|
||||
return value
|
||||
if isinstance(value, str):
|
||||
key = value.upper().replace("-", "_")
|
||||
if key.startswith("INPUT_BROKER_"):
|
||||
key = key[len("INPUT_BROKER_") :]
|
||||
try:
|
||||
return int(InputEventCode[key])
|
||||
except KeyError as exc:
|
||||
known = ", ".join(m.name for m in InputEventCode)
|
||||
raise ValueError(
|
||||
f"unknown event code name {value!r}; known: {known}"
|
||||
) from exc
|
||||
raise TypeError(
|
||||
f"event_code must be int|str|InputEventCode, got {type(value).__name__}"
|
||||
)
|
||||
@@ -0,0 +1,147 @@
|
||||
"""OCR wrapper for UI tests + the `capture_screen` tool.
|
||||
|
||||
Auto-selects a reader in priority order:
|
||||
1. `easyocr` (deep-learning, high quality on OLED screens — but ~100 MB
|
||||
model download on first use).
|
||||
2. `pytesseract` (requires system `tesseract` binary on PATH).
|
||||
3. `null` — returns `""` with a warning. Tests fall back to log + image
|
||||
evidence when OCR is unavailable.
|
||||
|
||||
Override via `MESHTASTIC_UI_OCR_BACKEND=easyocr|pytesseract|null|auto`
|
||||
(default `auto`).
|
||||
|
||||
`ocr_text(png_bytes) -> str` is the only public entry point. The reader is
|
||||
constructed lazily on first call and cached, so the easyocr cold-start cost
|
||||
only hits once per process.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import functools
|
||||
import logging
|
||||
import os
|
||||
import shutil
|
||||
import sys
|
||||
from typing import Callable
|
||||
|
||||
log = logging.getLogger(__name__)
|
||||
|
||||
|
||||
def _backend_choice() -> str:
|
||||
return os.environ.get("MESHTASTIC_UI_OCR_BACKEND", "auto").lower()
|
||||
|
||||
|
||||
@functools.lru_cache(maxsize=1)
|
||||
def _reader() -> tuple[str, Callable[[bytes], str]]:
|
||||
"""Return `(backend_name, callable)` for whichever OCR is available."""
|
||||
choice = _backend_choice()
|
||||
|
||||
def _easyocr() -> tuple[str, Callable[[bytes], str]]:
|
||||
import easyocr # type: ignore[import-untyped] # noqa: PLC0415
|
||||
import numpy as np # type: ignore[import-untyped] # noqa: PLC0415
|
||||
|
||||
reader = easyocr.Reader(["en"], gpu=False, verbose=False)
|
||||
|
||||
def _run(png: bytes) -> str:
|
||||
try:
|
||||
import cv2 # type: ignore[import-untyped] # noqa: PLC0415
|
||||
|
||||
arr = np.frombuffer(png, dtype=np.uint8)
|
||||
img = cv2.imdecode(arr, cv2.IMREAD_COLOR)
|
||||
except ImportError:
|
||||
# Fall back to PIL if cv2 isn't around.
|
||||
from io import BytesIO # noqa: PLC0415
|
||||
|
||||
from PIL import Image # type: ignore[import-untyped] # noqa: PLC0415
|
||||
|
||||
img = np.array(Image.open(BytesIO(png)).convert("RGB"))
|
||||
try:
|
||||
results = reader.readtext(img, detail=0, paragraph=True)
|
||||
except Exception as exc: # noqa: BLE001
|
||||
log.warning("easyocr failed: %s", exc)
|
||||
return ""
|
||||
return "\n".join(str(r) for r in results)
|
||||
|
||||
return "easyocr", _run
|
||||
|
||||
def _pytesseract() -> tuple[str, Callable[[bytes], str]]:
|
||||
from io import BytesIO # noqa: PLC0415
|
||||
|
||||
import pytesseract # type: ignore[import-untyped] # noqa: PLC0415
|
||||
from PIL import Image # type: ignore[import-untyped] # noqa: PLC0415
|
||||
|
||||
if shutil.which("tesseract") is None:
|
||||
raise ImportError("`tesseract` binary not on PATH")
|
||||
|
||||
def _run(png: bytes) -> str:
|
||||
try:
|
||||
return str(pytesseract.image_to_string(Image.open(BytesIO(png))))
|
||||
except Exception as exc: # noqa: BLE001
|
||||
log.warning("pytesseract failed: %s", exc)
|
||||
return ""
|
||||
|
||||
return "pytesseract", _run
|
||||
|
||||
def _null() -> tuple[str, Callable[[bytes], str]]:
|
||||
log.warning(
|
||||
"OCR backend is null; install easyocr or tesseract for text extraction"
|
||||
)
|
||||
return "null", lambda _png: ""
|
||||
|
||||
if choice == "easyocr":
|
||||
return _easyocr()
|
||||
if choice == "pytesseract":
|
||||
return _pytesseract()
|
||||
if choice == "null":
|
||||
return _null()
|
||||
if choice != "auto":
|
||||
print(
|
||||
f"[ocr] unknown MESHTASTIC_UI_OCR_BACKEND={choice!r}; falling back to auto",
|
||||
file=sys.stderr,
|
||||
)
|
||||
|
||||
# auto mode
|
||||
try:
|
||||
return _easyocr()
|
||||
except ImportError:
|
||||
pass
|
||||
try:
|
||||
return _pytesseract()
|
||||
except ImportError:
|
||||
pass
|
||||
return _null()
|
||||
|
||||
|
||||
def ocr_text(png_bytes: bytes) -> str:
|
||||
"""Run OCR on a PNG-encoded image and return the decoded text (possibly empty)."""
|
||||
if not png_bytes:
|
||||
return ""
|
||||
_, run = _reader()
|
||||
return run(png_bytes)
|
||||
|
||||
|
||||
def backend_name() -> str:
|
||||
"""Return the currently-selected backend name, initializing if necessary."""
|
||||
name, _ = _reader()
|
||||
return name
|
||||
|
||||
|
||||
def warm() -> None:
|
||||
"""Run one dummy inference so the easyocr cold-start cost is paid upfront.
|
||||
|
||||
Pytest session fixture calls this once so the first real capture doesn't
|
||||
eat the model-load latency.
|
||||
"""
|
||||
# A 64×32 white PNG — decodes clean, no text to extract.
|
||||
white_png = bytes.fromhex(
|
||||
"89504e470d0a1a0a0000000d49484452000000400000002008060000007ccac28e"
|
||||
"0000001c49444154785eedc1010d000000c2a0f74f6d0d370000000000000080"
|
||||
"0b010000ffff030000000000000049454e44ae426082"
|
||||
)
|
||||
try:
|
||||
ocr_text(white_png)
|
||||
except Exception as exc: # noqa: BLE001
|
||||
log.warning("ocr.warm() failed: %s", exc)
|
||||
|
||||
|
||||
__all__ = ["backend_name", "ocr_text", "warm"]
|
||||
@@ -1,4 +1,4 @@
|
||||
"""FastMCP server wiring — 38 tools across 7 categories.
|
||||
"""FastMCP server wiring — 43 tools across 9 categories (adds uhubctl power control).
|
||||
|
||||
Each tool handler is a thin delegation to a named module (pio.py, admin.py,
|
||||
etc.). Business logic does not live here.
|
||||
@@ -513,6 +513,152 @@ def factory_reset(
|
||||
return admin.factory_reset(port=port, confirm=confirm, full=full)
|
||||
|
||||
|
||||
@app.tool()
|
||||
def send_input_event(
|
||||
event_code: int | str,
|
||||
kb_char: int = 0,
|
||||
touch_x: int = 0,
|
||||
touch_y: int = 0,
|
||||
port: str | None = None,
|
||||
) -> dict[str, Any]:
|
||||
"""Inject an InputBroker event (button / key / gesture) into the device UI.
|
||||
|
||||
Drives the same code path as a physical button press. Accepts a numeric
|
||||
event code (0..255) or a name like `"RIGHT"`, `"SELECT"`, `"FN_F1"`.
|
||||
|
||||
Common codes: SELECT=10, UP=17, DOWN=18, LEFT=19, RIGHT=20, CANCEL=24,
|
||||
BACK=27, FN_F1..F5=241..245.
|
||||
"""
|
||||
return admin.send_input_event(
|
||||
event_code=event_code,
|
||||
kb_char=kb_char,
|
||||
touch_x=touch_x,
|
||||
touch_y=touch_y,
|
||||
port=port,
|
||||
)
|
||||
|
||||
|
||||
@app.tool()
|
||||
def capture_screen(role: str | None = None, ocr: bool = True) -> dict[str, Any]:
|
||||
"""Grab a frame from the USB webcam pointed at the device screen.
|
||||
|
||||
Returns PNG bytes (base64), optional OCR text, and backend metadata.
|
||||
Requires the `[ui]` extras (opencv-python-headless) and a camera
|
||||
configured via `MESHTASTIC_UI_CAMERA_DEVICE[_<ROLE>]`. Falls back to a
|
||||
1×1 black PNG from the null backend when no camera is configured.
|
||||
"""
|
||||
import base64
|
||||
|
||||
from . import camera as camera_mod
|
||||
|
||||
cam = camera_mod.get_camera(role)
|
||||
try:
|
||||
png = cam.capture()
|
||||
finally:
|
||||
cam.close()
|
||||
|
||||
result: dict[str, Any] = {
|
||||
"backend": cam.name,
|
||||
"bytes": len(png),
|
||||
"image_base64": base64.b64encode(png).decode("ascii"),
|
||||
}
|
||||
if ocr:
|
||||
from . import ocr as ocr_mod
|
||||
|
||||
result["ocr_backend"] = ocr_mod.backend_name()
|
||||
result["ocr_text"] = ocr_mod.ocr_text(png)
|
||||
return result
|
||||
|
||||
|
||||
# ---------- USB power control (uhubctl) -----------------------------------
|
||||
|
||||
|
||||
@app.tool()
|
||||
def uhubctl_list() -> list[dict[str, Any]]:
|
||||
"""List every USB hub + per-port device attachment as seen by `uhubctl`.
|
||||
|
||||
Read-only — no confirm required. Each hub entry includes its location
|
||||
(`1-1.3`), descriptor, whether it supports Per-Port Power Switching,
|
||||
and a list of populated ports with VID:PID of attached devices.
|
||||
Useful for pre-flight checks before a destructive power-cycle call.
|
||||
"""
|
||||
from . import uhubctl as uhubctl_mod
|
||||
|
||||
return uhubctl_mod.list_hubs()
|
||||
|
||||
|
||||
@app.tool()
|
||||
def uhubctl_power(
|
||||
action: str,
|
||||
location: str | None = None,
|
||||
port: int | None = None,
|
||||
role: str | None = None,
|
||||
confirm: bool = False,
|
||||
) -> dict[str, Any]:
|
||||
"""Power a USB hub port on or off via `uhubctl -a on|off`.
|
||||
|
||||
Target the port by either (`location`, `port`) — raw uhubctl syntax,
|
||||
e.g. `location="1-1.3", port=2` — OR by `role` ("nrf52", "esp32s3").
|
||||
Role lookup honors `MESHTASTIC_UHUBCTL_LOCATION_<ROLE>` +
|
||||
`_PORT_<ROLE>` env vars first, falls back to VID auto-detection.
|
||||
|
||||
`action="off"` requires `confirm=True` (destructive — the attached
|
||||
device will immediately disappear from the OS).
|
||||
"""
|
||||
from . import uhubctl as uhubctl_mod
|
||||
|
||||
action_lower = action.lower()
|
||||
if action_lower not in {"on", "off"}:
|
||||
raise ValueError(f"action must be 'on' or 'off', got {action!r}")
|
||||
if action_lower == "off" and not confirm:
|
||||
raise uhubctl_mod.UhubctlError(
|
||||
"uhubctl_power action='off' requires confirm=True"
|
||||
)
|
||||
loc, p = _resolve_uhubctl_target(location, port, role)
|
||||
if action_lower == "on":
|
||||
return uhubctl_mod.power_on(loc, p)
|
||||
return uhubctl_mod.power_off(loc, p)
|
||||
|
||||
|
||||
@app.tool()
|
||||
def uhubctl_cycle(
|
||||
location: str | None = None,
|
||||
port: int | None = None,
|
||||
role: str | None = None,
|
||||
delay_s: int = 2,
|
||||
confirm: bool = False,
|
||||
) -> dict[str, Any]:
|
||||
"""Power a USB hub port off, wait `delay_s` seconds, then on.
|
||||
|
||||
The typical hard-reset sequence — shorter than off+on as two RPCs
|
||||
because uhubctl handles the timing in-process. Target by (location,
|
||||
port) or by role (see `uhubctl_power`). Requires `confirm=True`.
|
||||
"""
|
||||
from . import uhubctl as uhubctl_mod
|
||||
|
||||
if not confirm:
|
||||
raise uhubctl_mod.UhubctlError("uhubctl_cycle requires confirm=True")
|
||||
if delay_s < 0 or delay_s > 60:
|
||||
raise ValueError(f"delay_s must be 0..60, got {delay_s}")
|
||||
loc, p = _resolve_uhubctl_target(location, port, role)
|
||||
return uhubctl_mod.cycle(loc, p, delay_s=delay_s)
|
||||
|
||||
|
||||
def _resolve_uhubctl_target(
|
||||
location: str | None, port: int | None, role: str | None
|
||||
) -> tuple[str, int]:
|
||||
"""Shared arg-resolution for uhubctl_power + uhubctl_cycle."""
|
||||
from . import uhubctl as uhubctl_mod
|
||||
|
||||
if role is not None:
|
||||
if location is not None or port is not None:
|
||||
raise ValueError("pass either `role` OR (`location` + `port`), not both")
|
||||
return uhubctl_mod.resolve_target(role)
|
||||
if location is None or port is None:
|
||||
raise ValueError("must pass `role` or both `location` and `port`")
|
||||
return (location, int(port))
|
||||
|
||||
|
||||
# ---------- Direct hardware tools -----------------------------------------
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,321 @@
|
||||
"""USB hub power control via `uhubctl` — hard-recovery for wedged devices +
|
||||
deliberate offline-peer simulation for mesh tests.
|
||||
|
||||
Why: when a Meshtastic device's serial port wedges (stuck in a boot loop,
|
||||
frozen USB CDC, crashed firmware that didn't reboot), the only recovery is
|
||||
a physical unplug. uhubctl toggles VBUS per-port on any hub with Per-Port
|
||||
Power Switching (PPPS) support — which is most externally-powered hubs
|
||||
from the last ~5 years — so the harness can power-cycle a device
|
||||
programmatically.
|
||||
|
||||
Architecture:
|
||||
- `list_hubs()` parses `uhubctl` default output into structured records.
|
||||
- `find_port_for_vid(vid)` walks the hubs to find which location+port
|
||||
hosts a given USB VID.
|
||||
- `resolve_target(role)` is the public entry for callers that know a role
|
||||
(`nrf52`, `esp32s3`) but not a hub location: env-var pins win, VID
|
||||
auto-detect falls back.
|
||||
- `power_on`, `power_off`, `cycle` wrap the corresponding `uhubctl -a`
|
||||
invocations, routed through `hw_tools._run` so they share tee-to-flash-
|
||||
log + timeout handling with esptool / nrfutil / picotool.
|
||||
|
||||
Sudo policy: **fail fast**. Modern macOS + most PPPS-capable hubs work
|
||||
without root, but Linux without udev rules (or old macOS with specific
|
||||
driver quirks) still needs it. We run uhubctl non-root; if stderr
|
||||
matches the classic permission pattern we raise `UhubctlError` with an
|
||||
install hint pointing at the uhubctl docs. Auto-wrapping with `sudo`
|
||||
would prompt in the middle of test runs — bad for CI.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import os
|
||||
import re
|
||||
from typing import Any, Sequence
|
||||
|
||||
from . import config, hw_tools
|
||||
|
||||
# ---------- Parser ---------------------------------------------------------
|
||||
|
||||
# Hub descriptor line:
|
||||
# Current status for hub 1-1.3 [2109:2817 VIA Labs, Inc. USB2.0 Hub, USB 2.10, 4 ports, ppps]
|
||||
_HUB_RE = re.compile(
|
||||
r"^Current status for hub (?P<location>\S+)\s+\[(?P<descriptor>.+)\]\s*$"
|
||||
)
|
||||
|
||||
# Port line:
|
||||
# " Port 2: 0103 power enable connect [239a:8029 RAKwireless ...]"
|
||||
# The bracketed section is absent for empty ports.
|
||||
_PORT_RE = re.compile(
|
||||
r"^\s+Port\s+(?P<port>\d+):\s+(?P<status>\S+)\s+(?P<flags>.*?)"
|
||||
r"(?:\s+\[(?P<device_vid>[0-9a-fA-F]{4}):(?P<device_pid>[0-9a-fA-F]{4})(?:\s+(?P<device_desc>.+))?\])?\s*$"
|
||||
)
|
||||
|
||||
|
||||
class UhubctlError(RuntimeError):
|
||||
"""Raised on uhubctl-specific failures: parse errors, permission denied,
|
||||
hub-not-found, or PPPS not supported."""
|
||||
|
||||
|
||||
# ---------- Role → VID map -------------------------------------------------
|
||||
|
||||
# Mirrors the default hub_profile in `mcp-server/tests/conftest.py:335`.
|
||||
# Note: esp32s3 and esp32s3_alt share a logical role — we search both.
|
||||
ROLE_VIDS: dict[str, tuple[int, ...]] = {
|
||||
"nrf52": (0x239A,),
|
||||
"esp32s3": (0x303A, 0x10C4),
|
||||
}
|
||||
|
||||
|
||||
def _normalize_role(role: str) -> str:
|
||||
"""Collapse `esp32s3_alt` → `esp32s3` to match the tier conventions."""
|
||||
return role.split("_alt", 1)[0].lower()
|
||||
|
||||
|
||||
# ---------- Core subprocess runner -----------------------------------------
|
||||
|
||||
|
||||
# If uhubctl hits a permission problem — most commonly Linux without the
|
||||
# udev rules, or a macOS variant where the kernel holds the hub driver —
|
||||
# it prints something like "Permission denied. Try running as root".
|
||||
# Linux error text varies; we match a broad substring rather than exact.
|
||||
_PERM_ERROR_PATTERNS = (
|
||||
"permission denied",
|
||||
"operation not permitted",
|
||||
"try running as root",
|
||||
"need root",
|
||||
"requires root",
|
||||
)
|
||||
|
||||
|
||||
def _run_uhubctl(args: Sequence[str], *, timeout: float = 30.0) -> dict[str, Any]:
|
||||
"""Invoke uhubctl with the given args. Returns `hw_tools._run`'s dict.
|
||||
|
||||
Translates permission-denied failures into a `UhubctlError` with the
|
||||
install hint, so callers don't have to match stderr themselves. Other
|
||||
non-zero exits are returned as-is for the caller to interpret.
|
||||
"""
|
||||
binary = config.uhubctl_bin()
|
||||
result = hw_tools._run(binary, args, timeout=timeout) # noqa: SLF001
|
||||
if result["exit_code"] != 0:
|
||||
combined = (result.get("stderr") or "") + "\n" + (result.get("stdout") or "")
|
||||
lower = combined.lower()
|
||||
if any(pat in lower for pat in _PERM_ERROR_PATTERNS):
|
||||
raise UhubctlError(
|
||||
"uhubctl exited with a permission error. Install the udev "
|
||||
"rules on Linux, or try `sudo` as a fallback: "
|
||||
"https://github.com/mvp/uhubctl#linux-usb-permissions\n"
|
||||
f"stderr: {result.get('stderr_tail')!r}"
|
||||
)
|
||||
return result
|
||||
|
||||
|
||||
# ---------- List / parse ---------------------------------------------------
|
||||
|
||||
|
||||
def parse_list_output(output: str) -> list[dict[str, Any]]:
|
||||
"""Parse the default `uhubctl` stdout into structured hubs.
|
||||
|
||||
Each hub: {
|
||||
"location": "1-1.3",
|
||||
"descriptor": "2109:2817 VIA Labs ...",
|
||||
"vid": 0x2109,
|
||||
"pid": 0x2817,
|
||||
"ppps": bool,
|
||||
"ports": [{"port": int, "status": str, "flags": str,
|
||||
"device_vid": int | None, "device_pid": int | None,
|
||||
"device_desc": str | None}, ...],
|
||||
}
|
||||
"""
|
||||
hubs: list[dict[str, Any]] = []
|
||||
current: dict[str, Any] | None = None
|
||||
|
||||
for line in output.splitlines():
|
||||
hm = _HUB_RE.match(line)
|
||||
if hm:
|
||||
descriptor = hm.group("descriptor")
|
||||
hub_vid, hub_pid = None, None
|
||||
vid_match = re.match(r"([0-9a-fA-F]{4}):([0-9a-fA-F]{4})", descriptor)
|
||||
if vid_match:
|
||||
hub_vid = int(vid_match.group(1), 16)
|
||||
hub_pid = int(vid_match.group(2), 16)
|
||||
current = {
|
||||
"location": hm.group("location"),
|
||||
"descriptor": descriptor,
|
||||
"vid": hub_vid,
|
||||
"pid": hub_pid,
|
||||
"ppps": ", ppps" in descriptor or descriptor.endswith("ppps"),
|
||||
"ports": [],
|
||||
}
|
||||
hubs.append(current)
|
||||
continue
|
||||
|
||||
pm = _PORT_RE.match(line)
|
||||
if pm and current is not None:
|
||||
device_vid = pm.group("device_vid")
|
||||
device_pid = pm.group("device_pid")
|
||||
current["ports"].append(
|
||||
{
|
||||
"port": int(pm.group("port")),
|
||||
"status": pm.group("status"),
|
||||
"flags": (pm.group("flags") or "").strip(),
|
||||
"device_vid": int(device_vid, 16) if device_vid else None,
|
||||
"device_pid": int(device_pid, 16) if device_pid else None,
|
||||
"device_desc": (pm.group("device_desc") or "").strip() or None,
|
||||
}
|
||||
)
|
||||
return hubs
|
||||
|
||||
|
||||
def list_hubs() -> list[dict[str, Any]]:
|
||||
"""Enumerate every hub uhubctl can see, with per-port device attachments.
|
||||
|
||||
Pure read — no power state changes. Useful as a pre-flight check before
|
||||
a destructive `power_off` call.
|
||||
"""
|
||||
result = _run_uhubctl([], timeout=15.0)
|
||||
if result["exit_code"] != 0:
|
||||
raise UhubctlError(
|
||||
f"uhubctl list failed (exit {result['exit_code']}): {result.get('stderr_tail')!r}"
|
||||
)
|
||||
return parse_list_output(result["stdout"])
|
||||
|
||||
|
||||
# ---------- Lookup / resolution -------------------------------------------
|
||||
|
||||
|
||||
def find_port_for_vid(
|
||||
vid: int, pid: int | None = None, *, only_ppps: bool = True
|
||||
) -> list[tuple[str, int]]:
|
||||
"""Return ALL (location, port) matches for a device VID (optionally +PID).
|
||||
|
||||
`only_ppps=True` filters out hubs that don't advertise PPPS — we can't
|
||||
control them anyway. Callers that want to diagnose a missing device can
|
||||
pass `only_ppps=False` to see if the device is on a non-controllable
|
||||
hub (and raise a clearer error).
|
||||
"""
|
||||
hubs = list_hubs()
|
||||
matches: list[tuple[str, int]] = []
|
||||
for hub in hubs:
|
||||
if only_ppps and not hub["ppps"]:
|
||||
continue
|
||||
for port in hub["ports"]:
|
||||
if port["device_vid"] != vid:
|
||||
continue
|
||||
if pid is not None and port["device_pid"] != pid:
|
||||
continue
|
||||
matches.append((hub["location"], port["port"]))
|
||||
return matches
|
||||
|
||||
|
||||
def resolve_target(role: str) -> tuple[str, int]:
|
||||
"""Resolve a Meshtastic role to (hub_location, port_number).
|
||||
|
||||
Priority:
|
||||
1. Env vars `MESHTASTIC_UHUBCTL_LOCATION_<ROLE>` + `_PORT_<ROLE>`
|
||||
(e.g. `MESHTASTIC_UHUBCTL_LOCATION_NRF52=1-1.3`, `_PORT_NRF52=2`).
|
||||
2. VID auto-detect against `ROLE_VIDS[role]`, taking the first PPPS
|
||||
match.
|
||||
|
||||
Raises `UhubctlError` on ambiguity (multiple matches) or no-match. The
|
||||
env-var path exists specifically to disambiguate when two devices share
|
||||
a VID.
|
||||
"""
|
||||
role = _normalize_role(role)
|
||||
env_key_loc = f"MESHTASTIC_UHUBCTL_LOCATION_{role.upper()}"
|
||||
env_key_port = f"MESHTASTIC_UHUBCTL_PORT_{role.upper()}"
|
||||
loc = os.environ.get(env_key_loc)
|
||||
port_str = os.environ.get(env_key_port)
|
||||
if loc and port_str:
|
||||
try:
|
||||
return (loc, int(port_str))
|
||||
except ValueError as exc:
|
||||
raise UhubctlError(
|
||||
f"{env_key_port}={port_str!r} is not a valid integer"
|
||||
) from exc
|
||||
|
||||
if role not in ROLE_VIDS:
|
||||
raise UhubctlError(
|
||||
f"unknown role {role!r}; known roles: {sorted(ROLE_VIDS)}. "
|
||||
f"Set {env_key_loc} + {env_key_port} to pin manually."
|
||||
)
|
||||
|
||||
matches: list[tuple[str, int]] = []
|
||||
for vid in ROLE_VIDS[role]:
|
||||
matches.extend(find_port_for_vid(vid))
|
||||
|
||||
if not matches:
|
||||
vids = ", ".join(f"0x{v:04x}" for v in ROLE_VIDS[role])
|
||||
raise UhubctlError(
|
||||
f"no controllable hub hosts a device with VID in {{{vids}}} "
|
||||
f"for role={role!r}. Check the device is plugged into a "
|
||||
f"PPPS-capable hub, or pin manually via {env_key_loc} + {env_key_port}."
|
||||
)
|
||||
if len(matches) > 1:
|
||||
shown = ", ".join(f"{loc}:port{p}" for loc, p in matches)
|
||||
raise UhubctlError(
|
||||
f"ambiguous: multiple devices match role={role!r} ({shown}). "
|
||||
f"Pin the target via {env_key_loc} + {env_key_port}."
|
||||
)
|
||||
return matches[0]
|
||||
|
||||
|
||||
# ---------- Power actions --------------------------------------------------
|
||||
|
||||
|
||||
def _action(
|
||||
action: str,
|
||||
location: str,
|
||||
port: int,
|
||||
*,
|
||||
delay_s: int | None = None,
|
||||
timeout: float = 30.0,
|
||||
) -> dict[str, Any]:
|
||||
args: list[str] = ["-a", action, "-l", location, "-p", str(port)]
|
||||
if delay_s is not None:
|
||||
args.extend(["-d", str(delay_s)])
|
||||
# Suppress verbose "before" printout so our parser doesn't have to skip it.
|
||||
args.append("-N")
|
||||
result = _run_uhubctl(args, timeout=timeout)
|
||||
if result["exit_code"] != 0:
|
||||
raise UhubctlError(
|
||||
f"uhubctl -a {action} -l {location} -p {port} failed "
|
||||
f"(exit {result['exit_code']}): {result.get('stderr_tail')!r}"
|
||||
)
|
||||
return {
|
||||
"action": action,
|
||||
"location": location,
|
||||
"port": port,
|
||||
"delay_s": delay_s,
|
||||
"duration_s": result["duration_s"],
|
||||
}
|
||||
|
||||
|
||||
def power_on(location: str, port: int) -> dict[str, Any]:
|
||||
"""Drive the port VBUS high. Device re-enumerates in 1-3 s on healthy hubs."""
|
||||
return _action("on", location, port)
|
||||
|
||||
|
||||
def power_off(location: str, port: int) -> dict[str, Any]:
|
||||
"""Drive the port VBUS low. Device disappears from `list_devices` immediately."""
|
||||
return _action("off", location, port)
|
||||
|
||||
|
||||
def cycle(location: str, port: int, delay_s: int = 2) -> dict[str, Any]:
|
||||
"""Off → wait `delay_s` → on. The common hard-reset pattern."""
|
||||
# uhubctl's own `-a cycle` handles the delay internally; we use a
|
||||
# slightly longer timeout to accommodate delay_s + enumeration.
|
||||
return _action("cycle", location, port, delay_s=delay_s, timeout=30.0 + delay_s * 2)
|
||||
|
||||
|
||||
__all__ = [
|
||||
"ROLE_VIDS",
|
||||
"UhubctlError",
|
||||
"cycle",
|
||||
"find_port_for_vid",
|
||||
"list_hubs",
|
||||
"parse_list_output",
|
||||
"power_off",
|
||||
"power_on",
|
||||
"resolve_target",
|
||||
]
|
||||
@@ -393,6 +393,7 @@ def build_testing_profile(
|
||||
long_name: str | None = None,
|
||||
disable_mqtt: bool = True,
|
||||
disable_position: bool = False,
|
||||
enable_ui_log: bool = False,
|
||||
) -> dict[str, Any]:
|
||||
"""Build a USERPREFS dict for an isolated test-mesh device.
|
||||
|
||||
@@ -423,6 +424,10 @@ def build_testing_profile(
|
||||
traffic never leaks to a public broker.
|
||||
disable_position: if True, disables GPS + position broadcasts — useful
|
||||
when test devices sit on a bench without antennas.
|
||||
enable_ui_log: if True, stamps `USERPREFS_UI_TEST_LOG=true` so the
|
||||
firmware emits one `Screen: frame N/M name=... reason=...` log
|
||||
line per frame transition. Test-only; off by default because the
|
||||
log is chatty (multiple times per second during UI interaction).
|
||||
|
||||
"""
|
||||
if region not in KNOWN_REGIONS:
|
||||
@@ -475,6 +480,9 @@ def build_testing_profile(
|
||||
prefs["USERPREFS_CONFIG_OWNER_LONG_NAME"] = long_name
|
||||
if short_name is not None:
|
||||
prefs["USERPREFS_CONFIG_OWNER_SHORT_NAME"] = short_name
|
||||
if enable_ui_log:
|
||||
# Consumed by `#ifdef USERPREFS_UI_TEST_LOG` in src/graphics/Screen.cpp.
|
||||
prefs["USERPREFS_UI_TEST_LOG"] = True
|
||||
|
||||
return prefs
|
||||
|
||||
|
||||
Reference in New Issue
Block a user