feat(piper): add bimanual PiPER/PiPER-X support and refresh docs

- add bi_piper/bi_piperx follower and leader implementations with configs

- wire bimanual Piper types into factories, scripts, and async inference mappings

- add pairing validation and bimanual parsing/teleop test coverage

- update README news and AgileX teleop/data-collection command templates
这个提交包含在:
Elvin
2026-03-07 22:27:09 +08:00
父节点 0d2ed91280
当前提交 cb29370c78
共有 20 个文件被更改,包括 795 次插入 和 23 次删除

查看文件

@ -0,0 +1,78 @@
import draccus
import pytest
from draccus.utils import ParsingError
from lerobot.scripts.lerobot_record import RecordConfig
from lerobot.scripts.lerobot_teleoperate import TeleoperateConfig
def test_teleoperate_parses_bi_piperx_types():
args = [
"--robot.type=bi_piperx_follower",
"--robot.id=my_bi_piperx_follower",
"--robot.left_arm_config.port=can0",
"--robot.right_arm_config.port=can2",
"--robot.left_arm_config.require_calibration=false",
"--robot.right_arm_config.require_calibration=false",
"--teleop.type=bi_piperx_leader",
"--teleop.id=my_bi_piperx_leader",
"--teleop.left_arm_config.port=can1",
"--teleop.right_arm_config.port=can3",
"--teleop.left_arm_config.require_calibration=false",
"--teleop.right_arm_config.require_calibration=false",
]
cfg = draccus.parse(config_class=TeleoperateConfig, config_path=None, args=args)
assert cfg.robot.type == "bi_piperx_follower"
assert cfg.teleop.type == "bi_piperx_leader"
def test_record_rejects_mixed_bi_piper_pair():
args = [
"--robot.type=bi_piper_follower",
"--robot.id=my_bi_piper_follower",
"--robot.left_arm_config.port=can0",
"--robot.right_arm_config.port=can2",
"--robot.left_arm_config.require_calibration=false",
"--robot.right_arm_config.require_calibration=false",
"--teleop.type=bi_piperx_leader",
"--teleop.id=my_bi_piperx_leader",
"--teleop.left_arm_config.port=can1",
"--teleop.right_arm_config.port=can3",
"--teleop.left_arm_config.require_calibration=false",
"--teleop.right_arm_config.require_calibration=false",
"--dataset.repo_id=dummy/dummy",
"--dataset.single_task=test",
"--dataset.num_episodes=1",
"--dataset.episode_time_s=1",
"--dataset.reset_time_s=1",
"--dataset.push_to_hub=false",
]
with pytest.raises(ParsingError) as exc_info:
draccus.parse(config_class=RecordConfig, config_path=None, args=args)
assert "Couldn't instantiate class RecordConfig" in str(exc_info.value)
assert exc_info.value.__cause__ is not None
assert "must be paired" in str(exc_info.value.__cause__)
def test_record_rejects_bimanual_piper_teleop_with_non_bimanual_robot():
args = [
"--robot.type=so101_follower",
"--robot.port=/dev/mock",
"--teleop.type=bi_piperx_leader",
"--teleop.id=my_bi_piperx_leader",
"--teleop.left_arm_config.port=can1",
"--teleop.right_arm_config.port=can3",
"--teleop.left_arm_config.require_calibration=false",
"--teleop.right_arm_config.require_calibration=false",
"--dataset.repo_id=dummy/dummy",
"--dataset.single_task=test",
"--dataset.num_episodes=1",
"--dataset.episode_time_s=1",
"--dataset.reset_time_s=1",
"--dataset.push_to_hub=false",
]
with pytest.raises(ParsingError) as exc_info:
draccus.parse(config_class=RecordConfig, config_path=None, args=args)
assert "Couldn't instantiate class RecordConfig" in str(exc_info.value)
assert exc_info.value.__cause__ is not None
assert "must be paired" in str(exc_info.value.__cause__)

查看文件

