Tune and validate control

Result: accept settings against measured criteria rather than one successful movement. First verify calibration, the initial motion path, profiles and any gravity model.

1. Prepare a baseline plan

cp tools/tuning/example.json tools/tuning/plan.local.json
cp tools/tuning/controller.example.json tools/tuning/controller.local.json

Copy-Item tools/tuning/example.json tools/tuning/plan.local.json
Copy-Item tools/tuning/controller.example.json tools/tuning/controller.local.json

In tools/tuning/plan.local.json, set config to controller.local.json, stage to baseline and candidates to []. The source example contains a PID candidate; do not run it unchanged as a baseline measurement.

Set the controller port and profiles, and include every supporting motor in joints as {"followerId": ID}. Remove a copied durationMs: the plan’s batch.maxDurationMs owns the duration budget.

Positions are corrected encoder counts. After recalibration, the same numbers may represent different physical positions. Supporting joints keep existing hold targets; the tool does not automatically reposition the whole arm.

2. Separate the three commands

Inspect files and estimated bus use without connecting:

npm run tune -- inspect tools/tuning/plan.local.json

npm.cmd run tune -- inspect tools/tuning/plan.local.json

Read firmware, calibration, limits and profiles without changing motors:

npm run tune -- preflight tools/tuning/plan.local.json

npm.cmd run tune -- preflight tools/tuning/plan.local.json

Run the batch with movement:

npm run tune -- run tools/tuning/plan.local.json

npm.cmd run tune -- run tools/tuning/plan.local.json

Do not run if preflight reveals unexpected clipped targets, a model error or an endpoint pair collapsed to one position. The batch moves probeId; other motors must retain a reviewed supporting pose.

3. Tune in order

1. Baseline: initial movements and holds without candidates; establish repeatability and investigate alarms.
2. Gravity: check a model across poses, directions and at least two speeds. This stage collects data without changing gains.
3. Velocity: compare directional feedforward using steady movement.
4. PID: compare P, D and filtering across loads; use longer holds to expose oscillation.
5. Integral: introduce only for a lasting error; test gain and limit together, including small reversals.
6. Motion: hold gains fixed while comparing acceleration and ramp time.
7. Combined motion: replay a whole-arm path; isolated joint tuning does not validate coupled movement.
8. Validation: freeze settings and check required speeds, accelerations, payloads and extended holds.

The stage restricts candidate fields. Baseline, gravity and validation do not change settings. Total output limits remain explicitly configured rather than automatically tuned.

4. Interpret results

Each tools/tuning/logs/<run>/ directory contains events.ndjson and summary.json. Review completion status, baselines before and after the batch, independent validation pairs and every acceptance criterion. An incomplete or failed batch provides no recommendation. Baseline drift can make a comparison inconclusive.

Metrics cover moving tracking RMS, steady error and span, overshoot, settling time, total response time and saturation fraction. Settling requires a continuous interval inside the band; an early crossing is insufficient. Short holds cannot establish the absence of slow oscillation.

Normal completion restores the configured baseline and retains hold. Ctrl+C during tuning attempts torque-off, unlike Extension replay. Support the mechanism before interruption; a killed process or disconnected bus can leave the previous hold active.

5. Save accepted settings

The tool does not automatically install a winning candidate. After review, update local profiles and keep them with calibration, model, payload/mounting details and validation logs. The export below uses the named-pose controller from the first-motion guide. Update its profiles to the accepted values. To use apply, first add this top-level joints property to tools/poses/controller.local.json, adjusting the IDs to match the physical arm:

"joints": [
  {"followerId": 1}, {"followerId": 2}, {"followerId": 3},
  {"followerId": 4}, {"followerId": 5}, {"followerId": 6}
]

This is a property fragment, not a complete JSON file: add a comma between it and the adjacent property. Export to a new directory without connecting to motors:

npm run tune -- export tools/poses/controller.local.json accepted-controller

npm.cmd run tune -- export tools/poses/controller.local.json accepted-controller

Use a directory that does not exist yet. Export does not certify settings. To apply the exported controller without replay, it must contain joints for all followers. This command changes control and enables hold:

npm run tune -- apply accepted-controller/controller.json

npm.cmd run tune -- apply accepted-controller/controller.json

A profile change can briefly release torque. Ordinary replay applies its own configuration and does not require a separate apply command.

Documentation home · Source revision: a995f77. Extension 9.0.