# 方案：LeRobot 双臂移动 VLA 机器人（可自行训练）

> 本文件是项目的「单一事实来源」(single source of truth)。所有决策、预算、阶段、命令、待办都以此为准，随进展更新。
> 最后更新：_P0 定稿（双 GPU 机版：3080 主家 + 3090 训练）_

---

## 0. 目标（一句话）

复刻 LeRobot 工作流，造一台**会走（LeKiwi 底盘）+ 双手协作（2×SO-101）+ 语言/视觉驱动（VLA）+ 能自己采集数据并训练**的移动操作机器人。

**核心思路**：不重写 LeRobot，而是**站在 LeRobot 框架上组装这台特定机器人**；架构上采用「**瘦边 + 厚芯**」——机器人只带一块便宜的驱动板(RPi 5)做实时控制，**推理放 3080 主家（挨着机器人）、训练放 3090（24GB）**，走局域网。

**协作模型**（详见 [env/machines.md](env/machines.md)）：
- **3080 机（10GB · 本地 Ubuntu · 机器人旁）= 主家**：开发 + 臂(USB) + 遥操/采数 + **推理部署** + P4 policy server。
- **3090 机（24GB · 远程 SSH · 同局域网）= 训练专用**：只跑训练；数据集/模型经 HF Hub（或 rsync）流转。
- **本 Windows 机 = 写字台**：我(agent)写代码/配置/文档 → **你 push 到 git 库** → 两台 GPU 机 clone/pull。
- 我无外网 → **我产出，你在两台机器上跑并粘回输出，我迭代**。

---

## 1. 决策总表（已拍板）

| 项 | 决策 | 备注 |
|---|---|---|
| 框架 | **LeRobot**（HF 官方，Py3.12, Transformers v5；最新 0.6.0） | 官方旗舰生态；装时取最新 stable |
| 机械臂 | **4× SO-101**（2 leader + 2 follower） | 双臂遥操 = 2 主 + 2 从；6DOF + 夹爪；自印有 3D 打印机 |
| 底盘 | **LeKiwi**（三轮全向，Feetech STS3215，Seeed 12V 版） | SO-101 专用移动底盘，LeRobot 原生 `.[lekiwi]` |
| 上机驱动板 | **RPi 5 (8GB)** + 有源 USB Hub | 只管实时控制/采图/执行/fail-safe，不做 ML |
| 主家(开发+推理) | **3080 机（本地 Ubuntu · 10GB · 机器人旁）** | 臂 USB 直插；遥操/采数/推理部署；P4 policy server 在它上面 |
| 训练专用 | **3090 机（远程 SSH · 24GB）** | 只跑 lerobot-train；与 3080 同局域网（rsync 直传 / π0 代推） |
| 富余算力 | **AWU408 双 DRIVE Orin**（空闲，非关键路径） | 3090 忙训练时可顶推理 / 或做固定台 |
| 相机 | **3× USB 相机**（1 前置全局 + 2 腕部） | USB 最通用，适配 RPi5/3080 |
| VLA 主力 | **SmolVLA (4.5亿)** | 单卡可全量训、10GB 卡可推理、异步分块天生适合分布式 |
| VLA 验证/起步 | **ACT**（小、快） | P1 先证明"能学会" |
| VLA 上限 | **π0-FAST**（自回归，~3B，LoRA 微调） | 算力宽裕后的 SOTA |
| 架构演进 | P1/P2 **单机**(3080 直连臂) → P4 **拆分**(RPi5↔局域网↔3080) | 先最快出结果，再长成分布式 |
| 预算 | **~¥6500-8000**（自印可更低） | 落在 ¥5000–10000 内（详见 [hw/bom.md](hw/bom.md)） |

---

## 2. 硬件 BOM（采购清单）

> 完整链接/店铺/状态见 **[hw/bom.md](hw/bom.md)**。这里给概览。

| # | 部件 | 数量 | 参考价 (¥) | 小计 | 说明 |
|---|---|---|---|---|---|
| 1 | SO-ARM101（含 3D 打印件+舵机+驱动板+电源） | 4 | ~879 | **~3500** | 2L+2F；淘宝现货树脂版最省；自印可降 |
| 2 | LeKiwi 底盘（12V，Seeed 含打印件+电池） | 1 | ~1800 | **~1800** | 或 base-only 12V ~¥1501 自印结构件 |
| 3 | RPi 5 (8GB) + 27W 电源 + 有源 USB Hub + 存储 | 1 套 | ~800 | **~800** | 上机驱动板 |
| 4 | USB 相机（1 前置 + 2 腕部） | 3 | ~130 | **~400** | 1080P 免驱；或 ¥138 双相机套件 |
| 5 | 线束/夹具/耗材/电源/网线 等杂项 | — | — | **~600** | |
| | **合计** | | | **~¥7100-8000** | P1 起步(2臂)~¥3300 |

