yuchen-roboinfra 0.0.1

Personal robotics infrastructure: control, teleop, sensors, intervention

RoboInfra

个人长期维护的机器人基础设施项目,目标覆盖四块功能:

1. 机器人控制
2. Teleoperation
3. Sensor / Policy / Robot 通信
4. Human intervention(参考 Physical Intelligence π-0.6 的 Recap 思路)

长期开发计划与架构

给我自己看的(maintainer 视角):

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

给下游用户看的(public 视角):

• README.md — 30 秒说明、install、三层 surface(Python API / app runners / setup CLIs)、5 个 quickstart recipe、scope 边界。GitHub 主页第一印象。
• 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