bounded-embodiment-kit 0.1.0__py3-none-any.whl

bounded_embodiment_kit/adapters/lerobot.py

@@ -0,0 +1,316 @@
+# SPDX-FileCopyrightText: 2026 Craig Merry and contributors
+# SPDX-License-Identifier: Apache-2.0
+"""DRAFT — requires line-by-line human review before use on hardware.
+
+The ``lerobot`` adapter: a LeRobot SO-100 / SO-101 follower arm on a Feetech bus.
+
+How a lab's gate plugs in. The adapter builds LeRobot's follower and connects its bus ITSELF with
+``feetech.connect_safely`` (goals synced to present before any torque). Only then does it hand the
+already-connected robot to the lab's ``--wrapper module:factory``, called as
+``factory(robot, context)``; the factory returns the gated wrapper (anything with
+``send_action(action) -> dict``). From then on:
+
+- every command goes through ``wrapper.send_action`` (the system under test);
+- the adapter NEVER calls the wrapper's ``connect()``, ``configure()`` or ``disconnect()``, nor the
+  inner robot's ``connect()`` or ``disconnect()``: LeRobot's ``connect()`` enables torque toward
+  goal registers that read 0 at power-up, and its ``disconnect()`` drops torque by default
+  (``SOFollowerConfig.disable_torque_on_disconnect=True``), which drops the arm;
+- stops, state reads and the final release go straight to the inner robot's bus, under the bus
+  lock, so a gate that misbehaves cannot block or alter a stop (it can only delay it by holding
+  the bus inside send_action; the watchdog's acknowledgement timer covers that case).
+
+``context`` is plain data: ``mode``, ``speed_factor`` (0.5 in a shakedown, else None: "use your own
+default"), and the paths of the envelope, command space, kit config and URDF.
+
+Other LeRobot robots (Dynamixel, Damiao, Robstride, Reachy 2 buses) are refused in v0.1: their
+connect path and their stop differ. A lab with one writes a ``python`` adapter with its own connect
+path, and runs with ``--estop-cmd``.
+
+LeRobot is imported only when a real robot is built (``build_follower``), never at import time.
+"""
+from __future__ import annotations
+
+import importlib
+import sys
+import threading
+from collections.abc import Callable
+from pathlib import Path
+
+from bounded_embodiment.commandspace import CommandSpace, load_command_space
+
+from .base import AdapterError, SendResult, State, clean_text, load_callable
+from .feetech import (
+    BODY_JOINT_SPEED_TRIP_DPS,
+    check_bus_is_ours,
+    choose_stop_goals,
+    connect_safely,
+    leave_safe,
+    norm_name,
+)
+
+__all__ = ["SUPPORTED_ROBOT_TYPES", "LeRobotAdapter", "add_arguments", "build_follower", "from_args",
+           "lerobot_version"]
+
+SUPPORTED_ROBOT_TYPES = ("so101_follower", "so100_follower")
+
+# LeRobot has moved the follower classes between releases (ev03-harness lerobot_compat.py).
+_FOLLOWER_PATHS = [
+    ("lerobot.robots.so_follower", "SO101Follower", "SO101FollowerConfig"),  # 0.6.x, main
+    ("lerobot.robots.so101_follower", "SO101Follower", "SO101FollowerConfig"),  # 0.2 - 0.4
+    ("lerobot.common.robots.so101_follower", "SO101Follower", "SO101FollowerConfig"),
+]
+
+#: How long close() waits for the bus lock before giving up (the command thread may be stuck
+#: inside a gate's send_action, holding the bus).
+CLOSE_LOCK_TIMEOUT_S = 5.0
+
+
+def _log(msg: str) -> None:
+    print(msg, file=sys.stderr, flush=True)
+
+
+def lerobot_version() -> str:
+    try:
+        from importlib.metadata import version
+
+        return version("lerobot")
+    except Exception:  # noqa: BLE001 - not installed, or broken metadata: say so, never fail
+        return "not installed"
+
+
+def build_follower(robot_type: str, port: str, robot_id: str,
+                   max_relative_target: float | None = None) -> object:
+    """Build (never connect) LeRobot's SO-10x follower, exactly as LeRobot's own scripts would."""
+    if robot_type not in SUPPORTED_ROBOT_TYPES:
+        raise AdapterError(f"robot type {robot_type!r} is refused in v0.1: only Feetech SO-10x "
+                           f"followers {SUPPORTED_ROBOT_TYPES} have a reviewed connect path and stop. "
+                           "Write a python adapter (be adapter new) with your own connect path, and "
+                           "run with --estop-cmd.")
+    errors = []
+    for module, robot_cls, config_cls in _FOLLOWER_PATHS:
+        try:
+            m = importlib.import_module(module)
+            robot_class, config_class = getattr(m, robot_cls), getattr(m, config_cls)
+            break
+        except (ImportError, AttributeError) as e:
+            errors.append(f"{module}: {e}")
+    else:
+        raise AdapterError("LeRobot's SO-101 follower was not found (pip install "
+                           "'bounded-embodiment-kit[lerobot]', Python >= 3.12). Tried:\n  "
+                           + "\n  ".join(errors))
+    kwargs = {"port": port, "id": robot_id, "max_relative_target": max_relative_target}
+    try:
+        cfg = config_class(use_degrees=True, **kwargs)
+    except TypeError:  # older LeRobot had no use_degrees option (connect_safely then refuses)
+        cfg = config_class(**kwargs)
+    return robot_class(cfg)
+
+
+class LeRobotAdapter:
+    """The adapter contract (``adapters.base``) for a LeRobot SO-10x follower."""
+
+    name = "lerobot"
+    simulation = False
+
+    def __init__(self, *, command_space_path: str | Path, port: str, robot_id: str,
+                 robot_type: str = "so101_follower", wrapper: str | None = None,
+                 wrapper_context: dict | None = None, max_relative_target: float | None = None,
+                 refuse_while_active: tuple[str, ...] = (),
+                 prompt: Callable[[str], str] = input, log: Callable[[str], None] = _log,
+                 make_robot: Callable[[], object] | None = None):
+        self.command_space_path = Path(command_space_path)
+        self.port, self.robot_id, self.robot_type = port, robot_id, robot_type
+        self.wrapper = wrapper
+        self.wrapper_context = dict(wrapper_context or {})
+        self.max_relative_target = max_relative_target
+        self.refuse_while_active = tuple(refuse_while_active)
+        self.prompt, self.log = prompt, log
+        self._make_robot = make_robot or (lambda: build_follower(robot_type, port, robot_id,
+                                                                 max_relative_target))
+        # One bus lock. Every bus access takes it: send, read_state, execute_stop, close. The
+        # watchdog never takes it; latch_stop() only sets an Event.
+        self._bus_lock = threading.RLock()
+        self._latched = threading.Event()
+        self._stop_goals: dict[str, int] | None = None
+        self._robot = None
+        self._target = None
+        self._connect_record: dict | None = None
+
+    # ----- open --------------------------------------------------------------------------------
+    def open(self) -> CommandSpace:
+        # The command space comes from the lab's declared file (URDF limits), never from bus
+        # calibration: bob's elbow and wrist are calibrated to the full encoder range.
+        space = load_command_space(self.command_space_path)
+        if space.kind != "joint_position":
+            raise AdapterError(f"the lerobot adapter drives joint positions; {self.command_space_path} "
+                               f"declares {space.kind!r}")
+        # Import the lab's factory BEFORE any torque, so an import error cannot leave a powered arm.
+        factory = load_callable(self.wrapper) if self.wrapper else None
+        self._preflight()
+        robot = self._make_robot()
+        self._check_robot(robot, space)
+        with self._bus_lock:
+            self._connect_record = connect_safely(robot, log=self.log)
+        self._robot = robot
+        try:
+            target = robot
+            if factory is not None:
+                target = factory(robot, dict(self.wrapper_context))
+                if not callable(getattr(target, "send_action", None)):
+                    raise AdapterError(f"{self.wrapper} returned {type(target).__name__}, which has "
+                                       "no send_action(action)")
+        except BaseException:
+            self._release_without_prompt()
+            raise
+        self._target = target
+        self._stop_goals = None
+        self._latched.clear()  # a new latch for this connection
+        return space
+
+    def _preflight(self) -> None:
+        """Refuse if anything else could command the arm (hw.py check_bus_is_ours)."""
+        problems = check_bus_is_ours(self.port, self.refuse_while_active)
+        if problems:
+            raise AdapterError("Something else could command the arm:\n  " + "\n  ".join(problems))
+
+    def _check_robot(self, robot: object, space: CommandSpace) -> None:
+        bus = getattr(robot, "bus", None)
+        motors = getattr(bus, "motors", None)
+        if not motors:
+            raise AdapterError(f"{type(robot).__name__} has no bus with motors")
+        unknown = [a.key for a in space.axes
+                   if not (a.key.endswith(".pos") and a.key[: -len(".pos")] in motors)]
+        if unknown:
+            raise AdapterError(f"command-space axes {unknown} are not '<motor>.pos' for this "
+                               f"robot's motors {list(motors)}")
+
+    def _release_without_prompt(self) -> None:
+        robot, self._robot, self._target = self._robot, None, None
+        if robot is None:
+            return
+        try:
+            with self._bus_lock:
+                if getattr(robot.bus, "is_connected", False):
+                    robot.bus.disconnect(disable_torque=False)  # torque untouched: the arm holds
+        except Exception as e:  # noqa: BLE001 - already failing; report and keep the first error
+            self.log(f"Could not release the port ({type(e).__name__}: {e}).")
+
+    # ----- describe ----------------------------------------------------------------------------
+    def describe(self) -> dict:
+        motors = list(getattr(getattr(self._robot, "bus", None), "motors", {}) or {})
+        body = [m for m in motors if m != "gripper"]
+        return {
+            "adapter": self.name,
+            "simulation": self.simulation,
+            # describe()["config"] is what the setup hash covers: everything that changes what is
+            # being tested or how it is driven, and nothing that changes from run to run.
+            "config": {
+                "adapter": self.name,
+                "robot_type": self.robot_type,
+                "port": self.port,
+                "robot_id": self.robot_id,
+                "wrapper": self.wrapper,
+                "max_relative_target": self.max_relative_target,
+            },
+            "lerobot_version": lerobot_version(),
+            "connect": self._connect_record,
+            "stop": {"rule": "every joint's present position, read at the first stop of a latch "
+                             "and re-sent unchanged by every later stop; raw ticks written to the "
+                             "inner bus, not through the wrapper"},
+            "joint_speed_trip_per_s": {m: BODY_JOINT_SPEED_TRIP_DPS for m in body},
+            "refuse_while_active": list(self.refuse_while_active),
+        }
+
+    # ----- commands ----------------------------------------------------------------------------
+    def send(self, cmd: dict) -> SendResult:
+        """Hand one proposal to the system under test. Never raises: the hostile stream sends NaN,
+        strings and missing keys on purpose, and LeRobot or a gate raising on them is a result."""
+        if self._latched.is_set():
+            return SendResult(False, None, "stop_latched")
+        target = self._target
+        if target is None:
+            return SendResult(False, None, "not_open")
+        try:
+            with self._bus_lock:
+                if self._latched.is_set():  # re-checked under the lock: the stop wins any race
+                    return SendResult(False, None, "stop_latched")
+                target.send_action(cmd)
+        except Exception as e:  # noqa: BLE001 - send() never raises; the error is the result
+            return SendResult(False, None, f"exception:{type(e).__name__}")
+        decision = getattr(target, "last_decision", None) if target is not self._robot else None
+        return SendResult(True, clean_text(decision), None)
+
+    def read_state(self) -> State | None:
+        robot = self._robot
+        if robot is None:
+            return None
+        with self._bus_lock:
+            values = robot.bus.sync_read("Present_Position")
+        units = {m: ("deg" if norm_name(motor) == "DEGREES" else "percent")
+                 for m, motor in robot.bus.motors.items()}
+        return State(joints={m: float(v) for m, v in values.items()}, units=units)
+
+    # ----- the stop ----------------------------------------------------------------------------
+    def latch_stop(self) -> None:
+        """Any thread. Sets the latch and returns at once: no bus access, no lock."""
+        self._latched.set()
+
+    def execute_stop(self) -> None:
+        """Command thread only. The stop: the present positions read at the first stop of this
+        latch (``feetech.choose_stop_goals``), written straight to the inner bus in raw ticks (no
+        wrapper, no LeRobot clamp, no degree rounding). Every later call re-sends exactly those."""
+        self._latched.set()
+        robot = self._robot
+        if robot is None:
+            raise AdapterError("execute_stop: the robot is not open")
+        with self._bus_lock:
+            bus = robot.bus
+            if self._stop_goals is None:
+                present = bus.sync_read("Present_Position", normalize=False)
+                self._stop_goals = choose_stop_goals(present)
+                self.log("Stop: every joint held where it was; later stops re-send these goals.")
+            bus.sync_write("Goal_Position", dict(self._stop_goals), normalize=False)
+
+    # ----- close -------------------------------------------------------------------------------
+    def close(self) -> None:
+        """Leave the arm holding (torque on) unless the operator types OFF; release the port. Never
+        through LeRobot's robot.disconnect() or the wrapper's."""
+        robot = self._robot
+        if robot is None:
+            return
+        if not self._bus_lock.acquire(timeout=CLOSE_LOCK_TIMEOUT_S):
+            self.log("*** The bus is still busy (a command is stuck?). Not touching it. "
+                     "CUT SERVO POWER if the arm is not holding still.")
+            return
+        try:
+            leave_safe(robot.bus, self.prompt, self.log)
+        finally:
+            self._bus_lock.release()
+            self._robot, self._target = None, None
+
+
+# ----- command line ----------------------------------------------------------------------------
+def add_arguments(p) -> None:
+    g = p.add_argument_group("lerobot adapter")
+    g.add_argument("--port", help="the follower's serial port (lerobot)")
+    g.add_argument("--id", dest="robot_id", help="the LeRobot robot id (its calibration file)")
+    g.add_argument("--robot-type", default="so101_follower", choices=SUPPORTED_ROBOT_TYPES)
+    g.add_argument("--wrapper", metavar="MODULE:FACTORY",
+                   help="the lab's gate: factory(robot, context) -> wrapper with send_action "
+                        "(module:name or path/to/file.py:name); omit for the bare robot")
+    g.add_argument("--max-relative-target", type=float, default=None,
+                   help="LeRobot's own per-command step clamp (part of the system under test)")
+    g.add_argument("--refuse-while-active", action="append", default=[], metavar="UNIT",
+                   help="a systemd unit that can also drive the arm; refuse while it is active")
+
+
+def from_args(args, context) -> LeRobotAdapter:
+    if not args.port or not args.robot_id:
+        raise AdapterError("the lerobot adapter needs --port and --id")
+    return LeRobotAdapter(command_space_path=context.command_space_path, port=args.port,
+                          robot_id=args.robot_id, robot_type=args.robot_type,
+                          wrapper=getattr(args, "wrapper", None),
+                          wrapper_context=context.wrapper_context(),
+                          max_relative_target=args.max_relative_target,
+                          refuse_while_active=tuple(args.refuse_while_active),
+                          prompt=context.prompt, log=context.log)

