feat(piper): require calibration by default with opt-out mode

- set piper calibration_mode default to required and keep off as explicit opt-out

- remove auto pairing policy and simplify runtime calibration gating

- update README and add test for uncalibrated control when calibration_mode=off
这个提交包含在:
Elvin
2026-03-05 21:49:39 +08:00
父节点 7a9aeb3850
当前提交 294a370657
共有 7 个文件被更改,包括 85 次插入 和 10 次删除

查看文件

@ -207,7 +207,11 @@ So first run `lerobot-setup-can` to confirm CAN interfaces are available:
lerobot-setup-can --mode=setup --interfaces=can0,can1
```
PiPER does not use `lerobot-calibrate`, and if you switch master/follower roles with the flags below, you must power-cycle both arms before enabling.
PiPER calibration is required by default.
If needed, you can disable it with
`--robot.calibration_mode=off` and `--teleop.calibration_mode=off`.
If you switch master/follower roles with the flags below, you must power-cycle both arms before enabling.
```bash
--teleop.set_leader_mode_on_connect=true

查看文件

@ -17,6 +17,7 @@
from dataclasses import dataclass, field
from lerobot.cameras import CameraConfig
from lerobot.utils.piper_sdk import PIPER_CALIBRATION_MODES
from ..config import RobotConfig
@ -49,6 +50,10 @@ class PiperFollowerConfigBase:
# Calibration precision:
# homing_offset/range_min/range_max are stored as "degree * calibration_scale".
calibration_scale: int = 1000
# Calibration policy:
# - required: always require calibration
# - off: never require calibration
calibration_mode: str = "required"
# Gripper forwarding behavior
sync_gripper: bool = True
@ -75,6 +80,8 @@ class PiperFollowerConfig(RobotConfig, PiperFollowerConfigBase):
raise ValueError("`enable_timeout_s` must be >= 0.")
if self.calibration_scale <= 0:
raise ValueError("`calibration_scale` must be > 0.")
if self.calibration_mode not in PIPER_CALIBRATION_MODES:
raise ValueError("`calibration_mode` must be one of: required, off.")
if self.startup_sleep_s < 0:
raise ValueError("`startup_sleep_s` must be >= 0.")
if not (0 <= self.gripper_effort_default <= 5000):

查看文件