**已拥有（0 成本）**：3080 机（10GB·主家）、3090 机（24GB·训练）、AWU408 双 Orin、3D 打印机、本 Windows 开发机。

**关键提醒**：
- SO-101 **打印件**：官方 STL 可 FDM(PLA) 或光固化；Leader 臂用**轻负载齿轮**才捏得动；**电机 ID 按顺序烧录**。
- 4 条臂 = **2 leader（遥操主手）+ 2 follower（执行从手）**。P1 先买/用 2 条(1L+1F)，P2 再补 2 条。
- LeKiwi 顶板 **M3 螺孔**直接固定 SO-101 底座；12V 底盘自带 12V→5V 降压给 5V 臂。

---

## 3. 系统架构

### 3.1 目标态（P4 整机自主）——瘦边 + 厚芯

```
  算力层（拆两台，同一局域网）
 ┌─────────────────────────────────────────────┐
  │  3080(10GB)＝推理芯 · 挨着机器人：            │
  │   · 遥操（P1/P2：接 leader 臂）/ 采数          │
  │   · policy server（obs→action chunk）        │
  │   · 数据集管理 / HF Hub 上传下载              │
  │  3090(24GB)＝训练芯：                         │
  │   · SmolVLA 全量 / π0-FAST LoRA               │
  │   （数据集·模型经 HF Hub / rsync 两机流转）     │
  └────────────────────────┬────────────────────┘
                           │  局域网 (1Gbps 有线最稳)
        上行: 3相机 + 本体状态(低频~10Hz)
        下行: 动作chunk(每 200~500ms 一批 K 步)
                           │
  ┌────────────────────────┴────────────────────┐
  │  移动机器人 ＝ LeKiwi 底盘 + 2×SO-101(follower) │
  │  RPi 5 驱动板:                                │
  │   · USB: 左/右臂舵机 + 3 底盘轮 (实时 20~30Hz)  │
  │   · USB: 3 相机 (采集 → 推给算力层)            │
  │   · 执行: 收 chunk → 实时插值下发              │
  │   · 安全: 断链 watchdog → 底盘停 / 臂缓回中位   │
  └─────────────────────────────────────────────┘
```

**为什么这样**：VLA 每 200~500ms 只算"一小批"未来动作(异步分块)，网络只传"几张图 + 一小批动作"，带宽占用极小；实时伺服与安全 100% 留在机器人本地(RPi 5)，断网即停。训练/推理拆两台：训练吃显存只有 3090 干得动，推理不吃显存 3080 足够，还挨着机器人。

### 3.2 起步态（P1/P2）——单机，最快闭环

P1/P2 底盘还没上、臂在固定夹/桌上时，**3080 主家直接用 USB 接臂**（1L+1F / 4 条），单机跑 遥操→采集→推理；**训练丢给同局域网的 3090**（数据集经 HF Hub / rsync 过去，模型拉回来），最快打通闭环。等 P3/P4 上 LeKiwi 移动，才切到 3.1 的分布式。

---

## 4. VLA 模型路线（训练：3090 24GB · 推理：3080 10GB）

| 阶段 | 模型 | 训练（3090 · 24GB） | 推理显存（3080 · 10GB） | 作用 |
|---|---|---|---|---|
| P1 起步 | **ACT** | 全量，几分钟~数十分钟 | **<1GB ✅** | 最快证明"采集→训练→会动"闭环 |
| P1→P4 主力 | **SmolVLA** | 全量微调（24GB 舒适） | **fp16 ~2GB ✅** | 语言+视觉驱动，异步推理，部署主力 |
| 上限/进阶 | **π0-FAST** | LoRA 微调（24GB 为此而生） | **~7GB ⚠️ 紧张** | SOTA 泛化，算力富余后上 |

- 数据统一走 **HF Hub**（`lerobot-record` 直接 push）；两台 GPU 机同局域网，大数据集/模型也可 rsync 直传。
- SmolVLA 的 **Real-Time Chunking / 异步推理** 正是为"算力层算、机器人执行"这种拆分设计的，天然契合 3.1。
- π0-FAST 推理在 10GB 上紧张的 3 条后路：**4-bit 量化** / batch=1+bf16 硬试 / **3090 同局域网代推**。

---

## 5. 分阶段实施计划

> 假设业余时间（每周若干小时）。**采购前置**：3D 打印件/套件到货周期可能 1~6 周，P0 期间就下单。
> 每阶段有明确「验收标准」，达到再进下一阶段。

