fix(piper): align follower flags and SDK dependency

这个提交包含在:
Elvin
2026-03-04 21:34:42 +08:00
父节点 78dae04a31
当前提交 b4482674ef
共有 6 个文件被更改,包括 104 次插入 和 93 次删除

114
README.md
查看文件

@ -29,6 +29,15 @@
- **[2026-02-26]** First SO101 real-world RL baseline and reproducible CLI workflow are released.
## 🧭 Table of Contents
| Getting Started | Training Pipeline | Project Info |
| --- | --- | --- |
| [⚡ Quick Start](#quick-start) | [4) Value Function Training](#value-function-training) | [Model & Dataset](#model--dataset) |
| [1) Installation](#installation) | [5) Value Inference](#value-inference) | [Community Channels](#community-channels) |
| [2) Hardware Setup](#hardware-setup) | [6) Policy Training](#policy-training) | [Affiliations](#affiliations) |
| [3) Data Collection](#data-collection) | [7) Closed-loop Rollout and Next Round](#closed-loop-rollout-and-next-round) | [Citation](#citation) / [License](#license) |
<p align="center"><strong>Value Visual Results</strong></p>
<p align="center"><small><strong>Success Case</strong></small></p>
@ -57,10 +66,12 @@
<img alt="Human-in-the-Loop Result 2" src="./website/assets/gifs/hitl_2.gif" width="48%"/>
</p>
<a id="quick-start"></a>
## ⚡ Quick Start
**LeRobot-aligned foundation:** we use LeRobot as the base of this codebase because its inference and data-collection logic are highly aligned with real-world RL workflows.
<a id="installation"></a>
### 1) Installation
```bash
@ -73,13 +84,13 @@ pip install -e .
For setup details and platform-specific dependencies, follow the official [LeRobot configuration guide](https://huggingface.co/docs/lerobot/installation).
<a id="hardware-setup"></a>
### 2) Hardware Setup
#### SO101
#### SO Series (SO100/SO101)
Due to hardware limitations, SO100 is **not supported** for real-world reinforcement learning.
For SO101 setup, please follow the [official SO101 tutorial](https://wiki.seeedstudio.com/cn/lerobot_so100m/) in detail and complete all installation and configuration steps there before continuing.
For SO-series setup, please follow the [official tutorial](https://wiki.seeedstudio.com/cn/lerobot_so100m/) in detail and complete all installation and configuration steps there before continuing.
The examples below use **SO101** as the reference configuration.
#### Device path recommendation
@ -186,9 +197,51 @@ For dual-arm camera mapping, it is fine to attach `front` under either the left-
If needed, you can also use temporary device paths (for example `/dev/ttyACM*` and `/dev/video*`) during initial debugging.
<a id="agilex-piper-setup"></a>
#### AgileX PiPER
For PiPER setup, PiPER uses CAN interfaces instead of serial ports.
So first run `lerobot-setup-can` to confirm CAN interfaces are available:
```bash
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.
```bash
--teleop.set_leader_mode_on_connect=true
--robot.set_follower_mode_on_connect=true
```
For single-arm users, run the command below to verify the system is ready:
```bash
lerobot-teleoperate \
--robot.type=piper_follower \
--robot.port=can0 \
--robot.id=my_piper_follower \
--teleop.type=piper_leader \
--teleop.port=can1 \
--teleop.id=my_piper_leader
```
Optional PiPER flags:
```bash
--robot.sync_gripper=true|false
--robot.gripper_effort_default=1000
--teleop.sync_gripper=true|false
```
<a id="data-collection"></a>
### 3) Data Collection
Collect rollout data with `lerobot-human-inloop-record`. Bimanual template:
Collect rollout data with `lerobot-human-inloop-record`.
#### SO Series (SO100/SO101)
Bimanual template:
```bash
lerobot-human-inloop-record \
@ -213,6 +266,24 @@ lerobot-human-inloop-record \
Recommendation: use **`fourcc: "MJPG"`** for OpenCV and **`warmup_s`** for RealSense. In this example `front` uses RealSense, but you can switch it to OpenCV with the same structure.
#### AgileX PiPER
```bash
lerobot-human-inloop-record \
--robot.type=piper_follower \
--robot.port=can0 \
--robot.id=my_piper_follower \
--teleop.type=piper_leader \
--teleop.port=can1 \
--teleop.id=my_piper_leader \
--dataset.repo_id=<HF_USERNAME_OR_ORG>/<DATASET_NAME> \
--dataset.single_task="<YOUR_TASK_DESCRIPTION>" \
--dataset.num_episodes=<NUM_EPISODES> \
--dataset.episode_time_s=<EPISODE_SECONDS> \
--dataset.reset_time_s=<RESET_SECONDS> \
--dataset.push_to_hub=true
```
Hotkeys:
- `i`: toggle intervention mode (policy <-> teleop takeover)
@ -230,6 +301,7 @@ lerobot-dataset-report --dataset <HF_USERNAME_OR_ORG>/<DATASET_NAME>
This prints: dataset meta, totals, episode-length stats/histogram, success/intervention metrics, task list, and full feature schema.
<a id="value-function-training"></a>
### 4) Value Function Training
Train the value function on the current dataset. Current default: [Pi\*0.6](https://www.pi.website/blog/pistar06) (`--value.type=pistar06`).
@ -268,6 +340,7 @@ To plug in a different value function, minimal path in this repo:
- Add `src/lerobot/values/<your_value>/processor_<your_value>.py` with `make_<your_value>_pre_post_processors(...)`.
- Remove/replace the current `pistar06`-only type checks in `src/lerobot/configs/value_train.py` and `src/lerobot/scripts/lerobot_value_infer.py`.
<a id="value-inference"></a>
### 5) Value Inference
Infer value signals and write value/advantage/indicator back to the dataset:
@ -307,32 +380,22 @@ CUDA_VISIBLE_DEVICES=<GPU_ID_LIST> accelerate launch \
Parameter notes:
- `--acp.n_step`: n-step advantage horizon.
- `--acp.positive_ratio`: positive label ratio after advantage binarization (e.g., `0.3` = top 30% per task).
```bash
--acp.n_step: n-step advantage horizon.
--acp.positive_ratio: positive label ratio after advantage binarization (e.g., 0.3 = top 30% per task).
```
Expected new columns:
- `complementary_info.value_<TAG>`
- `complementary_info.advantage_<TAG>`
- `complementary_info.acp_indicator_<TAG>`
```bash
complementary_info.value_<TAG>
complementary_info.advantage_<TAG>
complementary_info.acp_indicator_<TAG>
```
These columns are written back to the original dataset specified by `--dataset.repo_id`.
Visualization (optional):
- Enable with `--viz.enable=true`.
- Output videos are saved to `outputs/value_infer/<RUN_NAME>/value/viz/`.
- Each video overlays a value curve and per-frame text (`advantage`, `acp_indicator`) on top of camera frames.
- You can control scope with:
- `--viz.episodes=all` or ranges like `0-9,12`
- `--viz.video_key=<CAMERA_KEY>` (default picks `front` if available)
- `--viz.overwrite=true|false`
- `--viz.vcodec=<CODEC>` and `--viz.frame_storage_mode=memory|disk`
Value overlay examples (SO101, smooth=11):
- GIF assets are stored under `website/assets/gifs/`.
<a id="policy-training"></a>
### 6) Policy Training
Train the policy with advantage-conditioned tags.
@ -377,6 +440,7 @@ CUDA_VISIBLE_DEVICES=<GPU_ID_LIST> accelerate launch \
<POLICY_TRAIN_ARGS>
```
<a id="closed-loop-rollout-and-next-round"></a>
### 7) Closed-loop Rollout and Next Round
Deploy the trained policy in human-in-loop mode and collect the next dataset round:

查看文件

@ -74,6 +74,7 @@ dependencies = [
"packaging>=24.2,<26.0",
"pynput>=1.7.7,<1.9.0",
"pyserial>=3.5,<4.0",
"piper_sdk>=0.6.1,<0.7.0",
"wandb>=0.24.0,<0.25.0",
"torch>=2.2.1,<2.8.0", # TODO: Bumb dependency

查看文件

@ -34,8 +34,8 @@ class PiperFollowerConfigBase:
log_level: str = "WARNING"
startup_sleep_s: float = 0.1
# Optional role command on startup (0xFC = motion output arm)
set_slave_mode_on_connect: bool = False
# Optional role command on startup (0xFC = motion output/follower arm)
set_follower_mode_on_connect: bool = False
# Motion mode for follower arm
speed_ratio: int = 100

查看文件

@ -85,7 +85,7 @@ class PiperFollower(Robot):
self._is_connected = True
try:
if self.config.set_slave_mode_on_connect:
if self.config.set_follower_mode_on_connect:
self.arm.MasterSlaveConfig(0xFC, 0x00, 0x00, 0x00)
time.sleep(0.05)

查看文件

@ -16,10 +16,7 @@
from __future__ import annotations
import os
import sys
from functools import lru_cache
from pathlib import Path
from typing import Any
PIPER_JOINT_NAMES = (
@ -41,72 +38,16 @@ def unit_to_milli(value: float | int) -> int:
return int(round(float(value) * 1e3))
def _iter_candidate_paths() -> list[Path]:
repo_root = Path(__file__).resolve().parents[3]
env_path = os.environ.get("PIPER_SDK_PATH")
candidates: list[Path] = []
if env_path:
candidates.append(Path(env_path).expanduser())
candidates.extend(
[
Path.cwd(),
repo_root,
repo_root.parent,
repo_root / "piper_sdk",
repo_root.parent / "piper_sdk",
]
)
return candidates
def _add_path_if_matches(candidate: Path) -> bool:
candidate = candidate.resolve()
package_dir = candidate / "piper_sdk"
if package_dir.is_dir() and (package_dir / "__init__.py").is_file():
parent = str(candidate)
if parent not in sys.path:
sys.path.insert(0, parent)
return True
if candidate.name == "piper_sdk" and (candidate / "__init__.py").is_file():
parent = str(candidate.parent)
if parent not in sys.path:
sys.path.insert(0, parent)
return True
return False
@lru_cache(maxsize=1)
def get_piper_sdk() -> tuple[type[Any], Any]:
try:
from piper_sdk import C_PiperInterface_V2, LogLevel
return C_PiperInterface_V2, LogLevel
except ModuleNotFoundError:
pass
searched_paths: list[str] = []
for candidate in _iter_candidate_paths():
searched_paths.append(str(candidate))
if not candidate.exists():
continue
_add_path_if_matches(candidate)
try:
from piper_sdk import C_PiperInterface_V2, LogLevel
return C_PiperInterface_V2, LogLevel
except ModuleNotFoundError:
continue
searched = "\n- ".join(searched_paths)
raise ModuleNotFoundError(
"Could not import `piper_sdk`. Install it (for example: `pip install -e /path/to/piper_sdk`) "
"or set PIPER_SDK_PATH. Searched paths:\n- "
f"{searched}"
)
except ModuleNotFoundError as exc:
raise ModuleNotFoundError(
"Could not import `piper_sdk`. Install Evo-RL dependencies first (for example: `pip install -e .`)."
) from exc
def parse_piper_log_level(level_name: str) -> Any:

查看文件

@ -1,6 +1,8 @@
from types import SimpleNamespace
import lerobot.utils.piper_sdk as piper_sdk_utils
import lerobot.robots.piper_follower.piper_follower as piper_follower_module
import lerobot.teleoperators.piper_leader.piper_leader as piper_leader_module
from lerobot.robots.piper_follower import PiperFollower, PiperFollowerConfig
from lerobot.robots.utils import make_robot_from_config
from lerobot.teleoperators.piper_leader import PiperLeader, PiperLeaderConfig
@ -106,7 +108,10 @@ class FakePiperInterface:
def patch_fake_sdk(monkeypatch):
monkeypatch.setattr(piper_sdk_utils, "get_piper_sdk", lambda: (FakePiperInterface, FakeLogLevel))
fake_loader = lambda: (FakePiperInterface, FakeLogLevel)
monkeypatch.setattr(piper_sdk_utils, "get_piper_sdk", fake_loader)
monkeypatch.setattr(piper_follower_module, "get_piper_sdk", fake_loader)
monkeypatch.setattr(piper_leader_module, "get_piper_sdk", fake_loader)
def test_piper_leader_follower_teleop_roundtrip(monkeypatch):
@ -120,7 +125,7 @@ def test_piper_leader_follower_teleop_roundtrip(monkeypatch):
)
robot_cfg = PiperFollowerConfig(
port="can0",
set_slave_mode_on_connect=True,
set_follower_mode_on_connect=True,
sync_gripper=True,
)