Diagnose a problem
Result: choose a symptom-based check without randomly changing calibration, gains or firmware. Support the mechanism and remove power before wiring changes where required.
Connection or motor-list problems
| Symptom | Check | Do not immediately conclude |
|---|---|---|
| Port cannot open | Port name, USB data cable, access permissions and another process or browser using the adapter | That firmware needs replacing |
| Empty discovery list | Motor power, wiring and selected baud rate | That every motor is faulty |
| Missing IDs or conflicting replies | Unique IDs; inspect devices individually if necessary | That rescanning can distinguish duplicate IDs |
| Unexpected/missing controller IDs | Physical bus, profiles, joints and recorded IDs | That replay can simply ignore another attached motor |
Discovery checks the selected baud rate, not every rate automatically. If communication works but a command is rejected, preserve the complete error and check its conditions below.
Firmware and settings
| Symptom | Next action |
|---|---|
| Manifest, size or SHA-256 error | Obtain the original matching pair and run offline inspect |
Unsupported model bytes |
Check image/device compatibility; do not edit the permitted models |
| Torque-off / lock / no-alarm requirement | Support the mechanism and check torque, settings lock and alarm cause |
| Transfer finished, application verification failed | Preserve backups/flash/; inspect ID, baud and settings before reflashing |
| Factory flash exit code 2 | Factory firmware responded but settings changed; repair settings rather than immediately reflashing |
See recovery for procedures and backup formats.
Calibration, models and startup
| Symptom | Next action |
|---|---|
crosses zero |
Correct the physical reference so the complete travel fits within 0–4095 after reference capture at 2048 |
| One incorrect measured range | Use reset ID to sweep that joint again; this does not change offsets |
Calibration report not verified |
Finish both stages; cancelling does not undo saved offsets |
encoderCalibration mismatch |
Check model provenance and actual offsets/resolution/reverse; do not copy another arm’s offsets |
| Position outside saved limits | Support the arm, release torque and return it inside the reviewed range; check limits |
cappedTargets in preview |
Compare recording and current limits; re-record after changing calibration |
| Unexpected approach to the first pose | Review the path from the present position, which is also a commanded movement |
Movement and stopping
Oscillation, overheating, large tracking error or prolonged saturation require stopping the experiment and checking load, effort limits and settings. Do not increase every gain together. Follow the tuning sequence.
Powered hold after program completion can be normal for Extension replay or teleoperation. Firmware can continue its last target after the host stops. Consult the stop-behavior table; Ctrl+C is not a universal emergency stop.
holdRetained: true after an error means the controller retained a verified stationary hold after missing a gravity-update deadline. The run still failed and does not resume automatically. Retained effort is not an actively updating model.
Keep evidence
Keep software version/commit, ID and baud, exact command, controller and profiles, model and calibration, mounting/payload details, full error, logs/motion/ or tools/tuning/logs/<run>/, and any relevant flash report. Distinguish intended commands, transmission and confirmed feedback counters.
Windows test failures
In the audited source revision, three full-suite npm test cases fail in the Windows environment used here: two expect Unix path separators and one requires symlink creation. These are documented limitations of this test run, not evidence of a hardware fault. Do not assume unrelated failures have the same cause. These procedures do not require weakening PowerShell policy or changing system permissions to satisfy those tests.
Documentation home · Source revision: a995f77. Extension 9.0.