Recovery and factory firmware

Result: choose the correct recovery procedure and verify settings before motion. Start with connection diagnostics: a wrong port or baud rate does not require bootloader recovery.

Choose a procedure

Ordinary settings restoration

Isolate the motor, support the mechanism, turn torque off, lock writes and clear the cause of alarms. Use the JSON created by npm run settings -- backup:

npm run settings -- restore --port "$SERVO_PORT" --id 1 --file tools/settings/backups/servo-1-before-flash.json

npm.cmd run settings -- restore --port "$env:SERVO_PORT" --id 1 --file tools/settings/backups/servo-1-before-flash.json

--id and --baud describe the current connection, not necessarily the backed-up values. The tool checks the model, writes changed settings, follows ID/baud changes and verifies readback. It never enables torque or sends movement commands. Partial changes can remain after a failure; restoration is not atomic.

This command does not repair the factory reset template and does not accept Python settings.py backups.

Return to factory firmware

Only use this for matching SCServo21-GD32-TTL 3.10 hardware. The source includes its image and manifest in tools/flash/factory/. Isolate the servo because factory startup may change its ID to 1 and cause a bus conflict.

tools/flash/.venv/bin/python tools/flash/flash.py flash --manifest tools/flash/factory/release.json --port "$SERVO_PORT" --id 1

.\tools\flash\.venv\Scripts\python.exe tools/flash/flash.py flash --manifest tools/flash/factory/release.json --port "$env:SERVO_PORT" --id 1

Use the current ID and confirm FLASH. Keep power connected during normal transfer. Afterwards the tool checks the previous connection, then ID 1 at 1,000,000 baud if necessary, and reports the working connection. Exit code 2 means factory firmware responded but settings changed.

Repair settings after returning to factory software even if they initially look correct: firmware can use built-in defaults when stored settings are invalid.

Bootloader recovery

Connect only the intended servo. Recovery does not address by ID and cannot check the current model or back up settings before upload. This example recovers matching factory 3.10:

tools/flash/.venv/bin/python tools/flash/flash.py recover --manifest tools/flash/factory/release.json --port "$SERVO_PORT" --id 1

.\tools\flash\.venv\Scripts\python.exe tools/flash/flash.py recover --manifest tools/flash/factory/release.json --port "$env:SERVO_PORT" --id 1

Confirm the operation. Power-cycle the servo only when prompted, leaving the USB adapter connected. The tool waits up to 60 seconds for the bootloader. Specify the ID/baud expected after recovery. Recovery is not guaranteed; preserve output and check hardware if the bootloader does not respond.

Do not apply recovery’s power-cycle step to ordinary addressed flashing.

Repair and verify factory settings

After factory flash/recovery, use a Python backup from that same motor before settings were lost, or a normal flash report containing before_registers_hex. The Node.js backup format is not accepted. This example assumes the current ID is 1:

tools/flash/.venv/bin/python tools/flash/settings.py restore --port "$SERVO_PORT" --id 1 --file backups/servo-1-factory-recovery.json

.\tools\flash\.venv\Scripts\python.exe tools/flash/settings.py restore --port "$env:SERVO_PORT" --id 1 --file backups/servo-1-factory-recovery.json

Type RESTORE when asked. The tool supports factory 3.10 and rejects detected custom firmware. It restores settings, replaces the reset template, locks writes and restarts the motor. It follows ID/baud changes and verifies without sending motion commands.

Then power-cycle the servo and verify using the restored ID and baud:

tools/flash/.venv/bin/python tools/flash/settings.py verify --port "$SERVO_PORT" --id 1 --file backups/servo-1-factory-recovery.json

.\tools\flash\.venv\Scripts\python.exe tools/flash/settings.py verify --port "$env:SERVO_PORT" --id 1 --file backups/servo-1-factory-recovery.json

Change --id 1 in that final command if the backup restores another ID. Reports are saved under backups/settings/. Keep torque off after an error; repair neither rolls back partial writes nor retries automatically.

Completion check: the application responds, settings verify after power cycling, and physical offset meaning and limits have been reviewed. A backup taken after calibration was lost cannot recover its earlier values. Recalibration requires new pose recordings and renewed model validation.

Documentation home · Source revision: a995f77. Extension 9.0.