### P0 · 环境 & 工具链（~1~2 周，含下单等货）
**目标**：软件环境全通 + git 库建好 + 硬件下单。
- [ ] **建 git 库**：把本仓库推到你的私库（Gitee/GitHub），3080/3090 clone——此后代码同步全走它
- [ ] **两台 GPU 机装环境**（同一脚本 [env/setup_lerobot.sh](env/setup_lerobot.sh)：自动探测→国内镜像自适应→Py3.12 venv→clone LeRobot→装 `feetech,lekiwi,dataset,smolvla,pi0`→验证 GPU/CLI）：**先 3080 主家**（P1 在它上面跑），**再 3090**（训练用）；各把 [1]~[7] 输出粘回
- [ ] **HF 登录**：两台机器都 `huggingface-cli login`（HF_ENDPOINT=hf-mirror）
- [ ] **固定官方 CLI 命令**（find-port / find-cameras / calibrate / teleoperate / record / train / eval|rollout 的确切 flag，以装好后的 `--help` 实测为准）
- [ ] **下单硬件**（[hw/bom.md](hw/bom.md)，**先 2 条 SO-ARM101 起步**）
- [ ] （可选）验证 AWU408 能否跑 Ubuntu+CUDA+PyTorch（只影响"富余算力"，不阻塞主线）
**验收**：两台 GPU 机 `torch.cuda.is_available()==True`；LeRobot CLI 全 OK；git 库建好且两机已 clone；硬件已下单。

### P1 · 单臂 SO-101 闭环（~2~4 周）⭐核心
**目标**：1 leader + 1 follower，把 **采集→训练→部署** 整条闭环跑通。
- [ ] 组装+校准 1 follower + 1 leader（`lerobot-calibrate`），USB 直连 3080 主家
- [ ] 接 1 相机；遥操作（`lerobot-teleoperate`）验证跟手
- [ ] 采集第一个数据集（简单任务：抓方块 / 放杯子 / 按按钮），`lerobot-record` → push HF Hub
- [ ] 3090 上先训 **ACT** 快速验证能学 → 再训 **SmolVLA**
- [ ] 推理部署（3080 单机直连 follower），手臂独立完成任务
**验收**：**follower 独立完成一个抓取/放置任务**（无人工逐帧干预）；能稳定记录新 episode 并增量再训。

### P2 · 双臂 BiSO-101（~2~4 周）
**目标**：双手协作。
- [ ] 加装 2 条 leader + 1 条 follower（凑 2L+2F），接 3 相机（1 前 + 2 腕）
- [ ] 上 **bimanual 驱动**（`left_*`/`right_*` 前缀；参考 Maker-Mods / Xbotics 的 BiSO-101，移植进 LeRobot）
- [ ] 采集双臂数据（双手递物 / 协同开盒 / 双手抓取）
- [ ] 3090 训双臂 SmolVLA，3080 测双手协作任务
**验收**：双臂协同完成一个需要两手配合的任务。

### P3 · 底盘 LeKiwi（~2~3 周）
**目标**：会走 + 底盘与臂联动。
- [ ] 组装 LeKiwi + 校准（3 轮 STS3215）
- [ ] 上 **LeKiwi 底盘驱动**（LeRobot 原生 `.[lekiwi]` / 或 lerobot-ros 桥），`cmd_vel`/`odom` 跑通
- [ ] 底盘 + **单臂** 联动：边走边摆臂（先不拆网，3080 直连）
- [ ] （可选）雷达 + SLAM / nav2
**验收**：机器人能"边走边完成一个臂任务"。

### P4 · 整机整合（分布式落地）（~3~6 周）
**目标**：把 3.1 的「瘦边+厚芯」跑通，整机自主。
- [ ] 双臂固定到 LeKiwi 顶板，统一 **state/action 空间**（左/右臂关节 + 夹爪 + 底盘速度）
- [ ] 写 **policy server**（**3080 主家**上，FastAPI/GRPC：obs→action chunk；训练仍归 3090）+ **thin client**（RPi 5：推图+收 chunk+实时执行+**fail-safe watchdog**）
- [ ] RPi 5 上机（USB 接 2 臂+3 轮+3 相机），以太网接 3080
- [ ] 采集"整机"遥操数据（人在 leader 处，臂+底盘在 RPi5 处，走网），训一个**同时控制双臂+底盘**的 VLA
- [ ] 端到端任务：**走到桌边 → 双手抓取 → 移动到目标点放下**
**验收**：**无人干预**下，移动机器人完成"走+双手抓取+移动放置"的端到端任务；断网能安全停机。

