fastgripper-dm 0.1.0__tar.gz

fastgripper_dm-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+venv/
+__pycache__/
+*.pyc
+dist/
+build/
+*.egg-info/
+logs/
+datasets/
+checkpoints/
+bench/local.toml
+.DS_Store

fastgripper_dm-0.1.0/PKG-INFO

@@ -0,0 +1,39 @@
+Metadata-Version: 2.5
+Name: fastgripper-dm
+Version: 0.1.0
+Summary: FastGripper worm-gear gripper driver for Damiao DM-J4310 actuators on a dedicated CAN channel
+License: Apache-2.0
+Requires-Python: >=3.10
+Requires-Dist: gs-usb>=0.3.0
+Requires-Dist: python-can<4.6,>=4.0
+Requires-Dist: pyusb>=1.2
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# fastgripper-dm
+
+Driver, calibration and CLI for the FastGripper worm-gear parallel gripper
+when its actuator is a Damiao DM-J4310 on a **dedicated CAN channel**
+(standalone mode). Linux + SocketCAN is the shipped path; macOS + gs_usb is
+supported for bench use.
+
+```sh
+pip install fastgripper-dm
+
+# one-time: give the motor its identity (motor ALONE on the bus) and its watchdog
+fastgripper-dm id --interface socketcan --channel can0 --new_id 0x07
+fastgripper-dm setup --interface socketcan --channel can0 --motor_id 0x07 --master_id 0x17
+
+# every session
+fastgripper-dm preflight            # no motion: bus, motor, fault, watchdog, calibration
+fastgripper-dm calibrate            # keyboard jog, mark open/closed (once per unit)
+fastgripper-dm autocal home         # re-anchor against the closed stop (~20 s)
+fastgripper-dm drive 40             # 40 % and exit
+```
+
+Docs: `docs/fastgripper-dm/` at the repo root (quickstart-linux, quickstart-mac, troubleshooting).
+
+Safety: the `setup` step writes a comm-loss watchdog into the motor so a
+crashed host cannot leave the worm pushing into a stop. `preflight` refuses to
+pass with the watchdog disabled.

fastgripper_dm-0.1.0/README.md

@@ -0,0 +1,26 @@
+# fastgripper-dm
+
+Driver, calibration and CLI for the FastGripper worm-gear parallel gripper
+when its actuator is a Damiao DM-J4310 on a **dedicated CAN channel**
+(standalone mode). Linux + SocketCAN is the shipped path; macOS + gs_usb is
+supported for bench use.
+
+```sh
+pip install fastgripper-dm
+
+# one-time: give the motor its identity (motor ALONE on the bus) and its watchdog
+fastgripper-dm id --interface socketcan --channel can0 --new_id 0x07
+fastgripper-dm setup --interface socketcan --channel can0 --motor_id 0x07 --master_id 0x17
+
+# every session
+fastgripper-dm preflight            # no motion: bus, motor, fault, watchdog, calibration
+fastgripper-dm calibrate            # keyboard jog, mark open/closed (once per unit)
+fastgripper-dm autocal home         # re-anchor against the closed stop (~20 s)
+fastgripper-dm drive 40             # 40 % and exit
+```
+
+Docs: `docs/fastgripper-dm/` at the repo root (quickstart-linux, quickstart-mac, troubleshooting).
+
+Safety: the `setup` step writes a comm-loss watchdog into the motor so a
+crashed host cannot leave the worm pushing into a stop. `preflight` refuses to
+pass with the watchdog disabled.