@ -30,6 +30,7 @@ from lerobot.utils.piper_sdk import (
get_piper_sdk,
milli_to_unit,
parse_piper_log_level,
should_require_piper_calibration,
unit_to_milli,
)
from lerobot.utils.utils import enter_pressed, move_cursor_up
@ -100,7 +101,7 @@ class PiperFollower(Robot):
should_enable = self.config.enable_on_connect and calibrate
if should_enable and not self._wait_enable(self.config.enable_timeout_s):
logger.warning("Piper follower did not report enabled state before timeout.")
if not self.is_calibrated and calibrate:
if not self.is_calibrated and calibrate and should_require_piper_calibration(self.config.calibration_mode):
logger.info("No piper-follower calibration file found for '%s'. Running lerobot-calibrate flow.", self.id)
self.calibrate()
@ -116,6 +117,9 @@ class PiperFollower(Robot):
logger.info("%s connected.", self)
def _use_uncalibrated_passthrough(self) -> bool:
return not self.is_calibrated and not should_require_piper_calibration(self.config.calibration_mode)
@property
def is_calibrated(self) -> bool:
if not all(key in self.calibration for key in PIPER_CALIB_KEYS):
@ -247,7 +251,7 @@ class PiperFollower(Robot):
@check_if_not_connected
def send_action(self, action: RobotAction) -> RobotAction:
if not self.is_calibrated:
if not self.is_calibrated and not self._use_uncalibrated_passthrough():
raise RuntimeError(
f"{self} is not calibrated. Run `lerobot-calibrate --robot.type=piper_follower --robot.id={self.id}` first."
)
@ -259,7 +263,10 @@ class PiperFollower(Robot):
joint_keys = PIPER_JOINT_ACTION_KEYS
has_all_joints = all(key in action for key in joint_keys)
if has_all_joints:
joint_targets = [self._offset_to_target(key, action[key]) for key in joint_keys]
if self._use_uncalibrated_passthrough():
joint_targets = [action[key] for key in joint_keys]
else:
joint_targets = [self._offset_to_target(key, action[key]) for key in joint_keys]
joint_commands = [unit_to_milli(value) for value in joint_targets]
self.arm.JointCtrl(*joint_commands)
sent_action.update({key: milli_to_unit(raw) for key, raw in zip(joint_keys, joint_commands, strict=True)})
@ -267,7 +274,10 @@ class PiperFollower(Robot):
logger.debug("Ignoring partial Piper joint action. Need all six joint keys to send command.")
if self.config.sync_gripper and "gripper.pos" in action:
gripper_target = self._offset_to_target("gripper.pos", action["gripper.pos"])
if self._use_uncalibrated_passthrough():
gripper_target = action["gripper.pos"]
else:
gripper_target = self._offset_to_target("gripper.pos", action["gripper.pos"])
gripper_pos_raw = unit_to_milli(gripper_target)
self.arm.GripperCtrl(
gripper_pos_raw,

查看文件

@ -16,6 +16,8 @@
from dataclasses import dataclass
from lerobot.utils.piper_sdk import PIPER_CALIBRATION_MODES
from ..config import TeleoperatorConfig
@ -56,6 +58,10 @@ class PiperLeaderConfigBase:
# Calibration precision:
# homing_offset/range_min/range_max are stored as "degree * calibration_scale".
calibration_scale: int = 1000
# Calibration policy:
# - required: always require calibration
# - off: never require calibration
calibration_mode: str = "required"
# Safety behavior on disconnect
disable_on_disconnect: bool = False
@ -73,6 +79,8 @@ class PiperLeaderConfig(TeleoperatorConfig, PiperLeaderConfigBase):
raise ValueError("`enable_timeout_s` must be >= 0.")
if self.calibration_scale <= 0:
raise ValueError("`calibration_scale` must be > 0.")
if self.calibration_mode not in PIPER_CALIBRATION_MODES:
raise ValueError("`calibration_mode` must be one of: required, off.")
if self.startup_sleep_s < 0:
raise ValueError("`startup_sleep_s` must be >= 0.")
if not (0 <= self.gripper_effort_default <= 5000):

查看文件

@ -29,6 +29,7 @@ from lerobot.utils.piper_sdk import (
get_piper_sdk,
milli_to_unit,
parse_piper_log_level,
should_require_piper_calibration,
unit_to_milli,
)
from lerobot.utils.utils import enter_pressed, move_cursor_up
@ -93,7 +94,7 @@ class PiperLeader(Teleoperator):
self.arm.MasterSlaveConfig(0xFC, 0x00, 0x00, 0x00)
time.sleep(0.05)
self.configure()
if not self.is_calibrated and calibrate:
if not self.is_calibrated and calibrate and should_require_piper_calibration(self.config.calibration_mode):
logger.info("No piper-leader calibration file found for '%s'. Running lerobot-calibrate flow.", self.id)
self.calibrate()
except Exception:
@ -103,6 +104,9 @@ class PiperLeader(Teleoperator):
logger.info("%s connected.", self)
def _use_uncalibrated_passthrough(self) -> bool:
return not self.is_calibrated and not should_require_piper_calibration(self.config.calibration_mode)
@property
def is_calibrated(self) -> bool:
if not all(key in self.calibration for key in PIPER_CALIB_KEYS):
@ -285,12 +289,18 @@ class PiperLeader(Teleoperator):
@check_if_not_connected
def get_action(self) -> RobotAction:
if not self.is_calibrated:
if not self.is_calibrated and not self._use_uncalibrated_passthrough():
raise RuntimeError(
f"{self} is not calibrated. Run `lerobot-calibrate --teleop.type=piper_leader --teleop.id={self.id}` first."
)
raw_action = self._read_raw_action()
if self._use_uncalibrated_passthrough():
action: RobotAction = dict(raw_action)
if not self.config.sync_gripper:
action["gripper.pos"] = 0.0
return action
action: RobotAction = {
key: self._calibrated_to_offset(key, raw_action[key]) for key in PIPER_CALIB_KEYS
}
@ -300,7 +310,7 @@ class PiperLeader(Teleoperator):
@check_if_not_connected
def send_feedback(self, feedback: dict[str, Any]) -> None:
if not self.is_calibrated:
if not self.is_calibrated and not self._use_uncalibrated_passthrough():
raise RuntimeError(
f"{self} is not calibrated. Run `lerobot-calibrate --teleop.type=piper_leader --teleop.id={self.id}` first."
)
@ -311,12 +321,18 @@ class PiperLeader(Teleoperator):
joint_keys = PIPER_JOINT_ACTION_KEYS
has_all_joints = all(key in feedback for key in joint_keys)
if has_all_joints:
joint_targets = [self._offset_to_calibrated(key, feedback[key]) for key in joint_keys]
if self._use_uncalibrated_passthrough():
joint_targets = [feedback[key] for key in joint_keys]
else:
joint_targets = [self._offset_to_calibrated(key, feedback[key]) for key in joint_keys]
joint_commands = [unit_to_milli(value) for value in joint_targets]
self.arm.JointCtrl(*joint_commands)
if self.config.sync_gripper and "gripper.pos" in feedback:
gripper_target = self._offset_to_calibrated("gripper.pos", feedback["gripper.pos"])
if self._use_uncalibrated_passthrough():
gripper_target = feedback["gripper.pos"]
else:
gripper_target = self._offset_to_calibrated("gripper.pos", feedback["gripper.pos"])
gripper_pos_raw = unit_to_milli(gripper_target)
self.arm.GripperCtrl(
gripper_pos_raw,

查看文件

@ -29,6 +29,7 @@ PIPER_JOINT_NAMES = (
)
PIPER_JOINT_ACTION_KEYS = tuple(f"{joint}.pos" for joint in PIPER_JOINT_NAMES)
PIPER_ACTION_KEYS = PIPER_JOINT_ACTION_KEYS + ("gripper.pos",)
PIPER_CALIBRATION_MODES = {"required", "off"}
def milli_to_unit(value: float | int) -> float:
@ -61,3 +62,14 @@ def parse_piper_log_level(level_name: str) -> Any:
f"Invalid Piper log level '{level_name}'. "
"Expected one of: DEBUG, INFO, WARNING, ERROR, CRITICAL, SILENT."
) from exc
def should_require_piper_calibration(calibration_mode: str) -> bool:
if calibration_mode == "required":
return True
if calibration_mode == "off":
return False
raise ValueError(
f"Invalid Piper calibration mode '{calibration_mode}'. "
"Expected one of: required, off."
)

查看文件

@ -268,3 +268,21 @@ def test_piper_follower_connect_rolls_back_connected_cameras(monkeypatch):
assert cam_ok.disconnect_calls == 1
assert not cam_ok.is_connected
assert not robot.is_connected
def test_piper_calibration_mode_off_allows_uncalibrated_control(monkeypatch):
patch_fake_sdk(monkeypatch)
teleop = PiperLeader(PiperLeaderConfig(port="can1", calibration_mode="off"))
robot = PiperFollower(PiperFollowerConfig(port="can0", calibration_mode="off"))
teleop.connect(calibrate=False)
robot.connect(calibrate=False)
try:
action = teleop.get_action()
sent = robot.send_action(action)
assert sent["joint_1.pos"] == 10.0
assert sent["gripper.pos"] == 42.0
finally:
teleop.disconnect()
robot.disconnect()