hardlabs-sdk 0.1.0__py3-none-any.whl

hardlabs_sdk/__init__.py

@@ -0,0 +1,22 @@
+"""HardLabs SDK: run your tests against a simulated board running your firmware.
+
+    from hardlabs_sdk import Client
+
+    with Client().start("company_name/board_name", ["bootloader.bin@0x00400000", "app.bin@0x00410000"]) as board:
+        board.wait_for("app ready", within=5)
+        port = board.serial("rs485")          # serial_for_url(port.url) in your own framework
+        board.do("bench-supply.volts", 11.5)
+        assert board.read("power-monitor.bus-current") < 0.2
+        board.U4.do("extra-load-current", 0.5)  # a part by its schematic reference designator
+"""
+
+__version__ = "0.1.0"
+
+from ._http import HardLabsError  # noqa: E402
+from .board import Board, ConsoleTimeout, Control, Line, Part, Reading, SimulationStopped  # noqa: E402
+from .client import Client  # noqa: E402
+from .images import Image  # noqa: E402
+from .unit_tests import TestCase, UnitTestReport  # noqa: E402
+
+__all__ = ["Board", "Client", "ConsoleTimeout", "Control", "HardLabsError", "Image", "Line", "Part", "Reading",
+           "SimulationStopped", "TestCase", "UnitTestReport", "__version__"]

hardlabs_sdk/__main__.py

@@ -0,0 +1,60 @@
+"""``python -m hardlabs_sdk up``: boot a board and keep its serial ports open
+on this computer, for tools you run by hand (your own CLI, a terminal).
+
+    python -m hardlabs_sdk up company_name/board_name \\
+        --firmware bootloader.bin@0x00400000 --firmware app.bin@0x00410000 --serial rs485
+
+prints each port's address (``socket://127.0.0.1:N``) and runs until Ctrl-C,
+then stops the board.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+import time
+
+from ._http import HardLabsError
+from .client import Client
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(prog="python -m hardlabs_sdk")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    up = sub.add_parser("up", help="boot a board and bridge its serial ports here")
+    up.add_argument("sim", help="owner/project[@version]")
+    up.add_argument("--firmware", action="append", help="an ELF, or file@address per image (repeat)")
+    up.add_argument("--serial", action="append", default=[], help="a serial port to bridge (repeat; default: console)")
+    up.add_argument("--pty", action="store_true", help="pseudo-terminals instead of socket:// ports")
+    up.add_argument("--api", help="API address")
+    sub.add_parser("sims", help="the simulations you can open")
+    args = ap.parse_args(argv)
+    try:
+        client = Client(api=getattr(args, "api", None))
+        if args.cmd == "sims":
+            for s in client.sims():
+                print(s.get("address") or s["id"])
+            return 0
+        board = client.board(args.sim).start(args.firmware)
+        fw = board.firmware or {}
+        print(f"{board.name} running {fw.get('name', 'its own firmware')}")
+        for img in fw.get("images") or []:
+            print(f"  {img['name']} at {img['address']}")
+        bridges = [board.serial(p, pty=args.pty) for p in (args.serial or ["console"])]
+        for b in bridges:
+            print(f"  {b.port}: {b.url}")
+        print("Ctrl-C stops the board.", flush=True)
+        try:
+            while True:
+                time.sleep(1)
+        except KeyboardInterrupt:
+            pass
+        board.stop()
+        return 0
+    except (HardLabsError, LookupError, FileNotFoundError, ValueError) as e:
+        print(f"hardlabs: {e}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

hardlabs_sdk/_http.py

@@ -0,0 +1,87 @@
+"""The HardLabs API over HTTP: a token on every request, JSON in and out,
+errors as HardLabsError with the server's message. Standard library only."""
+
+from __future__ import annotations
+
+import json
+import re
+import secrets
+import socket
+import urllib.error
+import urllib.request
+from typing import Any
+
+from . import __version__
+
+
+class HardLabsError(Exception):
+    """A request the API refused or could not answer."""
+
+    def __init__(self, message: str, status: int = 0, code: str | None = None, body: dict | None = None) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.body = body or {}
+
+
+def friendly(msg: str) -> str:
+    """Server messages as a customer reads them: the engine underneath is not their concern."""
+    return re.sub(r"\bRenode\b", "the simulator", msg.replace("Renode Monitor", "simulator"))
+
+
+class Http:
+    def __init__(self, base: str, token: str, *, timeout: float = 60.0, client: str = f"sdk-python/{__version__}") -> None:
+        self.base = base.rstrip("/")
+        self.token = token
+        self.timeout = timeout
+        self.client = client
+
+    def headers(self) -> dict[str, str]:
+        out = {"X-HardLabs-Client": self.client}
+        if self.token:
+            out["Authorization"] = f"Bearer {self.token}"
+        return out
+
+    def call(self, method: str, path: str, body: Any = None, *, files: list[tuple[str, str, bytes]] | None = None,
+             form: list[tuple[str, str]] | None = None, timeout: float | None = None) -> dict:
+        headers = self.headers()
+        data: bytes | None = None
+        if files is not None or form is not None:
+            data, ctype = multipart(form or [], files or [])
+            headers["Content-Type"] = ctype
+        elif body is not None:
+            data = json.dumps(body).encode()
+            headers["Content-Type"] = "application/json"
+        req = urllib.request.Request(f"{self.base}{path}", data=data, method=method, headers=headers)
+        try:
+            with urllib.request.urlopen(req, timeout=timeout or self.timeout) as res:
+                text = res.read()
+        except urllib.error.HTTPError as e:
+            raw = e.read()
+            try:
+                payload = json.loads(raw) if raw else {}
+            except ValueError:
+                payload = {}
+            msg = str(payload.get("error") or payload.get("detail") or f"HTTP {e.code}")
+            if payload.get("detail") and payload.get("error"):
+                msg += f" — {payload['detail']}"
+            raise HardLabsError(friendly(msg), e.code, payload.get("error") if isinstance(payload.get("error"), str) else None,
+                                payload) from None
+        except (urllib.error.URLError, socket.timeout, ConnectionError) as e:
+            raise HardLabsError(f"cannot reach {self.base} ({getattr(e, 'reason', e)})") from None
+        return json.loads(text) if text else {}
+
+
+def multipart(fields: list[tuple[str, str]], files: list[tuple[str, str, bytes]]) -> tuple[bytes, str]:
+    """``(body, content type)`` for form *fields* and *files* as (field, filename, data); repeated names kept in order."""
+    boundary = f"hardlabs-{secrets.token_hex(12)}"
+    out = bytearray()
+    for name, value in fields:
+        out += f'--{boundary}\r\nContent-Disposition: form-data; name="{name}"\r\n\r\n{value}\r\n'.encode()
+    for name, filename, data in files:
+        safe = filename.replace('"', "_").replace("\r", "_").replace("\n", "_")
+        out += (f'--{boundary}\r\nContent-Disposition: form-data; name="{name}"; filename="{safe}"\r\n'
+                "Content-Type: application/octet-stream\r\n\r\n").encode()
+        out += data + b"\r\n"
+    out += f"--{boundary}--\r\n".encode()
+    return bytes(out), f"multipart/form-data; boundary={boundary}"