@ -9,16 +9,30 @@ import lerobot.robots.piper_follower.piper_follower as piper_follower_module
import lerobot.teleoperators.piper_leader.piper_leader as piper_leader_module
import lerobot.utils.piper_sdk as piper_sdk_utils
from lerobot.motors import MotorCalibration
from lerobot.robots.bi_piper_follower import (
BiPiperFollower,
BiPiperFollowerConfig,
BiPiperXFollower,
BiPiperXFollowerConfig,
)
from lerobot.robots.piper_follower import (
PiperFollower,
PiperFollowerConfig,
PiperFollowerConfigBase,
PiperXFollower,
PiperXFollowerConfig,
)
from lerobot.robots.utils import make_robot_from_config
from lerobot.teleoperators.bi_piper_leader import (
BiPiperLeader,
BiPiperLeaderConfig,
BiPiperXLeader,
BiPiperXLeaderConfig,
)
from lerobot.teleoperators.piper_leader import (
PiperLeader,
PiperLeaderConfig,
PiperLeaderConfigBase,
PiperXLeader,
PiperXLeaderConfig,
)
@ -477,3 +491,111 @@ def test_piper_lfs_pointer_urdf_raises_actionable_error(tmp_path):
piper_leader_module._ensure_not_lfs_pointer(
pointer_file, "assets/piper_description/urdf/pointer.urdf"
)
@pytest.mark.parametrize(
(
"teleop_cfg",
"robot_cfg",
"bi_teleop_cls",
"bi_robot_cls",
"left_teleop_cls",
"right_teleop_cls",
"left_robot_cls",
"right_robot_cls",
),
[
(
BiPiperLeaderConfig(
left_arm_config=PiperLeaderConfigBase(port="can1", manual_control=False, sync_gripper=True),
right_arm_config=PiperLeaderConfigBase(port="can3", manual_control=False, sync_gripper=True),
),
BiPiperFollowerConfig(
left_arm_config=PiperFollowerConfigBase(port="can0", sync_gripper=True),
right_arm_config=PiperFollowerConfigBase(port="can2", sync_gripper=True),
),
BiPiperLeader,
BiPiperFollower,
PiperLeader,
PiperLeader,
PiperFollower,
PiperFollower,
),
(
BiPiperXLeaderConfig(
left_arm_config=PiperLeaderConfigBase(port="can1", manual_control=False, sync_gripper=True),
right_arm_config=PiperLeaderConfigBase(port="can3", manual_control=False, sync_gripper=True),
),
BiPiperXFollowerConfig(
left_arm_config=PiperFollowerConfigBase(port="can0", sync_gripper=True),
right_arm_config=PiperFollowerConfigBase(port="can2", sync_gripper=True),
),
BiPiperXLeader,
BiPiperXFollower,
PiperXLeader,
PiperXLeader,
PiperXFollower,
PiperXFollower,
),
],
)
def test_bimanual_piper_leader_follower_roundtrip(
monkeypatch,
teleop_cfg,
robot_cfg,
bi_teleop_cls,
bi_robot_cls,
left_teleop_cls,
right_teleop_cls,
left_robot_cls,
right_robot_cls,
):
patch_fake_sdk(monkeypatch)
teleop = make_teleoperator_from_config(teleop_cfg)
robot = make_robot_from_config(robot_cfg)
assert isinstance(teleop, bi_teleop_cls)
assert isinstance(robot, bi_robot_cls)
assert isinstance(teleop.left_arm, left_teleop_cls)
assert isinstance(teleop.right_arm, right_teleop_cls)
assert isinstance(robot.left_arm, left_robot_cls)
assert isinstance(robot.right_arm, right_robot_cls)
teleop.left_arm.calibration = make_identity_calibration()
teleop.right_arm.calibration = make_identity_calibration()
robot.left_arm.calibration = make_identity_calibration()
robot.right_arm.calibration = make_identity_calibration()
teleop.connect(calibrate=False)
robot.connect(calibrate=False)
try:
action = teleop.get_action()
assert "left_joint_1.pos" in action
assert "right_joint_1.pos" in action
sent = robot.send_action(action)
obs = robot.get_observation()
assert robot.left_arm.arm.last_joint == (10000, 20000, 30000, 40000, 50000, 60000)
assert robot.right_arm.arm.last_joint == (10000, 20000, 30000, 40000, 50000, 60000)
assert robot.left_arm.arm.last_gripper[0] == 42000
assert robot.right_arm.arm.last_gripper[0] == 42000
assert sent["left_joint_1.pos"] == 10.0
assert sent["right_joint_1.pos"] == 10.0
assert sent["left_gripper.pos"] == 42.0
assert sent["right_gripper.pos"] == 42.0
assert obs["left_joint_1.pos"] == 11.0
assert obs["right_joint_1.pos"] == 11.0
assert obs["left_gripper.pos"] == 43.0
assert obs["right_gripper.pos"] == 43.0
teleop.send_feedback(action)
assert teleop.left_arm.arm.last_joint == (10000, 20000, 30000, 40000, 50000, 60000)
assert teleop.right_arm.arm.last_joint == (10000, 20000, 30000, 40000, 50000, 60000)
assert teleop.left_arm.arm.last_gripper[0] == 42000
assert teleop.right_arm.arm.last_gripper[0] == 42000
finally:
teleop.disconnect()
robot.disconnect()

查看文件

@ -0,0 +1,41 @@
from types import SimpleNamespace
import pytest
from lerobot.utils.control_utils import sanity_check_bimanual_piper_pair
@pytest.mark.parametrize(
("robot_type", "teleop_type"),
[
("bi_piper_follower", "bi_piper_leader"),
("bi_piperx_follower", "bi_piperx_leader"),
("so101_follower", "so101_leader"),
],
)
def test_sanity_check_bimanual_piper_pair_accepts_valid_pairs(robot_type, teleop_type):
sanity_check_bimanual_piper_pair(
SimpleNamespace(type=robot_type),
SimpleNamespace(type=teleop_type),
)
def test_sanity_check_bimanual_piper_pair_accepts_missing_teleop():
sanity_check_bimanual_piper_pair(SimpleNamespace(type="bi_piperx_follower"), None)
@pytest.mark.parametrize(
("robot_type", "teleop_type"),
[
("bi_piper_follower", "bi_piperx_leader"),
("bi_piperx_follower", "bi_piper_leader"),
("so101_follower", "bi_piperx_leader"),
("so101_follower", "bi_piper_leader"),
],
)
def test_sanity_check_bimanual_piper_pair_rejects_mixed_pairs(robot_type, teleop_type):
with pytest.raises(ValueError, match="must be paired"):
sanity_check_bimanual_piper_pair(
SimpleNamespace(type=robot_type),
SimpleNamespace(type=teleop_type),
)