Dual Franka#

RPent 可以通过 RLinf RealWorldEnv worker 控制双节点双臂 Franka 系统。

安装#

备注

以下的步骤只会安装 Python 侧依赖（自定义的 RLinf Franka 分支和 rlinf-openpi），并不会构建双臂真正需要的机器人节点控制栈。在安装 RPent 之前，请先按照 RLinf 双臂 Franka 指南配置两个机器人节点：选择兼容的 LIBFRANKA_VERSION，构建 franka-franky （franky/libfranka）控制栈，配置 PREEMPT_RT 实时内核与相关权限，并安装 GELLO 遥操作与夹爪依赖。参见 RLinf 双臂 Franka 指南。

在 RPent 仓库根目录运行：

uv sync --extra franka

该命令将自定义 RLinf Franka 分支和 rlinf-openpi 安装到 .venv。

标定（Calibration）#

手眼标定使用 ROS easy_handeye 完成。它为每台投影相机（ base_camera 和 d455_camera）生成一个 YAML，默认保存在 ~/.ros/easy_handeye/ 下。

RPent 会读取一个 JSON 文件（hand_eye_calibration.json），其中包含每台相机的 source_name、parameters 和 transformation。生成方式是从每个 easy_handeye YAML 中复制这些字段。

该文件的位置可通过 --calibration-path 配置（默认 ~/.ros/easy_handeye/hand_eye_calibration.json）。

开发配置#

启用机械臂运动前，请检查并修改仓库中的开发默认值：

robots/dual_franka/config/example.yaml 包含机器人身份（两台机器人 IP、相机序列号/类型、夹爪连接）、工作空间几何（目标位姿、安全边界）和感知定位边界 + base-frame 变换。

RPent 会将该机器人配置转换成内部双节点 RLinf cluster 和环境对象。如需使用其他文件，请传入 --robot-config /path/to/robot_config.yaml。

启动双节点 Ray 集群#

两个节点的角色不同（定义在 robots/dual_franka/runtime_config.py 中）：

节点 0 是 Ray head 节点：运行双臂 Franka 环境 worker （全部相机、感知以及双臂和夹爪状态）和**左臂**的实时控制器。VLA 任务的本地 VLA 服务也运行在该节点上。
节点 1 是 Ray worker 节点：只运行**右臂**的实时控制器，不接相机，也不运行 RPent 进程。

每个控制节点都必须在启动 Ray 前设置 RLINF_NODE_RANK。

节点 0：

export RLINF_NODE_RANK=0
ray stop --force
ray start --head --port=6379 --node-ip-address=HEAD_IP

节点 1：

export RLINF_NODE_RANK=1
ray stop --force
ray start --address=HEAD_IP:6379 --node-ip-address=WORKER_IP

运行冒烟测试#

任务 0 用于测试稳妥的单臂解析式运动和夹爪 primitives：

uv run --extra franka rpent --robot dual_franka --task-id 0 \
  --planner claude_code --model claude-opus-4-8 \
  --robot-config robots/dual_franka/config/example.yaml \
  --calibration-path ~/.ros/easy_handeye/hand_eye_calibration.json

RPent 使用当前解释器启动 robots/dual_franka/env_server.py，加载 RPent robot config 并生成内部 RLinf adapter config，然后连接 Ray，等待 healthz，并将初始状态记录为 step 0。任务 0 不会加载 VLA。

VLA 抓取 DEMO#

RPent 提供了一个使用 VLA 抓取物品的 DEMO。task-id 1 会暴露 vla_grasp，并可在本地启动双臂 Franka VLA 服务。PI05_CHECKPOINT_PATH 指向训练好的 Pi-05 checkpoint，DUAL_FRANKA_REPO_ID 是用于查找对应归一化统计的数据集 ID：

export PI05_CHECKPOINT_PATH=/path/to/checkpoints/global_step_N
export DUAL_FRANKA_REPO_ID=org/dual-franka-tcp-rot6d

uv run --extra franka rpent --robot dual_franka --task-id 1 \
  --cuda-device 0 \
  --planner claude_code --model claude-opus-4-8 \
  --robot-config robots/dual_franka/config/example.yaml \
  --calibration-path ~/.ros/easy_handeye/hand_eye_calibration.json

checkpoint 必须包含：

actor/model_state_dict/full_weights.pt
<DUAL_FRANKA_REPO_ID>/norm_stats.json

预训练 checkpoint

ModelScope 上发布了一个可直接使用的 task 1 checkpoint： Brunchlife/pi05-dualfranka-tcp-rot6d-clean-desk-532-delect-76000。下载后将 PI05_CHECKPOINT_PATH 指向下载目录，并将 DUAL_FRANKA_REPO_ID 设置为包含 norm_stats.json 的子目录：

modelscope download \
  --model Brunchlife/pi05-dualfranka-tcp-rot6d-clean-desk-532-delect-76000 \
  --local_dir /path/to/pi05-dualfranka-clean-desk

export PI05_CHECKPOINT_PATH=/path/to/pi05-dualfranka-clean-desk

警告

该 checkpoint 仅在我们的内部测试环境（机器人位姿、相机、工作空间布局和物体）上训练，切换到不同的环境时预计表现会较差。若要部署到你自己的机器上，请使用 RLinf 采集示教数据并微调你自己的 checkpoint，参见 RLinf 双臂 Franka 指南（采集 GELLO 示教数据、转换为 tcp_rot6d、运行 SFT，然后部署）。

未设置 --vla-endpoint 时，RPent 会启动 robots/dual_franka/vla_server.py，并只加载一次 pi05_dualfranka_tcp_rot6d。

也可以单独启动 VLA 服务：

uv run --extra franka python -m robots.dual_franka.vla_server \
  --model-path /path/to/checkpoints/global_step_N \
  --repo-id org/dual-franka-tcp-rot6d \
  --cuda-device 0 --transport http --host 0.0.0.0 --port 6000

然后向 rpent 传入 --vla-endpoint http://VLA_HOST:6000。外部 endpoint 始终优先于本地自动启动。

连接外部环境服务#

连接已经运行的双臂 Franka 环境服务：

uv run --extra franka rpent --robot dual_franka --task-id 0 \
  --env-endpoint http://ROBOT_HOST:PORT \
  --planner claude_code --model claude-opus-4-8 \
  --robot-config robots/dual_franka/config/example.yaml \
  --calibration-path ~/.ros/easy_handeye/hand_eye_calibration.json

工具与状态产物#

双臂 Franka 扩展提供 view_env_state、view_camera_meta、 move_delta、rotate_delta、open_gripper、close_gripper 和 vla_grasp。每次解析式运动只会作用于一条臂（left 或 right）。所有会改变环境状态的工具都会在 RPent 统一的 EnvState 中保存每条臂的状态以及同步的 left-wrist、base 和 right-wrist 图像。

安全要求#

两条臂都必须有操作员留在急停按钮旁。先使用极小的单臂动作验证任务 0，再尝试抓取。当相机与状态结果不一致、目标运动没有到位，或任何标定存在疑问时，应立即停止。