镜像自地址
https://github.com/MINT-SJTU/Evo-RL.git
已同步 2026-11-20 18:17:06 +00:00
fix(piper): align follower flags and SDK dependency
这个提交包含在:
114
README.md
114
README.md
@ -29,6 +29,15 @@
|
|||||||
|
|
||||||
- **[2026-02-26]** First SO101 real-world RL baseline and reproducible CLI workflow are released.
|
- **[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"><strong>Value Visual Results</strong></p>
|
||||||
|
|
||||||
<p align="center"><small><strong>Success Case</strong></small></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%"/>
|
<img alt="Human-in-the-Loop Result 2" src="./website/assets/gifs/hitl_2.gif" width="48%"/>
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
|
<a id="quick-start"></a>
|
||||||
## ⚡ Quick Start
|
## ⚡ 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.
|
**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
|
### 1) Installation
|
||||||
|
|
||||||
```bash
|
```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).
|
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
|
### 2) Hardware Setup
|
||||||
|
|
||||||
#### SO101
|
#### SO Series (SO100/SO101)
|
||||||
|
|
||||||
Due to hardware limitations, SO100 is **not supported** for real-world reinforcement learning.
|
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.
|
||||||
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.
|
|
||||||
|
|
||||||
#### Device path recommendation
|
#### 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.
|
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
|
### 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
|
```bash
|
||||||
lerobot-human-inloop-record \
|
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.
|
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:
|
Hotkeys:
|
||||||
|
|
||||||
- `i`: toggle intervention mode (policy <-> teleop takeover)
|
- `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.
|
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
|
### 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`).
|
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(...)`.
|
- 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`.
|
- 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
|
### 5) Value Inference
|
||||||
|
|
||||||
Infer value signals and write value/advantage/indicator back to the dataset:
|
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:
|
Parameter notes:
|
||||||
|
|
||||||
- `--acp.n_step`: n-step advantage horizon.
|
```bash
|
||||||
- `--acp.positive_ratio`: positive label ratio after advantage binarization (e.g., `0.3` = top 30% per task).
|
--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:
|
Expected new columns:
|
||||||
|
|
||||||
- `complementary_info.value_<TAG>`
|
```bash
|
||||||
- `complementary_info.advantage_<TAG>`
|
complementary_info.value_<TAG>
|
||||||
- `complementary_info.acp_indicator_<TAG>`
|
complementary_info.advantage_<TAG>
|
||||||
|
complementary_info.acp_indicator_<TAG>
|
||||||
|
```
|
||||||
|
|
||||||
These columns are written back to the original dataset specified by `--dataset.repo_id`.
|
These columns are written back to the original dataset specified by `--dataset.repo_id`.
|
||||||
|
|
||||||
Visualization (optional):
|
<a id="policy-training"></a>
|
||||||
|
|
||||||
- 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/`.
|
|
||||||
|
|
||||||
### 6) Policy Training
|
### 6) Policy Training
|
||||||
|
|
||||||
Train the policy with advantage-conditioned tags.
|
Train the policy with advantage-conditioned tags.
|
||||||
@ -377,6 +440,7 @@ CUDA_VISIBLE_DEVICES=<GPU_ID_LIST> accelerate launch \
|
|||||||
<POLICY_TRAIN_ARGS>
|
<POLICY_TRAIN_ARGS>
|
||||||
```
|
```
|
||||||
|
|
||||||
|
<a id="closed-loop-rollout-and-next-round"></a>
|
||||||
### 7) Closed-loop Rollout and Next Round
|
### 7) Closed-loop Rollout and Next Round
|
||||||
|
|
||||||
Deploy the trained policy in human-in-loop mode and collect the next dataset 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",
|
"packaging>=24.2,<26.0",
|
||||||
"pynput>=1.7.7,<1.9.0",
|
"pynput>=1.7.7,<1.9.0",
|
||||||
"pyserial>=3.5,<4.0",
|
"pyserial>=3.5,<4.0",
|
||||||
|
"piper_sdk>=0.6.1,<0.7.0",
|
||||||
"wandb>=0.24.0,<0.25.0",
|
"wandb>=0.24.0,<0.25.0",
|
||||||
|
|
||||||
"torch>=2.2.1,<2.8.0", # TODO: Bumb dependency
|
"torch>=2.2.1,<2.8.0", # TODO: Bumb dependency
|
||||||
|
|||||||
@ -34,8 +34,8 @@ class PiperFollowerConfigBase:
|
|||||||
log_level: str = "WARNING"
|
log_level: str = "WARNING"
|
||||||
startup_sleep_s: float = 0.1
|
startup_sleep_s: float = 0.1
|
||||||
|
|
||||||
# Optional role command on startup (0xFC = motion output arm)
|
# Optional role command on startup (0xFC = motion output/follower arm)
|
||||||
set_slave_mode_on_connect: bool = False
|
set_follower_mode_on_connect: bool = False
|
||||||
|
|
||||||
# Motion mode for follower arm
|
# Motion mode for follower arm
|
||||||
speed_ratio: int = 100
|
speed_ratio: int = 100
|
||||||
|
|||||||
@ -85,7 +85,7 @@ class PiperFollower(Robot):
|
|||||||
|
|
||||||
self._is_connected = True
|
self._is_connected = True
|
||||||
try:
|
try:
|
||||||
if self.config.set_slave_mode_on_connect:
|
if self.config.set_follower_mode_on_connect:
|
||||||
self.arm.MasterSlaveConfig(0xFC, 0x00, 0x00, 0x00)
|
self.arm.MasterSlaveConfig(0xFC, 0x00, 0x00, 0x00)
|
||||||
time.sleep(0.05)
|
time.sleep(0.05)
|
||||||
|
|
||||||
|
|||||||
@ -16,10 +16,7 @@
|
|||||||
|
|
||||||
from __future__ import annotations
|
from __future__ import annotations
|
||||||
|
|
||||||
import os
|
|
||||||
import sys
|
|
||||||
from functools import lru_cache
|
from functools import lru_cache
|
||||||
from pathlib import Path
|
|
||||||
from typing import Any
|
from typing import Any
|
||||||
|
|
||||||
PIPER_JOINT_NAMES = (
|
PIPER_JOINT_NAMES = (
|
||||||
@ -41,72 +38,16 @@ def unit_to_milli(value: float | int) -> int:
|
|||||||
return int(round(float(value) * 1e3))
|
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)
|
@lru_cache(maxsize=1)
|
||||||
def get_piper_sdk() -> tuple[type[Any], Any]:
|
def get_piper_sdk() -> tuple[type[Any], Any]:
|
||||||
try:
|
try:
|
||||||
from piper_sdk import C_PiperInterface_V2, LogLevel
|
from piper_sdk import C_PiperInterface_V2, LogLevel
|
||||||
|
|
||||||
return C_PiperInterface_V2, LogLevel
|
return C_PiperInterface_V2, LogLevel
|
||||||
except ModuleNotFoundError:
|
except ModuleNotFoundError as exc:
|
||||||
pass
|
raise ModuleNotFoundError(
|
||||||
|
"Could not import `piper_sdk`. Install Evo-RL dependencies first (for example: `pip install -e .`)."
|
||||||
searched_paths: list[str] = []
|
) from exc
|
||||||
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}"
|
|
||||||
)
|
|
||||||
|
|
||||||
|
|
||||||
def parse_piper_log_level(level_name: str) -> Any:
|
def parse_piper_log_level(level_name: str) -> Any:
|
||||||
|
|||||||
@ -1,6 +1,8 @@
|
|||||||
from types import SimpleNamespace
|
from types import SimpleNamespace
|
||||||
|
|
||||||
import lerobot.utils.piper_sdk as piper_sdk_utils
|
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.piper_follower import PiperFollower, PiperFollowerConfig
|
||||||
from lerobot.robots.utils import make_robot_from_config
|
from lerobot.robots.utils import make_robot_from_config
|
||||||
from lerobot.teleoperators.piper_leader import PiperLeader, PiperLeaderConfig
|
from lerobot.teleoperators.piper_leader import PiperLeader, PiperLeaderConfig
|
||||||
@ -106,7 +108,10 @@ class FakePiperInterface:
|
|||||||
|
|
||||||
|
|
||||||
def patch_fake_sdk(monkeypatch):
|
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):
|
def test_piper_leader_follower_teleop_roundtrip(monkeypatch):
|
||||||
@ -120,7 +125,7 @@ def test_piper_leader_follower_teleop_roundtrip(monkeypatch):
|
|||||||
)
|
)
|
||||||
robot_cfg = PiperFollowerConfig(
|
robot_cfg = PiperFollowerConfig(
|
||||||
port="can0",
|
port="can0",
|
||||||
set_slave_mode_on_connect=True,
|
set_follower_mode_on_connect=True,
|
||||||
sync_gripper=True,
|
sync_gripper=True,
|
||||||
)
|
)
|
||||||
|
|
||||||
|
|||||||
在新工单中引用
屏蔽一个用户