Add shelf actuator setup and per-servo calibration controls

docs/actuator-setup.md

@@ -0,0 +1,125 @@
+# Actuator Setup
+
+The first shelf button, **Actuator Setup**, opens a Local USB scanner. Pick the
+USB port and press **Scan**. Each responding servo appears as a separate connected
+node with its own ID, torque state, position, voltage, temperature and settings.
+Discovery and per-servo calibration/testing need only the USB port. A robot
+profile can be selected later for whole-robot calibration and testing.
+Unreadable replies appear as **Unresolved ID** cards while discovery continues.
+These show the attempted address and error; they do not claim a physical servo
+count or confirmed duplicate. Servos sharing an ID must be connected one at a
+time to receive unique IDs before the full chain can be identified separately.
+The workflow is also available under **Templates → Actuator Setup**. Existing
+shelves receive the button first while keeping their other shortcuts; it remains
+customizable through the shelf's settings.
+
+1. Select the USB adapter. Stop other sessions using that adapter, check power
+   and wiring, and press **Scan**. Rescanning refreshes existing servo cards,
+   adds newly discovered IDs and flags previously seen IDs that no longer respond.
+2. To program an ID, support the arm and power off before changing wiring.
+   Connect only the selected actuator, power on and scan again. Enter **New ID**
+   on its servo card and press **Set ID**. Keep the isolated actuator supported;
+   changing its ID retires the assembly's saved calibration.
+3. Power off, reconnect the complete arm and rescan. Resolve missing IDs, open
+   **Calibration and motion test** on a servo card, select the robot profile and
+   press **Calibrate** to record new hand-guided limits and home.
+4. Press **Open motion test** to open that servo in Servo Debug Monitor. Motion
+   requires its explicit **Arm** action, fresh feedback and calibrated limits.
+
+New IDs can be entered directly from 1–253. Robot profiles must match the final
+joint IDs before calibration and motion. Initial ID programming supports STS3215;
+unsupported models remain visible for diagnosis. Discovery is bounded, scans
+IDs 0–253 and preserves torque. Running or reopening this workflow performs
+no physical operation until an operator presses a control.
+
+**Hardware settings** shows a read-only snapshot of the baud rate code, position
+register limits, torque limit, operating mode and EEPROM lock for supported
+models. These raw limits are separate from calibrated safe motion limits.
+Use **Advanced** on the USB scanner to change baud rate or refresh USB ports.
+
+## Per-servo calibration, test slider and saved poses
+
+The card opens on **1. Set ID**, with the New ID field and assignment controls
+visible first. **2. Calibrate / test** contains the motion and capture controls;
+disabled actions explain the missing prerequisite beside the button.
+ID setup uses **New ID → Set ID**, with no confirmation checkboxes or manual
+scan-expiry step. The button is the explicit assignment action after the inline
+isolation/support and calibration-reset instructions. Its owning control scans
+the bus, checks the selected ID and torque, writes, and verifies the result.
+
+Each servo card has **Calibration and test** controls. Capture **Min** and **Max**
+from fresh measurements while the servo is supported and torque is released.
+Either tick direction is accepted. Use comfortable positions clear of mechanical
+stops. Testing uses those exact endpoints as command limits. Existing setup files
+also use their exact captures when reopened; saving retires the old automatic
+20-tick inset. **Home** is optional:
+an interior capture supplies the test origin; otherwise the midpoint is calculated
+for tick-to-angle conversion. This calculated center does not replace a captured
+Home or command the motor to move there. Partial points and named poses can also
+be saved with **Save states**.
+
+Before arming, the slider follows the motor's measured position as you move it
+by hand, showing the full raw tick range even before calibration is saved.
+Read-only feedback refreshes while the panel is visible and pauses while another
+control is working. Connection errors replace the live status. Capture buttons
+read the current position again; captured points are retained as drafts across
+reloads. **Arm** validates and saves a complete range before enabling torque;
+**Save states** is also available separately.
+
+After **Arm**, the slider controls the target. The Arm button is the
+explicit authorization; there is no extra checkbox. Use the calibrated actuator
+with its unique ID and keep the assembly supported. Arm holds the measured
+position anywhere within the captured endpoints, including either endpoint.
+It holds still until a slider command arrives. Each new slider target is sent
+directly to the servo's position controller, within the saved limits. The driver
+sets and verifies a finite 180°/s speed ceiling, acceleration 50 and zero goal
+time in the same RAM command. The servo controls the movement between targets.
+New targets replace pending targets immediately; the managed loop checks
+feedback on a 20 ms cadence, subject to USB latency.
+The UI uses fresh shared feedback for acknowledgements and updates readings
+every 100 ms. **Stop** releases torque and
+ends the session. Closing or hiding the controls stops it; a managed three-second
+lease also releases torque if the UI disconnects. Stale requests and invalid
+feedback disarm the test. STS3215 position mode must be verified before arming.
+
+The slider spans the captured Min/Max ticks and follows their direction, including
+decreasing tick values from Min to Max. Both exact endpoints are reachable targets;
+commands outside them are rejected.
+While calibration controls are open, the card's position and torque fields use
+live feedback; scan-only values are labeled as scan snapshots. Unavailable live
+feedback displays an unknown state instead of an old torque reading.
+
+Enter a **Pose name**, press **Capture pose**, then stop any active test and press
+**Save states**. Captures read measured positions, including while testing;
+they do not save the requested slider value as if it were feedback. Select a
+pose to preview its target before moving. Saved poses outside the calibrated
+range are clamped to that range for testing.
+
+State files live under the robot data directory's `actuator_setups/` folder,
+keyed by USB hardware identity, provider and servo ID, with the actuator model
+recorded. They load when the same servo card is reopened. ID assignment retires
+these files alongside existing assembly calibration. Replacing a same-model
+actuator at the same address requires recapturing calibration; these servos do
+not expose an individual serial identity through this setup protocol. Whole-robot
+profile calibration remains available from the card's expandable controls.
+
+Assignment retires saved calibration files for the selected physical USB
+identity into `calibrations/retired/`, preserving them for review while requiring
+new calibration for the changed assembly. It verifies EEPROM relocking and the
+new ID and keeps uncertain results visible. Each assignment uses a fresh,
+single-use discovery token for legacy clients; the current **Set ID** button
+performs fresh discovery on every click. It never enables torque or commands motion.
+
+## Delivery
+
+Select the USB scanner or a servo card and drag a corner to resize it. The
+controls fill the available space, with scrolling available inside smaller
+cards. Save the workflow to retain the card sizes.
+
+Managed Runtime release decision: **no Runtime release for this workstation
+Local USB workflow**. The editor UI and editor-server control routes run on the
+workstation; the robot and driver changes load through the existing package
+contract. This change does not add managed-device commissioning or modify the
+device source lock. Local verification does not publish a release. A future
+managed-device delivery must verify its actual Software update controls and
+follow the owning package/Runtime release sequence in `AGENTS.md`.

