Metadata-Version: 2.4
Name: yuchen-roboinfra
Version: 0.0.2
Summary: Personal robotics infrastructure: control, teleop, sensors, intervention
Requires-Python: >=3.11
Requires-Dist: msgpack>=1.0
Requires-Dist: numpy>=1.26
Requires-Dist: pydantic>=2.6
Requires-Dist: pyyaml>=6.0
Requires-Dist: pyzmq>=26.0
Requires-Dist: typing-extensions>=4.10
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: mujoco
Requires-Dist: mujoco>=3.0; extra == 'mujoco'
Provides-Extra: quest3
Requires-Dist: robovr>=0.1.0; extra == 'quest3'
Provides-Extra: recording
Requires-Dist: lerobot>=0.1; extra == 'recording'
Provides-Extra: so101
Requires-Dist: feetech-servo-sdk>=1.0; extra == 'so101'
Provides-Extra: teleop-factr
Requires-Dist: dynamixel-sdk>=3.7; extra == 'teleop-factr'
Requires-Dist: pin>=2.7; extra == 'teleop-factr'
Description-Content-Type: text/markdown

# RoboInfra

个人长期维护的机器人基础设施项目,目标覆盖四块功能:
1. 机器人控制
2. Teleoperation
3. Sensor / Policy / Robot 通信
4. Human intervention(参考 Physical Intelligence π-0.6 的 Recap 思路)

## 长期开发计划与架构

**给我自己看的(maintainer 视角)**:
- **[`plan.md`](./plan.md)** — 阶段路线图、任务拆解、设计决策(D1-Dn)、接口签名草稿、intervention FSM。**所有讨论的最终落点在这里**,不在 chat 里。
- **[`architecture.md`](./architecture.md)** — ASCII 架构图,分层 / channel / RT 进程切分 / teleop 拓扑 / FSM / sim-real / 数据流。直观索引。
- **[`reference.md`](./reference.md)** — 逐文件、逐类的开发参考(职责 / 字段 / 用法 / 关联设计决策)。改 Protocol / 加类型时同步更新。

**给下游用户看的(public 视角)**:
- **[`README.md`](./README.md)** — 30 秒说明、install、三层 surface(Python API / app runners / setup CLIs)、5 个 quickstart recipe、scope 边界。GitHub 主页第一印象。
- **[`docs/api.md`](./docs/api.md)** — 公共 API 参考,按 import surface 分组,每个 top-level 公共符号一节。**改 `roboinfra/__init__.py` 或任何子包 `__init__.py` 的 export 时必须同步**。

每次启动新工作前先看 `plan.md` / `architecture.md` / `reference.md` 这三份(maintainer);改公共 API 时连带 `README.md` / `docs/api.md`(public)。有调整就更新对应文件,不要让图、代码、文档漂移。

## 已锁定的技术栈

- **Robots**:Franka Panda(7-DoF, libfranka 1kHz)+ SO-101(LeRobot 原生)。
- **Teleop**:两套**同构** leader-follower 链路,不做跨机 retarget。
  - **FACTR leader → Franka follower**(力反馈,leader ~500-1000Hz,follower 1kHz FCI,独立 RT 进程)— 设计驱动 / 优先实现
  - SO-101 leader → SO-101 follower(全 Python,~30Hz)— 验证 / 第二阶段
- **Transport**:ZMQ pub/sub(高频流)+ gRPC(命令/服务)。**不**上 ROS 2,除非具体设备强制。
- **数据集**:LeRobot v2(parquet + mp4)为唯一主存储;Robomimic HDF5 仅作按需 export。
- **Sim**:MuJoCo(默认 / CI)+ Isaac Sim(复杂场景、domain rand)。两者与实机共用同一 ZMQ topic 与 `Robot` 接口。
- **Python**:3.11+,uv 管理依赖。

## 架构分层

```
roboinfra/                       (库本身,import 入口)
  apps/         配置驱动的通用 runner(teleop_collect, eval, replay 等)
  runtime/      节点编排、模式 FSM、E-stop
  intervention/ Arbiter + Blender + 三态标注(POLICY / INTERVENE / RECOVERY)
  policies/     本地 + 远端(openpi 协议)
  teleop/       so101 / factr / quest / spacemouse / pedal(D9)
  recording/    LeRobot v2 writer + intervention 扩展;converters/ 出 robomimic
  sim/          mujoco / isaac,与 robots/ 同接口
  robots/       franka / so101 / mujoco / isaac 后端
  sensors/      camera / imu / f-t
  calibration/  leader_arm / robot_arm / camera 标定 schema + 算法 + I/O
  core/         types / transport / codec / sync / sim_clock

examples/       demos / 烟测(证明组件可用,不是项目代码)
tools/          reference CLI(calibrate / data inspect / replay 等)
assets/         reference robot models / URDFs(mujoco_menagerie 子集 + FACTR)
configs/        示例配置
tests/          契约 + 单元测试
```

