arm101-cli 0.5.0__tar.gz → 0.6.0__tar.gz

{arm101_cli-0.5.0 → arm101_cli-0.6.0}/CHANGELOG.md

@@ -5,6 +5,31 @@ All notable changes to this project will be documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/). This project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.6.0] - 2026-06-27
+
+### Added
+
+- calibrate-motor verb: identify the single connected Feetech servo before assembly and catalog it — auto-detects the one motor (skipping busy/non-motor ports so it never grabs an unrelated device such as a Reachy daemon), verifies it is a Feetech STS3215 (model 777), shows its full read-only register snapshot, then records Servo Model / Gear Ratio / Corresponding Joint keyed by a motor label (F1..F6, L1..L6) into an XDG motor catalog. Read-only on the motor (no torque, motion, or EEPROM writes); manual and --auto (walk F1..F6 then L1..L6) modes. Validated live against a physical F1 follower motor.
+- set-motor-id verb: assign a new EEPROM id (1-253) to the single connected motor — the SO-101 pre-assembly step of connecting motors one at a time to give each its joint's id. Hard-gated: requires a typed `yes`, and a non-interactive stdin (EOF) refuses the persistent write unconditionally (CliError exit 2). Reuses the existing FeetechBus.write_id_baudrate primitive.
+- center-motor verb: drive the single connected motor to a known home position (default encoder tick 2048) for horn mounting, then relax torque (--keep-torque to leave it engaged). Commanded motion, hard-gated the same way (typed `yes`; EOF refuses to move). Adds enable_torque / write_goal_position primitives to the MotorBus interface (FeetechBus real impl at registers 40/42; FakeBus records torque/position writes in order for tests).
+
+### Changed
+
+- Renamed the optional install extra [hardware] → [seeed] (named after the Seeed Studio SO-101 kit; the kit currently ships Feetech servos, verified at runtime by model 777 so a future kit revision with a different servo vendor only updates the extra). Touches pyproject, README, docs, and the SDK install hint.
+- Registered set-motor-id/center-motor and updated the explain catalog, overview verb list, and learn prompt in lockstep so the documentation surfaces agree.
+- learn now documents the hardware prerequisite — the `[seeed]` SDK extra (`pip install 'arm101-cli[seeed]'`) and that set-motor-id/center-motor/setup-motors are gated destructive ops needing an interactive terminal — in both the text and `--json` (a `hardware` key), so a fresh install is self-sufficient from `learn` alone.
+
+### Fixed
+
+- set-motor-id/center-motor now reject a non-TTY stdin up front (before opening the bus), so a piped `yes` can no longer drive a persistent EEPROM write or commanded motion non-interactively (Qodo: gated write/motion needs an interactive terminal).
+- center-motor relaxes torque in a `finally` (unless `--keep-torque`) so a failed goal-position write never leaves the servo holding torque (Qodo: torque could remain enabled after an aborted move).
+- write_id_baudrate writes the baud register before the id register, both at the motor's current id — writing id first changed the device address mid-call, so the later baud write hit a now-unreachable id (Qodo).
+- set-motor-id/center-motor abort paths honour `--json` (emit a structured `aborted` payload instead of plain text) (Qodo).
+- FeetechBus.scan sweeps the full 1–253 id space by default (no broadcastPing in this SDK build) so a motor previously re-id'd above 12 is still detected (Qodo).
+- load_catalog rejects a non-object JSON root with a clean CliError instead of crashing on `.items()` (Qodo).
+- Corrected the SDK install hint to the real distribution name `arm101-cli[seeed]` (was `arm101[seeed]`) (Qodo).
+- Extracted three repeated CliError strings in bus.py to module constants (SonarCloud python:S1192).
+
 ## [0.5.0] - 2026-06-27
 
 ### Added

