# LeRobot 双臂移动操作项目

基于 LeRobot，建立人工遥操示范、采集、训练与真机执行闭环。先完成单臂抓放，再扩展桌面双臂，最后实现“移动到位 → 停稳 → 操作”的分阶段任务。

当前进入 P1：SO101 主从臂遥操与双摄像头采集已跑通，5 条真实示范已检查，RTX 3080 正在训练 ACT。自主抓放尚未评测；实时状态快照见 [进度追踪](docs/progress.md)。历史环境验收见 [P0 记录](docs/p0-3080-20260908.md)。

## 导览

| 文件 | 内容 |
|---|---|
| [docs/progress.md](docs/progress.md) | 当前状态、训练快照、问题与下一步 |
| [PLAN.md](PLAN.md) | 决策、阶段范围、验收与风险 |
| [hw/bom.md](hw/bom.md) | 分批采购、供电和机械验证 |
| [env/machines.md](env/machines.md) | 机器分工、依赖锁流程和环境记录 |
| [env/setup_lerobot.sh](env/setup_lerobot.sh) | Ubuntu GPU 环境安装与冒烟检查 |
| [env/requirements.in](env/requirements.in) | LeRobot 0.6.1 / P1 依赖输入 |
| [docs/cli_reference.md](docs/cli_reference.md) | 单臂设置、采集、训练和 rollout 示例 |
| [docs/evaluation.md](docs/evaluation.md) | 20 次评测及故障验证记录模板 |

`robots/` 已提供遥操、采集、训练和评测启动器；`configs/`、`server/`、`client/` 仍为后续扩展目录。后续优先复用上游驱动与网络推理，仅实现组合硬件适配、任务调度和故障处理。

## 机器分工

- 3080 10GB：当前 ACT 基线训练、遥操、采集与推理，P1/P2 USB 直连。
- 3090 24GB：训练，与 3080 使用同一经过验证的依赖锁。
- RPi 5：P3 起采图和动作执行，ARM64 环境单独验证。
- ACT：固定任务基线；SmolVLA：预训练基座微调和语言条件探索。
- 数据/模型优先局域网 rsync，HF Hub 可选；代码经 git 同步。

## 开始（3080 Ubuntu 主机）

先安装 git、uv、NVIDIA 驱动、FFmpeg，详见机器文档。

```bash
mkdir -p ~/robot
git clone https://git.hyonglin.top/ylhan/lerobot_learn.git ~/robot/proj
bash ~/robot/proj/env/setup_lerobot.sh
```

仓库已附本机验证的依赖锁及输入指纹，默认按锁安装；不要再次使用 `--resolve` 覆盖锁。3090 仍需同锁独立验收。已有本仓库时无需重复 clone，可直接在项目目录运行 `bash env/setup_lerobot.sh`。脚本不会自动拉取上游最新代码，也不会操作机器人。

安装完成后，在项目目录激活环境并加载本机主从臂串口：

```bash
source env/activate_lerobot.sh
```

## SO101 遥操作

以下脚本会自动激活环境，使用固定串口路径及 `zihao_follower_arm` / `zihao_leader_arm` 校准文件。在两条臂姿态大致一致、从臂周围有活动空间时运行；按 Ctrl+C 停止。

```bash
# 无摄像头
bash robots/teleoperate_no_camera.sh

# 单摄像头：腕部 Integrated Webcam，640×480 MJPG，30 FPS
bash robots/teleoperate_one_camera.sh

# 双摄像头：腕部相机 + 外部 USB2.0 CAM1（640×480 MJPG，25 FPS）
bash robots/teleoperate_two_cameras.sh
```

摄像头使用 `/dev/v4l/by-id/` 路径，避免 video 编号随插拔变化。单摄像头画面名为 `wrist`；双摄像头额外包含 `front`。带摄像头的脚本默认显示画面。脚本支持追加 LeRobot 参数，例如 `bash robots/teleoperate_no_camera.sh --fps=30`。

## ACT 积木抓放

先执行 `bash robots/record_block_white_box.sh` 录制 5 条检查数据。采集、续录、训练与真机评测说明见 [ACT 积木放入白盒](docs/act_block_white_box.md)。