hardlabs_sdk/board.py

@@ -0,0 +1,454 @@
+"""A simulated board running your firmware: its console, its controls and
+readings, simulated time, and its serial ports for your own test framework.
+
+Waits and timeouts count simulated seconds, so a busy server or a slow
+network doesn't change a result. Console matching follows the scenario
+runner (``hardlabs run``): a match uses up its line and the lines before it,
+and output printed before a ``send`` is not the reply to it.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Iterable, Union
+
+from ._http import HardLabsError
+from .images import Image, as_images
+
+if TYPE_CHECKING:
+    from .client import Client
+    from .serial import SerialBridge
+    from .unit_tests import UnitTestReport
+
+
+class ConsoleTimeout(AssertionError):
+    """Expected console output didn't appear in time (simulated seconds)."""
+
+    def __init__(self, text: str, within: float, recent: list[str]) -> None:
+        tail = "\n".join(f"  │ {line}" for line in recent) or "  (nothing new on the console)"
+        super().__init__(f"{text!r} didn't appear within {within:g} s of simulated time; the console since:\n{tail}")
+        self.text = text
+        self.within = within
+        self.recent = recent
+
+
+class SimulationStopped(HardLabsError):
+    """Simulated time stopped moving: the simulation is no longer running."""
+
+
+@dataclass(frozen=True)
+class Line:
+    n: int
+    text: str
+
+
+@dataclass(frozen=True)
+class Control:
+    name: str
+    kind: str
+    label: str
+    usage: str
+    min: float | None = None
+    max: float | None = None
+    unit: str | None = None
+    fields: tuple = ()
+    aliases: tuple = ()  # the names it answers to by reference designator: ("U4.enable",)
+
+
+@dataclass(frozen=True)
+class Reading:
+    name: str
+    label: str
+    value: Any
+    unit: str | None
+    text: str
+    aliases: tuple = ()
+
+    def __float__(self) -> float:
+        return float(self.value)
+
+
+# A name that reads as a reference designator: U4, IC3, J_BAT1, LED2.
+_REF = re.compile(r"^[A-Z][A-Z_]*\d+[A-Z]?$")
+
+
+@dataclass(frozen=True)
+class Part:
+    """One part of the board by its schematic reference designator, with what
+    you can do to it and read from it. ``board.U4`` or ``board.part("U4")``;
+    ``print(part)`` lists its actions."""
+
+    ref: str
+    part: str | None              # what the parts list calls it: "MAX890LESA+"
+    what: str | None              # "Load switch"
+    where: str | None             # "I2C20 0x6B", when it is on a bus
+    status: str | None            # simulated, partial, folded, not_simulated, not_fitted
+    note: str | None              # what the simulation leaves out, when it says
+    controls: tuple = ()          # Control, named "U4.<control>"
+    reading_names: tuple = ()     # "U4.<reading>"
+    bus: str | None = None        # as the board names it: "i2c0", "I2C20", "spi0"
+    address: int | None = None    # on an I2C bus: 0x6B
+    cs: str | None = None         # an SPI part's chip select
+    behind: str | None = None     # the part its bus runs through (an I2C switch)
+    mcu_pins: tuple = ()          # the processor pins it reaches: ({"pin": "P2.05", "net": "IMU_INT"}, ...)
+    connected_refs: tuple = ()    # the parts it is wired to, the processor first
+    is_mcu: bool = False          # the processor itself
+    board: "Board | None" = field(default=None, repr=False, compare=False)
+
+    def connected(self) -> list["Part"]:
+        """The parts it is wired to: the processor (over a bus or a pin), an
+        I2C switch it sits behind, the parts on its signal nets. On the
+        processor, every part it reaches."""
+        return [self.board.part(r) for r in self.connected_refs]
+
+    def _name(self, name: str) -> str:
+        return name if name.lower().startswith(self.ref.lower() + ".") else f"{self.ref}.{name}"
+
+    def do(self, control: str, value: Any = None, **values: float) -> str:
+        """Work one of its controls: ``board.U4.do("extra-load-current", 0.5)``."""
+        return self.board.do(self._name(control), value, **values)
+
+    def read(self, name: str) -> Any:
+        """One of its readings' value: ``board.U4.read("load-current")``."""
+        return self.board.read(self._name(name))
+
+    def readings(self) -> dict[str, Reading]:
+        """Every value it shows now, by its ``U4.<reading>`` name."""
+        if not self.reading_names:
+            return {}
+        got = self.board.readings(*self.reading_names)
+        return {alias: r for alias, r in zip(self.reading_names, got.values())}
+
+    def __str__(self) -> str:
+        head = " ".join(x for x in (self.ref, self.part) if x)
+        facts = ", ".join(x for x in (self.what, self.where, (self.status or "").replace("_", " ")) if x)
+        lines = [head + (f" — {facts}" if facts else "")]
+        if self.note:
+            lines.append(f"  {self.note}")
+        if self.connected_refs:
+            lines.append(f"  wired to {', '.join(self.connected_refs)}")
+        lines += [f"  do   {c.usage}" for c in self.controls]
+        if self.reading_names:
+            lines.append(f"  read {', '.join(self.reading_names)}")
+        if not self.controls and not self.reading_names:
+            lines.append("  (nothing to do or read on this part)")
+        return "\n".join(lines)
+
+
+FirmwareArg = Union[str, Path, Image, Iterable[Union[str, Path, Image]], None]
+
+
+@dataclass
+class _Console:
+    next: int = 0      # last line number read
+    cursor: int = 0    # nothing at or before this line number may match any more
+    lines: list = field(default_factory=list)
+
+
+class Board:
+    """One simulation you can open, and your session on it. Use it as a
+    context manager, or call :meth:`stop` when done."""
+
+    def __init__(self, client: "Client", sim: dict) -> None:
+        self._client = client
+        self._http = client.http
+        self.sim = sim
+        self.id: str = sim["id"]
+        self.name: str = sim.get("address") or sim.get("title") or sim["id"]
+        self._images: list[Image] | None = None
+        self.started: dict = {}
+        self._consoles: dict[str | None, _Console] = {}
+        self._bridges: list["SerialBridge"] = []
+        self._parts: dict[str, Part] | None = None
+        self._mcu: str | None = None
+
+    def __repr__(self) -> str:
+        return f"<Board {self.name}>"
+
+    def __getattr__(self, name: str) -> "Part":
+        # board.U4: a part by its reference designator.
+        if _REF.match(name):
+            try:
+                return self.part(name)
+            except KeyError as e:
+                raise AttributeError(e.args[0]) from None
+        raise AttributeError(f"{type(self).__name__!r} object has no attribute {name!r}")
+
+    def __dir__(self) -> list[str]:
+        # Tab completion offers the parts once they have been listed (no request here).
+        return [*super().__dir__(), *(self._parts or {})]
+
+    def _path(self, rest: str) -> str:
+        return f"/v1/jobs/{self.id}/sim" + (f"/{rest}" if rest else "")
+
+    # --- the session --------------------------------------------------------------
+
+    def start(self, firmware: FirmwareArg = None) -> "Board":
+        """Boot the board afresh with *firmware*: an ELF, or the images a
+        flash holds (``"bootloader.bin@0x00400000"``, ``Image(path, address)``,
+        Intel HEX), packed by the server into one image. Without firmware, the
+        board runs its own. A board already running is restarted."""
+        if firmware is not None:
+            self._images = as_images(firmware)
+        for bridge in self._bridges:
+            bridge.reconnect_later()
+        if self._images:
+            if len(self._images) == 1 and self._images[0].kind == "elf" and self._images[0].address is None:
+                img = self._images[0]
+                self.started = self._http.call("POST", self._path("start"), files=[("firmware", img.name, img.data)],
+                                               timeout=300)
+            else:
+                self.started = self._http.call(
+                    "POST", self._path("start"), timeout=300,
+                    files=[("image", img.name, img.data) for img in self._images],
+                    form=[("address", "" if img.address is None else f"0x{img.address:08X}") for img in self._images])
+        else:
+            self.started = self._http.call("POST", self._path("start"), {}, timeout=300)
+        self._consoles = {}
+        self._parts = None
+        return self
+
+    restart = start
+
+    def stop(self) -> None:
+        """End the session (also on leaving a ``with`` block)."""
+        for bridge in list(self._bridges):
+            bridge.close()
+        try:
+            self._http.call("POST", self._path("stop"), {})
+        except HardLabsError:
+            pass
+
+    def __enter__(self) -> "Board":
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.stop()
+
+    def status(self) -> dict:
+        return self._http.call("GET", self._path(""))
+
+    @property
+    def firmware(self) -> dict | None:
+        """What the session runs: name, sha256 and, for images, where each one went."""
+        return self.started.get("firmware")
+
+    # --- simulated time -----------------------------------------------------------
+
+    def clock(self) -> float:
+        """Seconds of simulated time since the board booted."""
+        return float(self._http.call("GET", self._path("clock"))["seconds"])
+
+    def wait(self, seconds: float) -> float:
+        """Let *seconds* of simulated time pass; returns the clock."""
+        body: dict = {"seconds": float(seconds)}
+        while True:
+            try:
+                got = self._http.call("POST", self._path("wait"), body)
+            except HardLabsError as e:
+                if e.body.get("stalled"):
+                    raise SimulationStopped(str(e), e.status, e.code, e.body) from None
+                raise
+            if got.get("reached"):
+                return float(got["sim_seconds"])
+            body = {"until": got["until"]}
+
+    # --- the console --------------------------------------------------------------
+
+    def _console(self, console: str | None) -> _Console:
+        return self._consoles.setdefault(console, _Console())
+
+    def _read(self, console: str | None) -> _Console:
+        c = self._console(console)
+        q = f"console?after={c.next}" + (f"&console={console}" if console else "")
+        got = self._http.call("GET", self._path(q))
+        c.lines.extend(Line(x["n"], x["text"]) for x in got["lines"])
+        del c.lines[:-2000]
+        c.next = got["next"]
+        return c
+
+    def send(self, line: str, *, console: str | None = None) -> None:
+        """Type one line into the firmware's console (its shell). Output
+        already printed is not the reply to it."""
+        c = self._read(console)
+        c.cursor = c.next
+        self._http.call("POST", self._path("console"), {"text": line, **({"console": console} if console else {})})
+
+    def lines(self, *, console: str | None = None) -> list[Line]:
+        """Every console line read so far (the last 2000)."""
+        return list(self._read(console).lines)
+
+    def wait_for(self, text: str, *, within: float = 30.0, console: str | None = None) -> Line:
+        """The next console line holding *text*, within *within* simulated
+        seconds; ConsoleTimeout otherwise. The line and those before it are
+        used up: a second wait_for finds a later line."""
+        return self.expect_console(text, within=within, console=console)[0]
+
+    def expect_console(self, *texts: str, within: float = 30.0, console: str | None = None) -> list[Line]:
+        """Each of *texts*, in order, each on a later line than the one before,
+        all within *within* simulated seconds."""
+        c = self._console(console)
+        deadline = None
+        found = []
+        for text in texts:
+            while True:
+                body = {"text": text, "after": c.cursor, **({"console": console} if console else {})}
+                body.update({"deadline": deadline} if deadline is not None else {"within": within})
+                try:
+                    got = self._http.call("POST", self._path("console/wait"), body)
+                except HardLabsError as e:
+                    if e.body.get("stalled"):
+                        raise SimulationStopped(str(e), e.status, e.code, e.body) from None
+                    raise
+                deadline = got.get("deadline", deadline)
+                if got.get("matched"):
+                    line = Line(got["line"]["n"], got["line"]["text"])
+                    c.cursor = line.n
+                    found.append(line)
+                    break
+                if got.get("timed_out"):
+                    raise ConsoleTimeout(text, within, [x["text"] for x in got.get("recent") or []])
+                c.cursor = max(c.cursor, int(got.get("next") or c.cursor))
+        return found
+
+    # --- controls and readings ----------------------------------------------------
+
+    def controls(self) -> list[Control]:
+        """Everything you can do to the board, under the names the CLI and scenarios use."""
+        return [_control(c) for c in self._http.call("GET", self._path("controls"))["controls"]]
+
+    def do(self, control: str, value: Any = None, **values: float) -> str:
+        """Work a control: ``do("input-source.usb", True)``,
+        ``do("battery.level", 30)``, ``do("bench-supply.set", volts=5.0)``,
+        ``do("reset.press")``, or a part's by its reference designator,
+        ``do("U4.extra-load-current", 0.5)``. Returns its output, if any."""
+        body: dict = {"control": control}
+        if value is not None:
+            body["value"] = value
+        if values:
+            body["values"] = values
+        return self._http.call("POST", self._path("do"), body).get("output", "")
+
+    def readings(self, *names: str) -> dict[str, Reading]:
+        """The values the panels show now, by name (all when none given)."""
+        q = "&".join(f"name={n}" for n in names)
+        got = self._http.call("GET", self._path("readings" + (f"?{q}" if q else "")))
+        return {r["name"]: Reading(r["name"], r["label"], r["value"], r.get("unit"), r["text"], tuple(r.get("aliases") or ()))
+                for r in got["readings"]}
+
+    def reading(self, name: str) -> Reading:
+        return next(iter(self.readings(name).values()))
+
+    def read(self, name: str) -> Any:
+        """A reading's value: a number, True/False, a name, or None when the board doesn't report it."""
+        return self.reading(name).value
+
+    # --- parts by reference designator ---------------------------------------------
+
+    def _all_parts(self) -> list[Part]:
+        if self._parts is None:
+            got = self._http.call("GET", self._path("parts"))
+            self._mcu = got.get("mcu")
+            self._parts = {
+                p["ref"]: Part(p["ref"], p.get("part"), p.get("what"), p.get("where"), p.get("status"), p.get("note"),
+                               tuple(_control(c) for c in p.get("controls") or ()),
+                               tuple(r["name"] for r in p.get("readings") or ()),
+                               p.get("bus"), p.get("address"), p.get("cs"), p.get("behind"),
+                               tuple(p.get("mcu_pins") or ()), tuple(p.get("connected") or ()), bool(p.get("mcu")),
+                               self)
+                for p in got["parts"]
+            }
+        return list(self._parts.values())
+
+    def parts(self, *, bus: str | None = None, address: int | str | None = None,
+              connected_to: "str | Part | None" = None, status: str | None = None) -> list[Part]:
+        """Every part on the board by its schematic reference designator
+        (passives left out), each with what it is, how far it is simulated,
+        where it sits, and the controls and readings it answers to as
+        ``<ref>.<name>``. Narrow it like a DOM query, any filters combined:
+        ``parts(bus="i2c0")``, ``parts(address=0x6B)``,
+        ``parts(connected_to="U1")`` (the processor's include the parts on its
+        buses), ``parts(status="not_simulated")``."""
+        every = self._all_parts()
+        want = _as_address(address) if address is not None else None
+        to = (connected_to.ref if isinstance(connected_to, Part) else connected_to or "").lower()
+        return [p for p in every
+                if (bus is None or (p.bus or "").lower() == bus.lower())
+                and (want is None or p.address == want)
+                and (not to or to in (r.lower() for r in p.connected_refs))
+                and (status is None or p.status == status)]
+
+    def find(self, **filters: Any) -> Part:
+        """The one part :meth:`parts` finds with *filters*:
+        ``find(bus="i2c0", address=0x6B)``. Raises when none or several match."""
+        found = self.parts(**filters)
+        if len(found) != 1:
+            said = ", ".join(f"{k}={v!r}" for k, v in filters.items())
+            raise LookupError(f"{len(found) or 'no'} parts with {said}" +
+                              (f": {', '.join(p.ref for p in found)}" if found else ""))
+        return found[0]
+
+    @property
+    def mcu(self) -> Part:
+        """The processor: ``board.mcu.connected()`` is every part it reaches."""
+        self._all_parts()
+        if not self._mcu:
+            raise LookupError("this board's parts list doesn't say which part is the processor")
+        return self.part(self._mcu)
+
+    def part(self, ref: str) -> Part:
+        """One part by its reference designator, in any case: ``part("U4")``."""
+        parts = {p.ref.lower(): p for p in self._all_parts()}
+        found = parts.get(ref.lower())
+        if found is None:
+            raise KeyError(f"no part {ref!r} on this board — parts: {', '.join(p.ref for p in parts.values()) or 'none listed'}")
+        return found
+
+    def problems(self) -> list[dict]:
+        """What went wrong in the run so far: the firmware's crashes, asserts
+        and restarts, and what may be the simulation's limit."""
+        return self._http.call("GET", self._path("state?displays=0")).get("problems") or []
+
+    # --- serial ports and unit tests ----------------------------------------------
+
+    def serial_ports(self) -> list[str]:
+        """The ports :meth:`serial` can open: ``console``, the board's declared ports, ``usb:<controller>``."""
+        return list(self.status().get("serial") or [])
+
+    def serial(self, port: str = "console", *, pty: bool = False) -> "SerialBridge":
+        """A local port your own framework opens like the real one: its
+        ``url`` (``socket://127.0.0.1:N``) for pyserial's serial_for_url, or
+        with *pty* a pseudo-terminal ``path`` (macOS and Linux)."""
+        from .serial import SerialBridge
+
+        bridge = SerialBridge(self, port, pty=pty)
+        self._bridges.append(bridge)
+        return bridge
+
+    def _forget(self, bridge: "SerialBridge") -> None:
+        if bridge in self._bridges:
+            self._bridges.remove(bridge)
+
+    def run_unit_tests(self, *, within: float = 300.0, done: str | None = None,
+                       console: str | None = None) -> "UnitTestReport":
+        """Collect an on-target test binary's results from the console:
+        Unity or GoogleTest output, until its summary (or *done*) appears."""
+        from .unit_tests import collect
+
+        return collect(self, within=within, done=done, console=console)
+
+
+def _control(c: dict) -> Control:
+    return Control(c["name"], c["kind"], c["label"], c["usage"], c.get("min"), c.get("max"),
+                   c.get("unit"), tuple(c.get("fields") or ()), tuple(c.get("aliases") or ()))
+
+
+def _as_address(v: int | str) -> int:
+    if isinstance(v, int) and not isinstance(v, bool):
+        return v
+    try:
+        return int(str(v).strip(), 0)
+    except ValueError:
+        raise ValueError(f"address: {v!r} is not a number (0x6B or 107)") from None