Skip to content

Commit fb29280

Browse files
committed
Apply shared servo register defaults during full calibration
1 parent a982682 commit fb29280

5 files changed

Lines changed: 53 additions & 6 deletions

File tree

‎setup/README.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -85,3 +85,13 @@ See [coordinate conventions](src/so101_setup/COORDINATES.md),
8585
[official LeRobot guide](https://huggingface.co/docs/lerobot/so101).
8686
Use an external control application for powered operation. This workflow still
8787
requires validation on the particular physical arm.
88+
89+
A full calibration save sets maximum acceleration to 254 on all six motors,
90+
gripper maximum torque to 500, and gripper protection current to 250. These are
91+
raw register values. A single-joint recalibration leaves them alone.
92+
93+
For an arm that needs different values, manually add `servo-overrides.toml`
94+
beside its `setup.toml`. Set only the keys it needs:
95+
`maximum_acceleration`, `gripper_max_torque_limit`, or
96+
`gripper_protection_current`. The tool applies them on the next full save.
97+
New arm setups do not create this file.

‎setup/src/so101_setup/calibration.py‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,9 @@
4242
"i_coefficient",
4343
"d_coefficient",
4444
"return_delay_time",
45+
"maximum_acceleration",
46+
"max_torque_limit",
47+
"protection_current",
4548
"lock",
4649
)
4750

@@ -656,6 +659,17 @@ def save(self, *, model_verified: bool) -> None:
656659
updates["operating_mode"] = [self.bus.definition.operating_modes["position"]] * 6
657660
if self.setup.servos.expected_return_delay_time is not None:
658661
updates["return_delay_time"] = [self.setup.servos.expected_return_delay_time] * 6
662+
servo_registers = self.setup.servo_registers
663+
updates["maximum_acceleration"] = [servo_registers.maximum_acceleration] * 6
664+
# The bus is in joint order, including when the physical IDs are reversed.
665+
updates["max_torque_limit"] = [
666+
*registers["max_torque_limit"][:5],
667+
servo_registers.gripper_max_torque_limit,
668+
]
669+
updates["protection_current"] = [
670+
*registers["protection_current"][:5],
671+
servo_registers.gripper_protection_current,
672+
]
659673
calibration_bytes = CALIBRATION_ADAPTER.dump_json(entries, indent=2)
660674
configuration_path = self.store.configuration_path(self.directory)
661675
result = ArmSetup.model_validate(

‎setup/src/so101_setup/configuration.py‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,12 @@ def require_distinct_endpoints(self) -> Self:
5454
return self
5555

5656

57+
class ServoRegisterSettings(SetupSection):
58+
maximum_acceleration: Annotated[int, Field(ge=0, le=254)] = 254
59+
gripper_max_torque_limit: Annotated[int, Field(ge=0, le=1000)] = 500
60+
gripper_protection_current: Annotated[int, Field(ge=0, le=310)] = 250
61+
62+
5763
class ServoSettings(SetupSection):
5864
# Starting configuration, not an empirically qualified tune for every arm.
5965
expected_position_gains: PositionGains = Field(default_factory=lambda: [16, 0, 32])
@@ -68,6 +74,7 @@ class ArmSetup(SetupSection):
6874
alignment: ModelAlignment = Field(default_factory=ModelAlignment)
6975
gripper: GripperEndpoints = Field(default_factory=GripperEndpoints)
7076
servos: ServoSettings = Field(default_factory=ServoSettings)
77+
servo_registers: ServoRegisterSettings = Field(default_factory=ServoRegisterSettings)
7178

7279
def motor_ids_in_joint_order(self) -> list[int]:
7380
return list(MOTOR_IDS) if self.motor_id_order == "ascending" else MOTOR_IDS[::-1]

‎setup/src/so101_setup/storage.py‎

Lines changed: 13 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66

77
import tomli_w
88

9-
from .configuration import ArmSetup, ModelVariant, ServoSettings
9+
from .configuration import ArmSetup, ModelVariant, ServoRegisterSettings, ServoSettings
1010

1111

1212
class SetupStore(Protocol):
@@ -32,27 +32,34 @@ def load(self, directory: Path, serial: str) -> ArmSetup:
3232
"This directory contains a host profile. Use its setup adapter or select a new standalone setup directory."
3333
)
3434
setup = ArmSetup(serial=serial, model_variant=self.default_model_variant)
35-
return self.with_servo_defaults(setup)
35+
return self.with_servo_defaults(directory, setup)
3636
document = tomllib.loads(path.read_text())
3737
setup = ArmSetup.model_validate(document)
3838
if setup.serial != serial:
3939
raise ValueError(f"Setup serial {setup.serial} does not match USB controller {serial}")
40-
return self.with_servo_defaults(setup)
40+
return self.with_servo_defaults(directory, setup)
4141