### P5 · 打磨 / 规模化（持续）
- [ ] 多任务、多数据集、课程式学习
- [ ] 异步推理提速、动作 chunk 调参、fail-safe 加固
- [ ] （可选）sim2real（IsaacLab-Arena / EnvHub）、力控/触觉扩展、π0-FAST 上限冲刺

---

## 6. 目录结构约定

```
（本 Windows 写字台 & 两台 GPU 机共用同一仓库，GPU 机上放 ~/robot/）
robot/
├─ PLAN.md                    # 本方案（单一事实来源）
├─ README.md                  # 仓库导览
├─ hw/
│  └─ bom.md                 # 采购清单/链接/到货状态
├─ env/
│  ├─ machines.md            # 机器拓扑 + 协作模型
│  └─ setup_lerobot.sh       # GPU 机一键装环境（3080/3090 都跑）
├─ lerobot/                  # LeRobot 仓库 clone（各 GPU 机自己 clone，不入库）
├─ robots/
│  └─ bi_so101_lekiwi/       # 本机器人的 LeRobot robot 定义（双臂+底盘驱动，P2/P3）
├─ configs/
│  ├─ teleop/  record/  train/  eval/   # 各场景的 .toml/.yaml 配置
├─ server/                   # policy server（3080 主家上，P4）
├─ client/                   # thin client + 执行 + fail-safe（RPi 5 上，P4）
└─ docs/                     # 组装/校准/CLI参考/踩坑笔记
```

> 说明：**3080 主家与 3090 训练机都 clone 本仓库 + LeRobot**（目录统一 `~/robot/`）；本 Windows `D:\robot\lerobot` 是源头，你 push 到 git 库后两机 pull。**数据集/模型不入 git**（走 HF Hub / rsync）。

---

## 7. 风险 & 待验证项

| # | 风险/未知 | 影响 | 对策 |
|---|---|---|---|
| 1 | **两台 GPU 机都不在我沙箱里（无外网）** | 我无法直接跑命令 | **协作**：我写 → 你 push git → 3080/3090 跑 → 粘回输出（见 machines.md） |
| 2 | **CLI flag 随版本变**（0.5→0.6 有差异） | 照旧文档会报错 | 装好后以 `--help` 实测为准（记到 docs/cli_reference.md） |
| 3 | **双臂驱动非官方内置**（靠社区 BiSO-101 移植） | P2 要多写/改驱动 | 参考 Maker-Mods/Xbotics，必要时自写 `bi_so101_follower` |
| 4 | **LeKiwi 驱动**：LeRobot 原生 `.[lekiwi]` vs lerobot-ros 桥 | P3 集成方式 | 优先 LeRobot 原生 lekiwi；不行再上 ROS2 桥 |
| 5 | **局域网可靠性**（WiFi 抖动 → 臂卡顿） | P4 体验/安全 | 优先**有线 1G**；client 带 watchdog 断链即停 |
| 6 | **AWU408 能否跑 Ubuntu+PyTorch**（常出厂 QNX/DRIVE OS） | 只影响"富余算力" | 非阻塞；跑不了就不管它 |
| 7 | **硬件到货周期**（3D 打印件 1~6 周） | 拖慢 P1 起步 | P0 立即下单，等货期间把软件全搭好 |
| 8 | **RPi 5 USB 口不够**（2臂+3轮+3相机≈6-8 设备） | 上机接线 | 用**有源 USB 3.0 Hub**；相机降到 2 个 USB3 口 |
| 9 | **GPU 机网络可达性**（能否直连 pip/HF/github） | 装环境速度/成败 | `setup_lerobot.sh` 自动探测并切国内镜像 |
| 10 | **π0-FAST 推理 ~7GB，3080 10GB 紧张** | P5 上限模型部署 | 4-bit 量化 / batch=1+bf16 / 3090 同局域网代推 |

---

## 8. 下一步（P0 第一步 · 现在就能做）

1. **建 git 库**：把 `D:\robot\lerobot` 推到你的私库（Gitee 国内快 / GitHub 均可），两台 GPU 机 clone。
2. **两台 GPU 机装环境**：clone 后在 **3080 主家** 与 **3090** 各跑一遍 `env/setup_lerobot.sh`，各把 **[1]~[7] 完整输出粘回**。
3. **下单**：[hw/bom.md](hw/bom.md) 先买 **2 条 SO-ARM101（1L+1F）** 起步。
4. **HF 登录**：两台机器都 `huggingface-cli login`（脚本已配 hf-mirror）。

> **协作**：我(本机)写 → 你 push git → 3080/3090 跑 → 粘回输出 → 我迭代。
> 装环境输出回来后，我就铺 **P1 的具体命令/配置**（第一条臂的 find-port / 校准 / 遥操 / 采集）。