下层不依赖上层。`core/` 不依赖任何业务模块。

## 工作约定

- **RoboInfra 是 library,不是项目**(D12):提供可重用组件,不写项目代码。下游项目单独 repo 用 `import roboinfra.*`,在那边写 launcher / 配置 / scene / training pipeline。`roboinfra/apps/` 只放配置驱动的通用 runner;demos / 烟测在顶层 `examples/`;reference CLI 在 `tools/`。任何 hardcoded 项目语义(scene 文件名、特定任务参数、dataset 路径)都 reject。
- **抽象以 Franka 为驱动**:接口必须容纳 Franka 的能力上限(1kHz、多控制模式、RT 进程边界、chunk action),SO-101 自然是 strict subset。反过来不行。
- **Leader / follower 必须解耦**(D10):任何 `Teleop` 实现不允许子类化或直接持有 `Robot`;两者通过 transport 通信。同进程跑两者通过线程 + ZMQ inproc 实现,不通过类继承。
- **不写 low-level PD/PID**(D11):`Action.kp/kd` 只是 pass-through 给下游已有 impedance controller(libfranka / MJCF actuator / servo 固件)。`core/` 和 `runtime/` 不允许出现 cycle-level 控制环代码;真要 1kHz 自定义控制,写 C++ RT 放进 `franka_rt_node`。FACTR leader 的 torque computation 是唯一例外,严格限定在 `roboinfra/teleop/factr/`。
- **训练 pipeline 不在本仓库**(D13):dataset 加载 / 优化器 / loss / 模型架构 / ckpt 管理都属于下游 training repo,即使是「通用训练框架」也别放这(很容易长出特定任务的钩子)。**但 Policy adapter 在**:`Policy` Protocol + `LocalPolicy`(包任意 callable)+ `RandomPolicy`(测试)+ `RemotePolicy`(P7)在 `roboinfra/policies/`,下游训完模型写一个 `(obs)→ndarray` callable 塞进 `LocalPolicy` 就接进 pipeline,**不动 infra**。`roboinfra/policies/` 只允许 adapter,不准放具体模型架构(ACT / DP / π0 都是);最小可跑的接入参考(如 DP)放 `examples/`。
- **`Teleop` Protocol 必须 thin**(D9):FACTR 现做,但接口要容纳未来的 Quest VR / Spacemouse / Gamepad / Pedal。设备特有的逻辑(500Hz 线程、Dynamixel、Pinocchio、力反馈控制律)只能在 `roboinfra/teleop/<device>/` 子模块里,不能渗到 Protocol。
- **FACTR 迁移规则**:从 `FACTR_Teleop/` 搬进来的代码必须先脱掉 ROS 2 / ABC 通信壳、解耦 leader 与 follower、改用 `core.transport`、消息时间戳改 `time.monotonic_ns()`。详见 `plan.md` 第 6 节迁移清单。
- **频率分层**:1kHz 控制环只跑在独立 RT 进程,Python 应用层一律 ~30-50Hz,不进硬实时。
- **接口先行**:每加一个 driver/policy 之前,先在 `core/` 或对应模块定义/复用接口,再写实现。
- **配置走 YAML**:运行参数(ports, IPs, topic 名, control gains)走 `configs/`,代码里不写 magic value。
- **数据格式**:不自造 dataset schema,扩展走 LeRobot 的 `extra` 字段。
- **测试**:任何 driver/policy 都先在 MuJoCo 后端跑通再上实机。
- **注释**:只写 *why*,不写 *what*。命名清楚就别加注释。
- **不要过度设计**:个人项目,优先维护成本低,不写没用的抽象层和未来可能用到的钩子。
- **改公共 API 同步 `docs/api.md`**:`roboinfra/__init__.py` 或任何子包 `__init__.py` 的 export 列表 / 顶层 class signature 改了 → 同一 commit 里更新 `docs/api.md` 对应 section。新加 top-level export → `docs/api.md` 加一节。`README.md` 只在三层 surface 结构变化时才动(增减 layer),普通 API 改动不触动它。

## 仓库布局(规划中,以 `plan.md` 为准)

```
roboinfra/{core,robots,sensors,teleop,policies,intervention,recording,sim,runtime,apps}/
configs/{robot,sensor,policy,scene,sim}/*.yaml
tools/{calibrate,viz,bag_inspect}.py
tests/
pyproject.toml
plan.md
CLAUDE.md
```
