镜像自地址
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.
|
||||
|
||||
## 🧭 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,
|
||||
)
|
||||
|
||||
|
||||
在新工单中引用
屏蔽一个用户