4242
@staticmethod
43-
def with_servo_defaults(setup: ArmSetup) -> ArmSetup:
43+
def with_servo_defaults(directory: Path, setup: ArmSetup) -> ArmSetup:
4444
shoulder_id, elbow_id = (2, 3) if setup.motor_id_order == "ascending" else (5, 4)
45+
override_path = directory / "servo-overrides.toml"
46+
register_settings = (
47+
ServoRegisterSettings.model_validate(tomllib.loads(override_path.read_text()))
48+
if override_path.exists()
49+
else ServoRegisterSettings()
50+
)
4551
return setup.model_copy(
4652
update={
53+
"servo_registers": register_settings,
4754
"servos": ServoSettings(
4855
expected_position_gains_by_motor={
4956
shoulder_id: [32, 0, 32],
5057
elbow_id: [32, 0, 32],
5158
}
52-
)
59+
),
5360
}
5461
)
5562

5663
def encode(self, directory: Path, setup: ArmSetup) -> bytes:
57-
document = setup.model_dump(mode="json", exclude={"servos"})
64+
document = setup.model_dump(mode="json", exclude={"servos", "servo_registers"})
5865
return tomli_w.dumps(document).encode()

‎setup/tests/test_calibration.py‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,9 @@ def __init__(self, motor_ids: list[int] | None = None) -> None:
4444
"i_coefficient": [0] * 6,
4545
"d_coefficient": [32] * 6,
4646
"return_delay_time": [250] * 6,
47+
"maximum_acceleration": [50] * 6,
48+
"max_torque_limit": [1000] * 6,
49+
"protection_current": [310] * 6,
4750
"lock": [0] * 6,
4851
}
4952
self.writes: list[tuple[int, str, int]] = []
@@ -118,6 +121,10 @@ def test_draft_is_read_only_and_save_creates_a_standalone_configuration(
118121
assert (session.state.backup / "registers.json").is_file()
119122
assert bus.registers["p_coefficient"] == [16, 32, 32, 16, 16, 16]
120123
assert bus.registers["return_delay_time"] == [0] * 6
124+
assert bus.registers["maximum_acceleration"] == [254] * 6
125+
assert bus.registers["max_torque_limit"] == [1000] * 5 + [500]
126+
assert bus.registers["protection_current"] == [310] * 5 + [250]
127+
assert not (session.directory / "servo-overrides.toml").exists()
121128
assert bus.registers["torque_enable"] == [0] * 6
122129
assert not any(register in {"torque_enable", "goal_position"} for _, register, _ in bus.writes)
123130
assert bus.closed
@@ -212,6 +219,7 @@ def test_matching_saved_calibration_skips_manual_steps_and_preserves_tuned_endpo
212219
assert "servos" not in document
213220
document["servos"] = {"expected_position_gains_by_motor": {"2": [24, 0, 32]}}
214221
(session.directory / "setup.toml").write_text(tomli_w.dumps(document))
222+
(session.directory / "servo-overrides.toml").write_text("maximum_acceleration = 100\n")
215223
setup = NativeSetupStore().load(session.directory, "ARM_A")
216224
writes_before_reconnect = list(bus.writes)
217225
reconnected = CalibrationSession(setup, session.directory, session.calibration_root, bus)
@@ -223,6 +231,7 @@ def test_matching_saved_calibration_skips_manual_steps_and_preserves_tuned_endpo
223231
assert saved_setup.gripper.open_position_radians == 1.0
224232
assert saved_setup.servos.expected_position_gains_by_motor[2] == [32, 0, 32]
225233
assert bus.registers["p_coefficient"][1] == 32
234+
assert bus.registers["maximum_acceleration"] == [100] * 6
226235
assert "servos" not in tomllib.loads((session.directory / "setup.toml").read_text())
227236

228237

0 commit comments

Comments
 (0)