{arm101_cli-0.5.0 → arm101_cli-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arm101-cli
-Version: 0.5.0
+Version: 0.6.0
 Summary: Agent and CLI for controlling SO-ARM101 robotic arm grippers
 Project-URL: Homepage, https://github.com/agentculture/arm101-cli
 Project-URL: Issues, https://github.com/agentculture/arm101-cli/issues
@@ -13,10 +13,10 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Software Development
 Requires-Python: >=3.12
-Provides-Extra: hardware
-Requires-Dist: feetech-servo-sdk>=1.0; extra == 'hardware'
 Provides-Extra: mac
 Requires-Dist: pyserial>=3.5; extra == 'mac'
+Provides-Extra: seeed
+Requires-Dist: feetech-servo-sdk>=1.0; extra == 'seeed'
 Provides-Extra: win
 Requires-Dist: pyserial>=3.5; extra == 'win'
 Description-Content-Type: text/markdown
@@ -44,10 +44,12 @@ Base install (zero third-party runtime dependencies — introspection only):
 uv sync          # or: pip install arm101-cli
 ```
 
-For real Feetech STS3215 motor I/O, add the `[hardware]` extra:
+For real Feetech STS3215 motor I/O on the Seeed Studio SO-101 kit, add the
+`[seeed]` extra (named by the kit provider; the CLI verifies each connected
+motor really is a Feetech STS3215 at runtime):
 
 ```bash
-uv sync --extra hardware          # or: pip install 'arm101-cli[hardware]'
+uv sync --extra seeed          # or: pip install 'arm101-cli[seeed]'
 ```
 
 This pulls in `feetech-servo-sdk` (import module `scservo_sdk`), which the bus

{arm101_cli-0.5.0 → arm101_cli-0.6.0}/README.md

@@ -21,10 +21,12 @@ Base install (zero third-party runtime dependencies — introspection only):
 uv sync          # or: pip install arm101-cli
 ```
 
-For real Feetech STS3215 motor I/O, add the `[hardware]` extra:
+For real Feetech STS3215 motor I/O on the Seeed Studio SO-101 kit, add the
+`[seeed]` extra (named by the kit provider; the CLI verifies each connected
+motor really is a Feetech STS3215 at runtime):
 
 ```bash
-uv sync --extra hardware          # or: pip install 'arm101-cli[hardware]'
+uv sync --extra seeed          # or: pip install 'arm101-cli[seeed]'
 ```
 
 This pulls in `feetech-servo-sdk` (import module `scservo_sdk`), which the bus

{arm101_cli-0.5.0 → arm101_cli-0.6.0}/arm101/cli/__init__.py

@@ -63,12 +63,15 @@ def _argv_has_json(argv: list[str] | None) -> bool:
 
 def _build_parser() -> argparse.ArgumentParser:
     from arm101.cli._commands import calibrate as _calibrate_cmd
+    from arm101.cli._commands import calibrate_motor as _calibrate_motor_cmd
+    from arm101.cli._commands import center_motor as _center_motor_cmd
     from arm101.cli._commands import cli as _cli_group
     from arm101.cli._commands import doctor as _doctor_cmd
     from arm101.cli._commands import explain as _explain_cmd
     from arm101.cli._commands import find_port as _find_port_cmd
     from arm101.cli._commands import learn as _learn_cmd
     from arm101.cli._commands import overview as _overview_cmd
+    from arm101.cli._commands import set_motor_id as _set_motor_id_cmd
     from arm101.cli._commands import setup_motors as _setup_motors_cmd
     from arm101.cli._commands import whoami as _whoami_cmd
 
@@ -92,6 +95,9 @@ def _build_parser() -> argparse.ArgumentParser:
     _doctor_cmd.register(sub)
     _find_port_cmd.register(sub)
     _calibrate_cmd.register(sub)
+    _calibrate_motor_cmd.register(sub)
+    _set_motor_id_cmd.register(sub)
+    _center_motor_cmd.register(sub)
     _setup_motors_cmd.register(sub)
     _cli_group.register(sub)
     # Register your own noun groups here:

arm101_cli-0.6.0/arm101/cli/_commands/calibrate_motor.py

@@ -0,0 +1,329 @@
+"""``arm101 calibrate-motor`` — identify a single connected motor and catalog it.
+
+Before an SO-101 is assembled, each Feetech servo is connected to the computer
+**one at a time** and identified.  This verb detects the single connected
+STS3215 (auto-skipping busy or non-motor serial ports so it never grabs an
+unrelated device such as a Reachy daemon), shows the operator the motor's full
+read-only register snapshot, then records three operator-supplied spec fields —
+**Servo Model**, **Gear Ratio**, and **Corresponding Joint** — keyed by a motor
+label (``F1``..``F6`` follower, ``L1``..``L6`` leader) into the motor catalog
+(:mod:`arm101.hardware.motor_catalog`).
+
+It is **read-only on the motor**: it pings and reads registers, never enabling
+torque, commanding motion, or writing EEPROM.  The human is gated at every input
+(label + the three fields); in ``--auto`` mode the CLI also gates on connecting
+each motor in turn.
+
+Two modes
+---------
+* **manual** (default): register the one motor currently connected.  The label
+  is taken from the optional positional argument or prompted for.
+* **automatic** (``--auto``): walk ``F1``..``F6`` then ``L1``..``L6``, prompting
+  the operator to connect each motor before registering it.
+
+Bus injection seam
+------------------
+:func:`_open_bus` is monkeypatched in tests to inject a
+:class:`~arm101.hardware.bus.FakeBus` without physical hardware.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+from arm101.cli._errors import EXIT_ENV_ERROR, EXIT_USER_ERROR, CliError
+from arm101.cli._output import emit_diagnostic, emit_result
+from arm101.hardware import ports
+from arm101.hardware.bus import FeetechBus, MotorBus
+from arm101.hardware.motor_catalog import MotorEntry, catalog_path, save_entry
+
+#: STS3215 model number — used to confirm a responding device is really a servo.
+_STS3215_MODEL = 777
+
+#: Automatic-mode walk order: follower F1..F6 then leader L1..L6.
+_AUTO_LABELS = [f"F{i}" for i in range(1, 7)] + [f"L{i}" for i in range(1, 7)]
+
+
+# ---------------------------------------------------------------------------
+# Bus injection seam (monkeypatched in tests)
+# ---------------------------------------------------------------------------
+
+
+def _open_bus(port: str) -> MotorBus:
+    """Open and return a :class:`FeetechBus` for *port* (tests patch this)."""
+    bus = FeetechBus(port)
+    bus.open()
+    return bus
+
+
+# ---------------------------------------------------------------------------
+# Stdin prompting
+# ---------------------------------------------------------------------------
+
+
+def _prompt(message: str, *, default: str | None = None, required: bool = False) -> str:
+    """Write *message* to stderr, read one line from stdin, return the answer.
+
+    EOF (no input) raises ``CliError(EXIT_ENV_ERROR)`` — this command is
+    interactive and must not hang or silently proceed.  A blank answer falls
+    back to *default*; if *required* and still blank, raises a user error.
+    """
+    suffix = f" [{default}]" if default else ""
+    emit_diagnostic(f"{message}{suffix}: ")
+    line = sys.stdin.readline()
+    if line == "":  # EOF
+        raise CliError(
+            code=EXIT_ENV_ERROR,
+            message="No input available; calibrate-motor is interactive.",
+            remediation="Run it in a terminal and answer the prompts (or pipe answers via stdin).",
+        )
+    answer = line.strip()
+    if not answer and default is not None:
+        return default
+    if not answer and required:
+        raise CliError(
+            code=EXIT_USER_ERROR,
+            message=f"{message} is required.",
+            remediation="Re-run and provide a value.",
+        )
+    return answer
+
+
+# ---------------------------------------------------------------------------
+# Port + motor detection
+# ---------------------------------------------------------------------------
+
+
+def _candidate_ports() -> list[str]:
+    """Real (symlink-resolved, de-duplicated) candidate serial ports."""
+    canon: list[str] = []
+    seen: set[str] = set()
+    for p in ports.enumerate_ports():  # raises CliError on macOS/Windows
+        real = os.path.realpath(p)
+        if real not in seen:
+            seen.add(real)
+            canon.append(real)
+    return canon
+
+
+def _model_of(bus: MotorBus, motor: int) -> int | None:
+    """Return *motor*'s model number, or None if it cannot be read."""
+    try:
+        return int(bus.read_info(motor).get("model", -1))
+    except CliError:
+        return None
+
+
+def _detect_one_motor(args: argparse.Namespace) -> tuple[MotorBus, str, int]:
+    """Return an open bus, its port, and the single STS3215 motor ID found.
+
+    Ports that cannot be opened (busy — e.g. another robot's daemon) are
+    skipped, so an unrelated device never blocks detection.  Exactly one motor
+    on exactly one port is required; anything else is a clear CliError.
+    """
+    target = getattr(args, "port", None)
+    ports_to_try = [os.path.realpath(target)] if target else _candidate_ports()
+
+    matches: list[tuple[MotorBus, str, list[int]]] = []
+    for port in ports_to_try:
+        try:
+            bus = _open_bus(port)
+        except CliError:
+            continue  # busy / unopenable — skip (ignores other devices)
+        sts_ids = [i for i in bus.scan() if _model_of(bus, i) == _STS3215_MODEL]
+        if sts_ids:
+            matches.append((bus, port, sts_ids))
+        else:
+            bus.close()
+
+    if not matches:
+        raise CliError(
+            code=EXIT_ENV_ERROR,
+            message="No STS3215 servo detected on any serial port.",
+            remediation=(
+                "Connect the motor and its external power (STS3215 needs V+, not USB "
+                "alone), then retry. Use --port to target a specific device."
+            ),
+        )
+    if len(matches) > 1:
+        found_ports = [p for _, p, _ in matches]
+        for bus, _, _ in matches:
+            bus.close()
+        raise CliError(
+            code=EXIT_USER_ERROR,
+            message=f"Motors found on multiple ports: {found_ports}.",
+            remediation="Connect one motor at a time, or pass --port to choose.",
+        )
+
+    bus, port, ids = matches[0]
+    if len(ids) != 1:
+        bus.close()
+        raise CliError(
+            code=EXIT_USER_ERROR,
+            message=f"Expected exactly one motor on {port}, found ids {ids}.",
+            remediation="Connect a single motor at a time for per-motor registration.",
+        )
+    return bus, port, ids[0]
+
+
+# ---------------------------------------------------------------------------
+# Presentation
+# ---------------------------------------------------------------------------
+
+
+def _show_info(info: dict[str, int], port: str) -> None:
+    """Emit the full read-only register snapshot to stderr for operator review."""
+    pos = info["present_position"]
+    verified = (
+        "Feetech STS3215 (model 777) ✓"
+        if info["model"] == _STS3215_MODEL
+        else f"UNKNOWN servo (model {info['model']}) ✗"
+    )
+    lines = [
+        "Detected motor (read-only — no torque, motion, or EEPROM writes):",
+        f"  port             : {port}",
+        f"  verified         : {verified}",
+        f"  id               : {info['id']}",
+        f"  model            : {info['model']}",
+        f"  firmware         : {info['firmware_major']}.{info['firmware_minor']}",
+        f"  baud index       : {info['baud_index']}",
+        f"  present position : {pos} (~{pos * 360.0 / 4096.0:.1f} deg)",
+        f"  angle limits     : {info['min_angle']}..{info['max_angle']}",
+        f"  torque enable    : {'ON' if info['torque_enable'] else 'OFF'}",
+        f"  voltage          : {info['present_voltage'] / 10.0:.1f} V",
+        f"  temperature      : {info['present_temperature']} C",
+        f"  load / speed     : {info['present_load']} / {info['present_speed']}",
+    ]
+    emit_diagnostic("\n".join(lines))
+
+
+def _entry_payload(entry: MotorEntry, info: dict[str, int]) -> dict:
+    return {
+        "label": entry.label,
+        "servo_model": entry.servo_model,
+        "gear_ratio": entry.gear_ratio,
+        "joint": entry.joint,
+        "port": entry.port,
+        "recorded": entry.recorded,
+        "detected": {
+            "id": info["id"],
+            "model": info["model"],
+            "firmware": f"{info['firmware_major']}.{info['firmware_minor']}",
+            "voltage_v": round(info["present_voltage"] / 10.0, 1),
+            "temperature_c": info["present_temperature"],
+            "present_position": info["present_position"],
+        },
+    }
+
+
+# ---------------------------------------------------------------------------
+# Registration of one motor
+# ---------------------------------------------------------------------------
+
+
+def _register_one(args: argparse.Namespace, label: str | None) -> dict:
+    """Detect, display, gate on operator input, and catalog one motor."""
+    bus, port, motor_id = _detect_one_motor(args)
+    try:
+        info = bus.read_info(motor_id)
+    finally:
+        bus.close()
+
+    _show_info(info, port)
+
+    if not label:
+        label = _prompt("Which motor is this? (e.g. F1, L2)", required=True)
+
+    detected_model = f"STS3215 (model {info['model']})"
+    servo_model = _prompt("Servo Model", default=detected_model)
+    gear_ratio = _prompt("Gear Ratio (e.g. 1:191)", required=True)
+    joint = _prompt("Corresponding Joint (e.g. shoulder_pan)", required=True)
+
+    entry = save_entry(
+        MotorEntry(
+            label=label,
+            servo_model=servo_model,
+            gear_ratio=gear_ratio,
+            joint=joint,
+            detected_id=int(info["id"]),
+            detected_model=int(info["model"]),
+            port=port,
+        )
+    )
+    return _entry_payload(entry, info)
+
+
+# ---------------------------------------------------------------------------
+# Command handler
+# ---------------------------------------------------------------------------
+
+
+def cmd_calibrate_motor(args: argparse.Namespace) -> None:
+    """Manual (one motor) or automatic (``--auto``, F1..F6 then L1..L6) registration."""
+    json_mode = bool(getattr(args, "json", False))
+    results: list[dict] = []
+
+    if getattr(args, "auto", False):
+        for label in _AUTO_LABELS:
+            answer = _prompt(
+                f"Connect the {label} motor ONLY, then press Enter (or 's' to skip, 'q' to finish)"
+            )
+            if answer.lower() == "q":
+                break
+            if answer.lower() == "s":
+                emit_diagnostic(f"Skipped {label}.")
+                continue
+            results.append(_register_one(args, label))
+    else:
+        results.append(_register_one(args, getattr(args, "label", None)))
+
+    _emit_results(results, json_mode=json_mode)
+
+
+def _emit_results(results: list[dict], *, json_mode: bool) -> None:
+    path = str(catalog_path())
+    if json_mode:
+        emit_result({"motors": results, "catalog": path}, json_mode=True)
+        return
+    lines = []
+    for r in results:
+        lines.append(
+            f"Registered {r['label']}: {r['servo_model']} | gear {r['gear_ratio']} "
+            f"| joint {r['joint']} (motor id {r['detected']['id']})"
+        )
+    if not lines:
+        lines.append("No motors registered.")
+    lines.append(f"Catalog: {path}")
+    emit_result("\n".join(lines), json_mode=False)
+
+
+# ---------------------------------------------------------------------------
+# Registration
+# ---------------------------------------------------------------------------
+
+
+def register(sub: "argparse._SubParsersAction") -> None:
+    """Register the ``calibrate-motor`` subcommand on *sub*."""
+    p = sub.add_parser(
+        "calibrate-motor",
+        help="Identify a single connected motor (read-only) and record its model/gear/joint.",
+    )
+    p.add_argument(
+        "label",
+        nargs="?",
+        help="Motor label, e.g. F1 or L2 (manual mode). Omit to be prompted.",
+    )
+    p.add_argument(
+        "--auto",
+        action="store_true",
+        help="Automatic mode: walk F1..F6 then L1..L6, prompting to connect each.",
+    )
+    p.add_argument(
+        "--port",
+        default=None,
+        help="Serial port of the motor (default: auto-detect, skipping busy/non-motor ports).",
+    )
+    p.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    p.set_defaults(func=cmd_calibrate_motor)

arm101_cli-0.6.0/arm101/cli/_commands/center_motor.py

@@ -0,0 +1,182 @@
+"""``arm101 center-motor`` — drive a single connected STS3215 servo to home position.
+
+Before mounting a horn on a Feetech STS3215 servo, the motor must be parked at
+its centre (default encoder tick 2048, mid-range of the 12-bit ``[0, 4095]``
+scale, ≈180°) so the horn aligns with the known zero point.  This verb detects
+the single connected servo (reusing the calibrate-motor seam so busy or
+non-motor ports are never grabbed), shows the operator a read-only snapshot,
+then **gates hard** — a typed ``yes`` is required before any bus write occurs.
+
+On confirmation the sequence is:
+
+1. Enable torque (Torque_Enable register 40).
+2. Command the goal position (Goal_Position register 42).
+3. Relax torque (Torque_Enable → 0) — unless ``--keep-torque`` is given.
+
+This is **commanded motion**.  Running it without a clear workspace or without
+the motor secured is a hardware risk.  The gate guarantees that a non-interactive
+invocation (e.g. a CI run with no stdin) can never silently move the motor.
+
+Bus injection seam
+------------------
+:func:`~arm101.cli._commands.calibrate_motor._open_bus` and
+:func:`~arm101.cli._commands.calibrate_motor._candidate_ports` are
+monkeypatched on ``calibrate_motor`` in tests.  Because
+:func:`~arm101.cli._commands.calibrate_motor._detect_one_motor` (imported
+here) resolves those names in its own module scope, patching ``calibrate_motor``
+is sufficient — no re-export from this module is needed.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from arm101.cli._commands.calibrate_motor import (
+    _detect_one_motor,
+    _prompt,
+    _show_info,
+)
+from arm101.cli._errors import EXIT_ENV_ERROR, CliError
+from arm101.cli._output import emit_diagnostic, emit_result
+
+# ---------------------------------------------------------------------------
+# Gate helper
+# ---------------------------------------------------------------------------
+
+
+def _require_tty() -> None:
+    """Refuse to run unless stdin is an interactive terminal.
+
+    Commanded motion must never be driven by piped/redirected input: a non-TTY
+    stdin could otherwise feed ``yes`` and satisfy the confirmation gate
+    non-interactively (a CI run or ``echo yes | …``).  Checked before the bus is
+    opened so a non-interactive invocation touches no hardware.
+    """
+    if not sys.stdin.isatty():
+        raise CliError(
+            code=EXIT_ENV_ERROR,
+            message="center-motor requires an interactive terminal (stdin is not a TTY).",
+            remediation=(
+                "This verb commands motor motion — run it without pipes or "
+                "redirects so the confirmation is answered by a human."
+            ),
+        )
+
+
+def _confirm(question: str) -> bool:
+    """Ask *question* via :func:`_prompt` and return True iff the answer is ``yes``.
+
+    A non-interactive stdin (EOF) causes :func:`_prompt` to raise
+    ``CliError(EXIT_ENV_ERROR)`` — the motor is never moved silently.
+    """
+    answer = _prompt(question)
+    return answer.strip().lower() == "yes"
+
+
+# ---------------------------------------------------------------------------
+# Command handler
+# ---------------------------------------------------------------------------
+
+
+def cmd_center_motor(args: argparse.Namespace) -> None:
+    """Park the single connected STS3215 at the home position for horn mounting."""
+    json_mode = bool(getattr(args, "json", False))
+    target = int(getattr(args, "position", 2048))
+    keep_torque = bool(getattr(args, "keep_torque", False))
+
+    _require_tty()
+
+    bus, port, motor_id = _detect_one_motor(args)
+    try:
+        info = bus.read_info(motor_id)
+        _show_info(info, port)
+
+        deg = target * 360.0 / 4096.0
+        emit_diagnostic(
+            f"⚠ This will ENABLE TORQUE and MOVE motor {motor_id} on {port}"
+            f" to position {target} (~{deg:.0f}°). Clear the workspace."
+        )
+
+        confirmed = _confirm("Type 'yes' to proceed, anything else to abort")
+        if not confirmed:
+            if json_mode:
+                emit_result(
+                    {
+                        "aborted": True,
+                        "motor": motor_id,
+                        "port": port,
+                        "position": target,
+                        "moved": False,
+                    },
+                    json_mode=True,
+                )
+            else:
+                emit_result("Aborted; motor not moved.", json_mode=False)
+            return
+
+        bus.enable_torque(motor_id, True)
+        # Once torque is on, always relax it (unless --keep-torque) even if the
+        # goal-position write raises — otherwise a failed/aborted move would
+        # leave the servo holding torque.
+        try:
+            bus.write_goal_position(motor_id, target)
+        finally:
+            if not keep_torque:
+                bus.enable_torque(motor_id, False)
+        torque_relaxed = not keep_torque
+
+    finally:
+        bus.close()
+
+    torque_state = "relaxed" if torque_relaxed else "still enabled"
+    if json_mode:
+        emit_result(
+            {
+                "motor": motor_id,
+                "port": port,
+                "position": target,
+                "torque_relaxed": torque_relaxed,
+            },
+            json_mode=True,
+        )
+    else:
+        emit_result(
+            f"Centered motor {motor_id} to {target} on {port} (torque {torque_state}).",
+            json_mode=False,
+        )
+
+
+# ---------------------------------------------------------------------------
+# Registration
+# ---------------------------------------------------------------------------
+
+
+def register(sub: "argparse._SubParsersAction") -> None:
+    """Register the ``center-motor`` subcommand on *sub*."""
+    p = sub.add_parser(
+        "center-motor",
+        help=(
+            "Drive a single connected motor to the home position (default 2048) "
+            "for horn mounting. Gated: requires typed confirmation before moving."
+        ),
+    )
+    p.add_argument(
+        "--port",
+        default=None,
+        help="Serial port of the motor (default: auto-detect, skipping busy/non-motor ports).",
+    )
+    p.add_argument(
+        "--position",
+        type=int,
+        default=2048,
+        help="Target encoder tick [0–4095] (default: 2048 = mid-range / home).",
+    )
+    p.add_argument(
+        "--keep-torque",
+        action="store_true",
+        default=False,
+        help="Leave torque enabled after centering (default: relax after move).",
+    )
+    p.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    p.set_defaults(func=cmd_center_motor)