docs/provider-authoring.md

@@ -213,13 +213,70 @@ Use the resolver already defined by the capability:
 
 - Calibration control discovers capability-specific provider registrations and
   opens the implementation selected by the profile.
+- Actuator Setup resolves `_bn_robot_actuator_setup_provider` by the highest unique
+  positive `match_hardware(hardware)` score for the selected USB port. Saved workflows
+  can also select the provider through the profile's joint or calibration binding.
+  `scan(config)` returns normalized `actuators`
+  including `servo_id`, `model`, `model_number`, `assignment_supported`,
+  `torque_enabled`, `raw_position`, `voltage_v`, `temperature_c`,
+  `hardware_error_flags`, `hardware_errors` and `errors`, plus optional `settings`
+  and `settings_errors`. The editor creates an `ActuatorServoSetup` card for each
+  responding ID, connected to the scanner's typed `bus` output. The owning provider's
+  scan can retain unreadable addresses with `discovery_status: unreadable`,
+  `model_number: null`, `assignment_supported: false` and an actionable `errors`
+  list. These records represent uncertain addresses rather than confirmed servos;
+  they preserve partial discovery and cannot authorize writes. The provider's
+  `assign(config, expected, new_id)` rescans under exclusive bus ownership and
+  verifies the ID write and protection state. Optional `release(config, expected)`
+  independently verifies torque off. The robot facade owns expiring single-use
+  confirmation and retirement of hardware-bound calibration. The dedicated ID
+  button uses an explicit `operator_action: assign` request after visible isolation
+  and calibration-reset instructions; its owning control refreshes discovery
+  automatically. Legacy clients retain their confirmation/token contract. Ordinary graph
+  cooks remain inert. See [Actuator Setup](actuator-setup.md).
+- The optional setup callback `read_position(config, servo_id)` performs a bounded,
+  read-only sample of one discovered address and closes its connection. It returns
+  `servo_id`, `reported_id`, `model_number`, `assignment_supported`, `raw_position`,
+  `torque_enabled`, `hardware_error_flags`, `hardware_errors`, `errors`, Unix
+  `sampled_at`, and a raw `position_range` with `min`/`max`. The editor requests
+  samples only while the calibration panel is visible and idle. The facade
+  serializes requests, rejects stale or mismatched feedback, and blocks this path
+  while a motion session owns the bus. It preserves measured values with hardware
+  warnings; calibration capture and arming keep their stricter health checks.
+- Per-actuator setup can expose `build_test_context(config, state, row)` on the
+  same provider. It converts normalized raw Min/Home/Max points into the standard
+  joint-motion profile and calibration context, including `degrees_per_tick`.
+  The facade sorts the two captured endpoints and uses an interior Home or a
+  calculated midpoint as the test origin, retaining all original captures in
+  storage. The Arm button sends `operator_action: arm-test` and
+  `save_calibration: true`; the facade validates hardware and current position,
+  persists the range, then arms. Hold accepts the full captured range; commanded
+  targets retain the inset limits at the driver boundary.
+  Legacy callers still require a prior save.
+  The robot facade persists points and named measured poses by physical USB
+  identity/provider/servo ID. Its managed test uses the existing motion service,
+  fresh feedback and a three-second UI lease. Raw
+  register conversion and model/mode validation stay in the provider.
+  New slider targets wake the controller immediately and replace pending targets.
+  Target acknowledgements and UI status may reuse
+  the worker's feedback for at most 250 ms; motion retains fresh driver checks.
 - Servo motion discovers `_bn_robot_joint_motion_provider` registrations and
   opens only the package/component selected by the profile's `joint_group`,
   `calibration_control`, or `position_feedback` binding. A session supplies
   `sample()`, `hold()`, `command(positions_deg, deadline=...)`, `release()`,
   and `close()`. `hold()` seeds every configured joint from current feedback
   before torque; `command()` verifies freshness, torque, and hardware health at
   the physical driver boundary.
+- Providers with `supports_position_targets: true` also implement
+  `command_position_target(positions_deg, max_velocity_deg_s=..., deadline=...)`.
+  An armed context can select `position_target_mode: true`; the gateway checks
+  this provider capability before holding torque. It sends the latest calibrated
+  destination directly through motion arbitration, with a finite positive speed
+  ceiling enforced by the provider's position controller. The regular `command`
+  path retains software velocity limiting. Feetech setup uses a 180°/s ceiling,
+  validates model/mode, writes acceleration/goal/time/speed together, and checks
+  goal and speed readback. Its hardware warnings, stale-data and release paths
+  apply to both command modes. The mock provider supplies the same target method.
 - Managed attachments synchronize the selected package, build a process
   descriptor from provider configuration, and ask Runtime to start or reuse it.
 - Existing-topic providers remain read-only and use ROS interface checks as