fastgripper_dm-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[project]
+name = "fastgripper-dm"
+version = "0.1.0"
+description = "FastGripper worm-gear gripper driver for Damiao DM-J4310 actuators on a dedicated CAN channel"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+dependencies = ["python-can>=4.0,<4.6", "pyusb>=1.2", "gs_usb>=0.3.0"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[project.scripts]
+fastgripper-dm = "fastgripper_dm.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/fastgripper_dm"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

fastgripper_dm-0.1.0/src/fastgripper_dm/__init__.py

@@ -0,0 +1,12 @@
+"""fastgripper-dm: FastGripper worm-gear gripper on a Damiao DM-J4310 over CAN.
+
+v0.0.x is the "harvest" release: the hardware-validated bench tools under one
+package and one CLI. The controller/port refactor (see the design spec) lands
+in v0.1.
+"""
+
+from .facade import FastGripper, HomingError
+from .profile import GripperProfile, PRESETS, TMAX_CAP
+
+__version__ = "0.1.0"
+__all__ = ["FastGripper", "HomingError", "GripperProfile", "PRESETS", "TMAX_CAP", "__version__"]

fastgripper_dm-0.1.0/src/fastgripper_dm/calstore.py

@@ -0,0 +1,99 @@
+"""Multi-gripper calibration store.
+
+Format v2 — one gripper_cal.json, named entries, each self-describing:
+
+    {
+      "format": 2,
+      "grippers": {
+        "right": {
+          "motor_id": 32, "master_id": 48,
+          "open": ..., "closed": ..., "span": ...,
+          "last_position": ..., "last_wrapped": ...,
+          "stop_open": ..., "stop_closed": ..., "stop_span": ...,
+          "calibrated_at": "..."
+        }
+      }
+    }
+
+Legacy flat single-gripper files (open/closed at top level) load as an entry
+named "default" and are upgraded to v2 on the next save. Tools select an
+entry with --gripper <name>; when the file has exactly one entry the name is
+optional.
+"""
+
+import json
+import os
+
+
+def config_home() -> str:
+    """$FASTGRIPPER_DM_HOME, else ~/.config/fastgripper-dm. Never the cwd: a
+    stale gripper_cal.json in the working directory silently shadowing the
+    real calibration would drive goto targets toward the wrong stops."""
+    return os.environ.get("FASTGRIPPER_DM_HOME") or os.path.join(
+        os.path.expanduser("~"), ".config", "fastgripper-dm")
+
+
+def default_cal_path() -> str:
+    return os.path.join(config_home(), "gripper_cal.json")
+
+
+def default_config_path() -> str:
+    return os.path.join(config_home(), "config.json")
+
+
+def load_store(path: str) -> dict:
+    """Load a cal store, migrating legacy flat files in memory."""
+    try:
+        raw = json.load(open(path))
+    except OSError:
+        return {"format": 2, "grippers": {}}
+    if "grippers" in raw:
+        return raw
+    # legacy flat single-gripper file
+    return {"format": 2, "grippers": {"default": raw}}
+
+
+def save_store(path: str, store: dict) -> None:
+    """Atomic write: a crash mid-save must not destroy the only calibration."""
+    store["format"] = 2
+    parent = os.path.dirname(os.path.abspath(path))
+    os.makedirs(parent, exist_ok=True)
+    tmp = path + ".tmp"
+    with open(tmp, "w") as f:
+        json.dump(store, f, indent=2)
+        f.flush()
+        os.fsync(f.fileno())
+    os.replace(tmp, path)
+
+
+def get_entry(store: dict, name: str | None = None) -> tuple[str, dict]:
+    """Resolve (name, entry). Name optional iff exactly one entry exists."""
+    g = store["grippers"]
+    if name is not None:
+        if name not in g:
+            raise SystemExit(f"no gripper named '{name}' in the cal file — "
+                             f"have: {', '.join(sorted(g)) or '(none)'}")
+        return name, g[name]
+    if len(g) == 1:
+        return next(iter(g.items()))
+    if not g:
+        raise SystemExit("cal file has no gripper entries — calibrate first "
+                         "(calibrate.py or autocal.py full)")
+    raise SystemExit(f"cal file has multiple grippers ({', '.join(sorted(g))}) — "
+                     f"pick one with --gripper <name>")
+
+
+def resolve_ids(args, entry: dict) -> tuple[int, int]:
+    """Motor IDs: the entry's own IDs win unless the CLI overrides them.
+    (add_bus_args defaults are 0x01/0x00 — treated as 'not specified'.)"""
+    cli_set = not (args.motor_id == 0x01 and args.master_id == 0x00)
+    if cli_set or "motor_id" not in entry:
+        return args.motor_id, args.master_id
+    return int(entry["motor_id"]), int(entry["master_id"])
+
+
+def entry_profile(entry: dict):
+    """The entry's profile block merged over package defaults."""
+    from .profile import GripperProfile
+
+    return GripperProfile.from_dict(entry.get("profile", {}) or {})

fastgripper_dm-0.1.0/src/fastgripper_dm/cli.py

@@ -0,0 +1,252 @@
+"""fastgripper-dm — command-line front door.
+
+    fastgripper-dm setup      save interface/channel (+ motor ids) and write the motor watchdog
+    fastgripper-dm preflight  no-motion go/no-go: bus echo, motor answers, fault, watchdog, cal entry
+    fastgripper-dm doctor     bus ping with fault decode (which motors are alive?)
+    fastgripper-dm id         re-ID a factory motor (must be alone on the bus) / --verify
+    fastgripper-dm watchdog   read or set the comm-loss watchdog (ms)
+    fastgripper-dm calibrate  keyboard jog, mark open/closed (real terminal)
+    fastgripper-dm autocal    full|home|touch hardstop calibration
+    fastgripper-dm cal-doctor turn-alias diagnosis of the saved calibration
+    fastgripper-dm open       open fully (torque-capped)
+    fastgripper-dm close      close fully (torque-capped)
+    fastgripper-dm goto       go to a percentage open (0 = closed, 100 = open)
+    fastgripper-dm drive      alias for `goto`
+    fastgripper-dm home       stall-home against the closed stop
+    fastgripper-dm status     print entry marks and current position (no motion)
+
+Saved settings live in $FASTGRIPPER_DM_HOME or ~/.config/fastgripper-dm/
+(config.json + gripper_cal.json). The tools take --interface/--channel/
+--motor_id/--master_id explicitly; `setup` records them so you can omit them.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+from .calstore import default_config_path
+
+
+def _load_config() -> dict:
+    p = default_config_path()
+    if os.path.exists(p):
+        return json.load(open(p))
+    return {}
+
+
+def _save_config(cfg: dict) -> None:
+    p = default_config_path()
+    os.makedirs(os.path.dirname(p), exist_ok=True)
+    tmp = p + ".tmp"
+    with open(tmp, "w") as f:
+        json.dump(cfg, f, indent=2)
+    os.replace(tmp, p)
+
+
+def _bus_argv(cfg: dict, extra: list[str]) -> list[str]:
+    """Prefix saved bus/motor settings unless the caller passed them explicitly."""
+    out: list[str] = []
+    for key, flag in (("interface", "--interface"), ("channel", "--channel"),
+                      ("motor_id", "--motor_id"), ("master_id", "--master_id")):
+        if key in cfg and flag not in extra:
+            out += [flag, str(cfg[key])]
+    return out + extra
+
+
+def _run_tool(tool_main, argv: list[str], prog: str) -> None:
+    from .tools._cli import run
+
+    sys.argv = [prog] + argv
+    run(tool_main)
+
+
+def cmd_setup(args, extra):
+    from .damiao.canbus import open_bus
+    from .damiao.config_tool import RegisterClient, read_watchdog_ms, set_watchdog_ms
+
+    cfg = _load_config()
+    for key in ("interface", "channel", "motor_id", "master_id"):
+        v = getattr(args, key)
+        if v is not None:
+            cfg[key] = v
+    if "interface" not in cfg:
+        raise SystemExit("setup needs --interface (socketcan|gs_usb|slcan) and --channel")
+    cfg.setdefault("motor_id", 0x01)
+    cfg.setdefault("master_id", 0x00)
+    cfg["watchdog_ms"] = args.watchdog_ms
+    _save_config(cfg)
+    print(f"saved {default_config_path()}: {cfg}")
+    with open_bus(cfg["interface"], cfg.get("channel")) as bus:
+        c = RegisterClient(bus)
+        mid = int(cfg["motor_id"])
+        if not c.probe(mid):
+            raise SystemExit(f"motor 0x{mid:02X} does not answer -- check power/wiring, or run `fastgripper-dm id`")
+        before = read_watchdog_ms(c, mid)
+        got = before if before == args.watchdog_ms else set_watchdog_ms(c, mid, args.watchdog_ms)
+        print(f"motor 0x{mid:02X} watchdog: {before} -> {got} ms (verified)")
+
+
+def cmd_watchdog(args, extra):
+    from .damiao.canbus import open_bus
+    from .damiao.config_tool import RegisterClient, read_watchdog_ms, set_watchdog_ms
+
+    cfg = _load_config()
+    mid = int(args.motor_id if args.motor_id is not None else cfg.get("motor_id", 0x01))
+    with open_bus(args.interface or cfg.get("interface", "auto"), args.channel or cfg.get("channel")) as bus:
+        c = RegisterClient(bus)
+        if args.set is None:
+            print(f"motor 0x{mid:02X} watchdog = {read_watchdog_ms(c, mid)} ms")
+        else:
+            print(f"motor 0x{mid:02X} watchdog = {set_watchdog_ms(c, mid, args.set)} ms (verified)")
+
+
+def cmd_id(args, extra):
+    from .damiao.canbus import open_bus
+    from .damiao.config_tool import RegisterClient, set_motor_id
+
+    cfg = _load_config()
+    with open_bus(args.interface or cfg.get("interface", "auto"), args.channel or cfg.get("channel")) as bus:
+        c = RegisterClient(bus)
+        if args.verify:
+            for reg in ("id", "master_id", "timeout", "sw_ver"):
+                print(f"motor 0x{args.new_id:02X} {reg} = {c.read(args.new_id, reg)}")
+            return
+        got_id, got_master = set_motor_id(c, args.old_id, args.new_id, args.master_id)
+        print(f"SUCCESS: motor is now 0x{got_id:02X} / feedback 0x{got_master:02X}")
+        cfg["motor_id"], cfg["master_id"] = got_id, got_master
+        _save_config(cfg)
+        print(f"saved to {default_config_path()}")
+
+
+def cmd_preflight(args, extra):
+    from .tools.preflight import run_preflight
+
+    cfg = _load_config()
+    ok = run_preflight(cfg, interface=args.interface, channel=args.channel)
+    raise SystemExit(0 if ok else 1)
+
+
+def cmd_motion(args, extra):
+    from .facade import FastGripper
+    from .tools._cli import run
+
+    frac = {"open": 1.0, "close": 0.0}.get(args.cmd)
+    if frac is None:
+        frac = args.pct / 100.0
+
+    def go():
+        with FastGripper.standalone(gripper=args.gripper, cal_path=args.cal) as g:
+            g.goto(frac)
+            g.wait(timeout=15.0)
+            print(f"at {g.position:+.2f} rad" + (" (stalled/holding)" if g.stalled else ""))
+    run(go)
+
+
+def cmd_home(args, extra):
+    from .facade import FastGripper
+    from .tools._cli import run
+
+    def go():
+        with FastGripper.standalone(gripper=args.gripper, cal_path=args.cal, home="stall") as g:
+            print(f"homed; at {g.position:+.2f} rad")
+    run(go)
+
+
+def cmd_status(args, extra):
+    from .facade import FastGripper
+    from .tools._cli import run
+
+    def go():
+        g = FastGripper.standalone(gripper=args.gripper, cal_path=args.cal, home="off")
+        g.connect()
+        e = g._entry
+        pos = g.position
+        pct = 100.0 * (pos - e["closed"]) / (e["open"] - e["closed"]) if pos is not None and e["open"] != e["closed"] else None
+        print(f"entry '{g._gripper_name}': open {e['open']:+.2f} closed {e['closed']:+.2f} rad")
+        print(f"position (this window): {pos:+.2f} rad" + (f" ~ {pct:.0f}% open" if pct is not None else ""))
+        print("NOTE: 'off' mode has no absolute frame; use preflight/park for trusted state")
+        g.port.disable()
+        g.port.close()
+    run(go)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="fastgripper-dm", description=__doc__,
+                                     formatter_class=argparse.RawDescriptionHelpFormatter)
+    sub = parser.add_subparsers(dest="cmd", required=True)
+    hexint = lambda s: int(s, 0)  # noqa: E731
+
+    p = sub.add_parser("setup", help="save bus/motor settings and write the motor watchdog")
+    p.add_argument("--interface", choices=["gs_usb", "slcan", "socketcan"])
+    p.add_argument("--channel")
+    p.add_argument("--motor_id", type=hexint)
+    p.add_argument("--master_id", type=hexint)
+    p.add_argument("--watchdog_ms", type=int, default=8000, help="RID 9 value; unit under investigation (8000 = the arm motors' proven setting)")
+
+    p = sub.add_parser("preflight", help="no-motion go/no-go")
+    p.add_argument("--interface"); p.add_argument("--channel")
+
+    p = sub.add_parser("watchdog", help="read/set the comm-loss watchdog (ms)")
+    p.add_argument("--set", type=int, default=None)
+    p.add_argument("--interface"); p.add_argument("--channel"); p.add_argument("--motor_id", type=hexint)
+
+    p = sub.add_parser("id", help="re-ID a factory motor (motor ALONE on the bus)")
+    p.add_argument("--old_id", type=hexint, default=0x01)
+    p.add_argument("--new_id", type=hexint, default=0x07)
+    p.add_argument("--master_id", type=hexint, default=None, help="default new_id + 0x10")
+    p.add_argument("--verify", action="store_true")
+    p.add_argument("--interface"); p.add_argument("--channel")
+
+    for name in ("doctor", "calibrate", "autocal", "cal-doctor"):
+        sub.add_parser(name, help=f"run `{name}` (pass its own flags after the name; -h for help)")
+
+    for name in ("open", "close"):
+        p = sub.add_parser(name, help=f"{name} fully (torque-capped)")
+        p.add_argument("--gripper", default=None)
+        p.add_argument("--cal", default=None, help="cal store path override")
+    for name in ("goto", "drive"):
+        p = sub.add_parser(name, help="go to a percentage open (0 = closed, 100 = open)")
+        p.add_argument("pct", type=float)
+        p.add_argument("--gripper", default=None)
+        p.add_argument("--cal", default=None, help="cal store path override")
+    p = sub.add_parser("home", help="stall-home against the closed stop, then hold just off it")
+    p.add_argument("--gripper", default=None)
+    p.add_argument("--cal", default=None, help="cal store path override")
+    p = sub.add_parser("status", help="print entry marks and current position (no motion; briefly energizes the motor with zero gains)")
+    p.add_argument("--gripper", default=None)
+    p.add_argument("--cal", default=None, help="cal store path override")
+
+    args, extra = parser.parse_known_args()
+    if args.cmd == "setup":
+        return cmd_setup(args, extra)
+    if args.cmd == "preflight":
+        return cmd_preflight(args, extra)
+    if args.cmd == "watchdog":
+        return cmd_watchdog(args, extra)
+    if args.cmd == "id":
+        return cmd_id(args, extra)
+    if args.cmd in ("open", "close", "goto", "drive"):
+        return cmd_motion(args, extra)
+    if args.cmd == "home":
+        return cmd_home(args, extra)
+    if args.cmd == "status":
+        return cmd_status(args, extra)
+
+    cfg = _load_config()
+    argv = _bus_argv(cfg, extra)
+    if args.cmd == "doctor":
+        from .tools.bus_ping import main as tool
+    elif args.cmd == "calibrate":
+        from .tools.calibrate import main as tool
+    elif args.cmd == "autocal":
+        from .tools.autocal import main as tool
+    else:
+        from .tools.cal_doctor import main as tool
+    _run_tool(tool, argv, f"fastgripper-dm {args.cmd}")
+
+
+if __name__ == "__main__":
+    main()

fastgripper_dm-0.1.0/src/fastgripper_dm/controller.py

@@ -0,0 +1,96 @@
+"""The gripper control algorithm, once, with no I/O.
+
+Ported from so101_teleop.py v7 (the hardware-validated version with the
+torque cap): software P velocity loop + per-tick torque clamp + stall hold.
+The owner of the bus loops `fb = port.command(controller.tick(fb, dt))`
+(standalone) or merges the returned command into its own array (adapters)."""
+
+from __future__ import annotations
+
+from .port import Feedback, MitCommand
+from .profile import GripperProfile
+from .tracker import MultiTurnTracker
+
+
+class GripperController:
+    def __init__(self, entry: dict, profile: GripperProfile):
+        profile.validate()
+        if "open" not in entry or "closed" not in entry:
+            raise ValueError("cal entry needs open/closed marks -- calibrate first")
+        self.entry = entry
+        self.profile = profile
+        self.kd = profile.tmax_nm / profile.vmax
+        self._lo = min(entry["open"], entry["closed"])
+        self._hi = max(entry["open"], entry["closed"])
+        self.tracker = MultiTurnTracker()
+        self.goal: float | None = None
+        self.stalled = False
+        self._stall_t = 0.0
+
+    # --- goals ---
+    def goto_rad(self, pos: float) -> None:
+        self.goal = min(self._hi, max(self._lo, pos))
+        self.stalled = False
+        self._stall_t = 0.0
+
+    def goto_frac(self, frac: float) -> None:
+        frac = min(1.0, max(0.0, frac))
+        self.goto_rad(self.entry["closed"] + frac * (self.entry["open"] - self.entry["closed"]))
+
+    def open(self) -> None:
+        self.goto_frac(1.0)
+
+    def close(self) -> None:
+        self.goto_frac(0.0)
+
+    def hold(self) -> None:
+        if self.position is not None:
+            self.goal = self.position
+
+    # --- state ---
+    @property
+    def position(self) -> float | None:
+        return self.tracker.position if self.tracker.seen else None
+
+    @property
+    def at_goal(self) -> bool:
+        return (self.goal is not None and self.position is not None
+                and abs(self.goal - self.position) < 0.05)
+
+    def adopt_park(self, last_position: float) -> None:
+        self.tracker = MultiTurnTracker(start_unwrapped=last_position)
+
+    def anchor(self, known_position: float) -> None:
+        self.tracker.anchor(known_position)
+
+    def park_fields(self) -> dict:
+        return {"last_position": self.tracker.position, "last_wrapped": self.tracker.wrapped}
+
+    # --- the tick ---
+    def tick(self, fb: Feedback, dt: float) -> MitCommand:
+        if fb.faulted:
+            return MitCommand()
+        pos = self.tracker.update(fb.position)
+        if self.goal is None or self.stalled:
+            return MitCommand(kd=self.kd)          # damp to zero velocity (hold)
+        p = self.profile
+        v = p.sw_kp * (self.goal - pos)
+        v = min(p.vmax, max(-p.vmax, v))
+        dv = p.tmax_nm / self.kd                    # = vmax by construction
+        # Clamps against fb.velocity, which is one integration step stale relative
+        # to the velocity the motor (or sim) uses to compute the torque it reports
+        # next tick -- the <= tmax bound is enforced by the motor's own kd law
+        # (tau = kd*(v_cmd - v_actual), a self-correcting relationship), not by
+        # strict per-tick algebra here, and is verified empirically in tests.
+        # Revisit this comment if vmax, sw_kp, or the loop dt change materially.
+        v = min(fb.velocity + dv, max(fb.velocity - dv, v))
+        # stall detection on MEASURED torque (current sense), like the bench code
+        if abs(fb.torque) > p.stall_torque_frac * p.tmax_nm and not self.at_goal:
+            self._stall_t += dt
+            if self._stall_t > p.stall_time_s:
+                self.stalled = True
+                self.goal = pos
+                return MitCommand(kd=self.kd)
+        else:
+            self._stall_t = 0.0
+        return MitCommand(vel=v, kd=self.kd)

fastgripper_dm-0.1.0/src/fastgripper_dm/damiao/can_port.py

@@ -0,0 +1,90 @@
+"""Synchronous MotorPort over a dedicated CAN channel (python-can)."""
+
+from __future__ import annotations
+
+import time
+
+from ..port import Feedback, MitCommand, PortError
+from .dm4310 import DM4310
+
+
+class PortFault(PortError):
+    def __init__(self, code: int, text: str):
+        super().__init__(text)
+        self.code = code
+
+
+class DamiaoCanPort:
+    pos_window = 12.5
+
+    def __init__(self, bus, motor_id: int, master_id: int, retry_budget_s: float = 0.2):
+        self.motor = DM4310(bus, can_id=motor_id, master_id=master_id)
+        self.retry_budget_s = retry_budget_s
+        self._closed = False
+
+    def enable(self) -> None:
+        self.motor.enable()
+
+    def disable(self) -> None:
+        self.motor.disable()
+
+    def clear_error(self) -> None:
+        self.motor.clear_error()
+
+    def _txrx(self, cmd: MitCommand) -> Feedback:
+        deadline = time.monotonic() + self.retry_budget_s
+        while True:
+            self.motor.mit_control(cmd.pos, cmd.vel, cmd.kp, cmd.kd, cmd.tau)
+            raw = self.motor.read_feedback(timeout=min(0.05, self.retry_budget_s))
+            if raw is not None:
+                return Feedback(position=raw.position, velocity=raw.velocity,
+                                torque=raw.torque, error_code=raw.error, t=time.monotonic())
+            if time.monotonic() > deadline:
+                raise PortError(f"motor 0x{self.motor.can_id:02X}: no feedback within "
+                                f"{self.retry_budget_s:.2f}s")
+
+    def _recover(self) -> Feedback | None:
+        for _ in range(10):
+            self.motor.clear_error()
+            time.sleep(0.01)
+            self.motor.enable()
+            try:
+                fb = self._txrx(MitCommand())
+            except PortError:
+                time.sleep(0.3)
+                continue
+            if not fb.faulted:
+                return fb
+            time.sleep(0.3)
+        return None
+
+    def command(self, cmd: MitCommand) -> Feedback:
+        fb = self._txrx(cmd)
+        if fb.faulted:
+            recovered = self._recover()
+            if recovered is None:
+                raise PortFault(fb.error_code,
+                                f"motor fault '{fb.fault_text}' did not clear after 10 attempts")
+            return recovered
+        return fb
+
+    def read(self) -> Feedback:
+        return self.command(MitCommand())    # zero gains: no motion
+
+    def close(self) -> None:
+        if self._closed:
+            return
+        self._closed = True
+        for _ in range(3):
+            try:
+                self.motor.mit_control(0.0, 0.0, 0.0, 0.0, 0.0)
+            except Exception:
+                break
+            time.sleep(0.02)
+        for _ in range(5):
+            try:
+                self.motor.disable()
+                self.motor.read_feedback(timeout=0.1)
+            except Exception:
+                break
+            time.sleep(0.05)