bounded_embodiment_kit/adapters/python.py

@@ -0,0 +1,136 @@
+# SPDX-FileCopyrightText: 2026 Craig Merry and contributors
+# SPDX-License-Identifier: Apache-2.0
+"""DRAFT — requires line-by-line human review before use on hardware.
+
+The ``python`` adapter: a lab's own adapter class, loaded by name (``--adapter-class
+path/to/my_adapter.py:Adapter`` or ``module:Class``) and constructed as ``Class(context)`` with
+the run's ``AdapterContext``. ``be adapter new NAME`` writes a starting point (``TEMPLATE``).
+
+The runner checks that the object has every method of the contract (``adapters.base``) before it
+calls any of them.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from .base import AdapterError, check_adapter, load_callable
+
+__all__ = ["TEMPLATE", "add_arguments", "from_args", "write_template"]
+
+
+def add_arguments(p) -> None:
+    g = p.add_argument_group("python adapter")
+    g.add_argument("--adapter-class", metavar="FILE.py:CLASS",
+                   help="the lab's adapter class (python adapter), constructed as Class(context)")
+
+
+def from_args(args, context):
+    if not getattr(args, "adapter_class", None):
+        raise AdapterError("the python adapter needs --adapter-class FILE.py:CLASS (be adapter new "
+                           "NAME writes a template)")
+    cls = load_callable(args.adapter_class)
+    adapter = cls(context)
+    check_adapter(adapter)
+    return adapter
+
+
+def write_template(name: str, out_dir: str | Path = ".") -> Path:
+    """Write ``<name>_adapter.py`` from TEMPLATE; refuse to overwrite."""
+    if not name.isidentifier():
+        raise AdapterError(f"{name!r} is not a Python identifier")
+    path = Path(out_dir) / f"{name}_adapter.py"
+    if path.exists():
+        raise AdapterError(f"{path} already exists; not overwriting it")
+    path.write_text(TEMPLATE.replace("{NAME}", name), encoding="utf-8")
+    return path
+
+
+TEMPLATE = '''"""{NAME}: a Bounded Embodiment adapter (written by `be adapter new {NAME}`).
+
+DRAFT — requires line-by-line human review before use on hardware.
+
+Fill in the four places marked TODO. Run it with:
+
+    be run ev03 --mode shakedown --adapter python --adapter-class {NAME}_adapter.py:Adapter ...
+
+Rules the runner relies on (bounded_embodiment_kit.adapters.base has the full contract):
+
+- open() connects WITHOUT the robot jumping: set every position goal to where the joint already is
+  before anything enables torque. It returns the lab's declared command space, loaded from the
+  file, never built from what the robot reports.
+- send() never raises. It hands the command to your system under test (your gate, your model's
+  command interface) exactly as your model would, and reports what happened.
+- latch_stop() is called from the WATCHDOG thread: it only sets a flag. No bus access, no lock.
+- execute_stop() runs on the command thread, under the bus lock. It chooses the stop goals ONCE
+  per latch and re-sends exactly the same goals on every later call. Never re-read the present
+  position on a later stop: a sagging arm re-anchored on every stop ratchets downward.
+- close() leaves the robot holding (torque on) unless the operator types OFF.
+"""
+import threading
+
+from bounded_embodiment.commandspace import load_command_space
+from bounded_embodiment_kit.adapters.base import SendResult, State
+
+
+class Adapter:
+    name = "{NAME}"
+    simulation = False
+
+    def __init__(self, context):
+        self.context = context              # AdapterContext: paths, mode, prompt, log
+        self._bus_lock = threading.RLock()  # every bus access takes it
+        self._latched = threading.Event()
+        self._stop_goals = None
+        self.robot = None
+
+    def open(self):
+        space = load_command_space(self.context.command_space_path)
+        # TODO: connect to the robot WITHOUT enabling torque; set every goal to the present
+        # position; read the goals back; only then enable torque. Then wrap it in your gate.
+        raise NotImplementedError("{NAME}: open() is not written yet")
+        self._latched.clear()
+        self._stop_goals = None
+        return space
+
+    def describe(self):
+        # "config" goes into the setup hash: everything that changes what is tested.
+        return {"adapter": self.name, "simulation": False,
+                "config": {"adapter": self.name},          # TODO: port, robot id, gate version...
+                "joint_speed_trip_per_s": {}}              # e.g. {"elbow": 150.0} (deg/s)
+
+    def send(self, cmd):
+        if self._latched.is_set():
+            return SendResult(False, None, "stop_latched")
+        try:
+            with self._bus_lock:
+                if self._latched.is_set():
+                    return SendResult(False, None, "stop_latched")
+                # TODO: hand cmd to your system under test, exactly as your model would.
+                raise NotImplementedError
+        except Exception as e:  # send() never raises
+            return SendResult(False, None, f"exception:{type(e).__name__}")
+        return SendResult(True, None, None)
+
+    def read_state(self):
+        # TODO: return State(joints={name: value}, units={name: "deg"}) from the encoders, or
+        # None if the robot has no joint state (then a run needs --no-fk-tripwire-i-understand).
+        return None
+
+    def latch_stop(self):
+        self._latched.set()                 # watchdog thread: a flag, nothing else
+
+    def execute_stop(self):
+        self._latched.set()
+        with self._bus_lock:
+            if self._stop_goals is None:
+                # TODO: choose the goals ONCE: read every joint's present position (a joint may
+                # be moving, so stop it where it is). Never read them again for a later stop.
+                self._stop_goals = {}
+            # TODO: send self._stop_goals to the robot, bypassing the gate.
+
+    def close(self):
+        answer = self.context.prompt("Type OFF and Enter to turn torque off, or Enter to leave it on: ")
+        if answer.strip() == "OFF":
+            pass                            # TODO: torque off
+        # TODO: release the connection without touching torque.
+'''

bounded_embodiment_kit/adapters/sim_rover.py

@@ -0,0 +1,206 @@
+# SPDX-FileCopyrightText: 2026 Craig Merry and contributors
+# SPDX-License-Identifier: Apache-2.0
+"""DRAFT — requires line-by-line human review before use on hardware.
+
+``sim-rover``: a simulated differential-drive rover commanded with ``{"linear": m/s, "angular":
+rad/s}`` (``examples/command-spaces/rover.command-space.json``). Port of ev03-harness
+``ev03/adapters.py`` SimRover, with its constants made parameters.
+
+The drive's own command interface (``SimRover.send_action``) does what UngatedRover did in the
+harness: a command with both keys as finite numbers is clamped to the drive's top speeds and
+applied; anything else raises ValueError and changes nothing. A lab's gate can wrap it with
+``--wrapper module:factory`` exactly as for an arm: ``factory(rover, context)``.
+
+The stop is zero velocity, the same every time. The rover then brakes at its acceleration limit,
+so from top speed it needs top_speed**2 / (2 * accel) metres (1.1 m with the defaults) and more
+than the watchdog's 0.25 s acknowledgement window: a stop at speed escalates, by design.
+
+There are no kinematics to check from the drive's state, so a run on it has no FK tripwire.
+"""
+from __future__ import annotations
+
+import math
+import threading
+import time
+from collections.abc import Callable, Mapping
+from pathlib import Path
+
+from bounded_embodiment.commandspace import CommandSpace, load_command_space
+
+from .base import AdapterError, SendResult, State, clean_text, load_callable
+
+__all__ = ["SimRover", "SimRoverAdapter", "add_arguments", "from_args"]
+
+PHYSICS_PERIOD_S = 0.005
+
+
+def _number(value: object) -> float:
+    if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value):
+        raise ValueError(f"not a finite number: {value!r}")
+    return float(value)
+
+
+class SimRover:
+    """Unicycle rover. Ground truth is (x, y, theta) in the envelope frame, metres and radians."""
+
+    def __init__(self, top_speed: float = 1.5, max_turn: float = 1.5, accel: float = 1.0,
+                 start: tuple[float, float, float] = (1.0, 1.0, 0.0)):
+        self.x, self.y, self.th = (float(v) for v in start)
+        self.v = self.w = 0.0
+        self.cmd_v = self.cmd_w = 0.0
+        self.top, self.max_turn, self.accel = top_speed, max_turn, accel
+        self.lock = threading.Lock()
+
+    def actuate(self, linear_mps: float, angular_radps: float) -> None:
+        """What reaches the motors, clamped to what the drive can do."""
+        with self.lock:
+            self.cmd_v = max(-self.top, min(self.top, linear_mps))
+            self.cmd_w = max(-self.max_turn, min(self.max_turn, angular_radps))
+
+    def send_action(self, cmd: Mapping) -> dict:
+        """The drive's own command interface: both keys, finite numbers, or ValueError."""
+        if not isinstance(cmd, Mapping) or "linear" not in cmd or "angular" not in cmd:
+            raise ValueError(f"a drive command needs linear and angular: {cmd!r}")
+        v, w = _number(cmd["linear"]), _number(cmd["angular"])
+        self.actuate(v, w)
+        return {"linear": self.cmd_v, "angular": self.cmd_w}
+
+    def tick(self, dt: float) -> None:
+        with self.lock:
+            dv = max(-self.accel * dt, min(self.accel * dt, self.cmd_v - self.v))
+            self.v += dv
+            self.w = self.cmd_w
+            self.th += self.w * dt
+            self.x += self.v * math.cos(self.th) * dt
+            self.y += self.v * math.sin(self.th) * dt
+
+    def pose(self) -> tuple[float, float, float]:
+        with self.lock:
+            return self.x, self.y, self.th
+
+    def velocities(self) -> tuple[float, float]:
+        with self.lock:
+            return self.v, self.w
+
+
+class SimRoverAdapter:
+    """The adapter contract for the simulated rover."""
+
+    name = "sim-rover"
+    simulation = True
+
+    def __init__(self, *, command_space_path: str | Path, top_speed: float = 1.5,
+                 max_turn: float = 1.5, accel: float = 1.0,
+                 start: tuple[float, float, float] = (1.0, 1.0, 0.0), wrapper: str | None = None,
+                 wrapper_context: dict | None = None, realtime: bool = True,
+                 log: Callable[[str], None] = print, prompt: Callable[[str], str] = input):
+        self.command_space_path = Path(command_space_path)
+        self.params = {"top_speed": top_speed, "max_turn": max_turn, "accel": accel,
+                       "start": list(start)}
+        self.wrapper, self.wrapper_context = wrapper, dict(wrapper_context or {})
+        self.realtime, self.log, self.prompt = realtime, log, prompt
+        self._bus_lock = threading.RLock()  # the drive's "bus": one lock, as for an arm
+        self._latched = threading.Event()
+        self._stop_goals: dict[str, float] | None = None
+        self.rover: SimRover | None = None
+        self._target = None
+        self._physics: threading.Thread | None = None
+        self._physics_quit = threading.Event()
+
+    def open(self) -> CommandSpace:
+        space = load_command_space(self.command_space_path)
+        if space.kind != "velocity" or set(space.keys) != {"linear", "angular"}:
+            raise AdapterError("sim-rover takes a velocity command space with axes linear and angular")
+        factory = load_callable(self.wrapper) if self.wrapper else None
+        p = self.params
+        self.rover = SimRover(p["top_speed"], p["max_turn"], p["accel"], tuple(p["start"]))
+        self._target = factory(self.rover, dict(self.wrapper_context)) if factory else self.rover
+        if not callable(getattr(self._target, "send_action", None)):
+            raise AdapterError(f"{self.wrapper} returned an object without send_action")
+        self._stop_goals = None
+        self._latched.clear()
+        if self.realtime:
+            self._physics_quit.clear()
+            self._physics = threading.Thread(target=self._run_physics, name="be-sim-physics",
+                                             daemon=True)
+            self._physics.start()
+        return space
+
+    def _run_physics(self) -> None:
+        last = time.perf_counter()
+        while not self._physics_quit.wait(PHYSICS_PERIOD_S):
+            now = time.perf_counter()
+            self.rover.tick(now - last)
+            last = now
+
+    def describe(self) -> dict:
+        return {"adapter": self.name, "simulation": True,
+                "config": {"adapter": self.name, "wrapper": self.wrapper, "sim": dict(self.params)},
+                "stop": {"rule": "zero velocity; the rover brakes at its acceleration limit"},
+                "joint_speed_trip_per_s": {}}
+
+    def send(self, cmd: dict) -> SendResult:
+        if self._latched.is_set():
+            return SendResult(False, None, "stop_latched")
+        try:
+            with self._bus_lock:
+                if self._latched.is_set():
+                    return SendResult(False, None, "stop_latched")
+                self._target.send_action(cmd)
+        except Exception as e:  # noqa: BLE001 - send() never raises; the error is the result
+            return SendResult(False, None, f"exception:{type(e).__name__}")
+        decision = getattr(self._target, "last_decision", None) if self._target is not self.rover else None
+        return SendResult(True, clean_text(decision), None)
+
+    def read_state(self) -> State | None:
+        with self._bus_lock:
+            v, w = self.rover.velocities()
+        return State(joints={"linear": v, "angular": w}, units={"linear": "m/s", "angular": "rad/s"})
+
+    def latch_stop(self) -> None:
+        self._latched.set()
+
+    def execute_stop(self) -> None:
+        self._latched.set()
+        with self._bus_lock:
+            if self._stop_goals is None:
+                self._stop_goals = {"linear": 0.0, "angular": 0.0}
+            self.rover.actuate(self._stop_goals["linear"], self._stop_goals["angular"])
+
+    def close(self) -> None:
+        self._physics_quit.set()
+        if self._physics is not None:
+            self._physics.join(timeout=2.0)
+            self._physics = None
+
+    def step(self, dt: float, substep: float = 0.001) -> None:
+        n = max(1, round(dt / substep))
+        for _ in range(n):
+            self.rover.tick(dt / n)
+
+    def truth_fn(self, fk=None, envelope=None) -> Callable[[], dict]:
+        """For the simulated instrument: every envelope point at the rover's position, z = 0."""
+        points = list(getattr(envelope, "points", {}) or {"base": None})
+
+        def truth() -> dict:
+            x, y, _ = self.rover.pose()
+            return {pid: (x, y, 0.0) for pid in points}
+
+        return truth
+
+
+def add_arguments(p) -> None:
+    g = p.add_argument_group("sim-rover adapter")
+    g.add_argument("--sim-rover-start", default="1.0,1.0,0.0", metavar="X,Y,THETA",
+                   help="start pose in the envelope frame (m, m, rad)")
+
+
+def from_args(args, context) -> SimRoverAdapter:
+    try:
+        x, y, th = (float(v) for v in args.sim_rover_start.split(","))
+    except ValueError:
+        raise AdapterError(f"--sim-rover-start {args.sim_rover_start!r} is not X,Y,THETA") from None
+    return SimRoverAdapter(command_space_path=context.command_space_path, start=(x, y, th),
+                           wrapper=getattr(args, "wrapper", None),
+                           wrapper_context=context.wrapper_context(), log=context.log,
+                           prompt=context.prompt)