OpenArm 2.0(开源仿人双臂) 复刻全流程
OpenArm 2.0(开源仿人双臂) 从采购、打印、组装到装软件、标定和训练的 113 个步骤,附物料表、购买链接与官方出处。
官方称完整双臂系统 6,500 美元(README 与 LeRobot 文档;openarm.dev 把这个数字标为物料成本)。认证厂商 WowRobo 整机 6,500 美元(不带顶部双目相机)或 7,300 美元(带),2026‑11‑01,运费与进口关税另计;DIY 套件价格未列
采购
- 购买已组装或 DIY 版 OpenArm
浏览 openarm.dev,查找全球经过验证和认证的制造商,以获取已组装或 DIY 版 OpenArm。
- 查看物料清单
按照 OpenArm 官方硬件文档中的物料清单和采购说明操作。
- 购买 OpenArm
通过购买页面获取已组装或 DIY 版本的 OpenArm。
打印与加工
- 遵循 3D 打印说明
按照 OpenArm 官方硬件文档中的 3D 打印说明操作。
组装
- 固定机械臂安装
使用螺钉或夹具将机械臂固定在平坦、稳定的表面上。
- 完成机械组装
按照 OpenArm 官方硬件文档中的机械组装说明操作。
- 连接电气布线
按照 OpenArm 官方硬件文档中的电气布线说明操作。
- 检查 CAN 总线接线
检查 CAN-H、CAN-L 和 GND 接线。
软件与固件
- 安装 Miniforge
使用文档提供的下载和安装命令安装 Miniforge。此步骤仅适用于使用 conda 的用户。
- 创建 Python 3.12 环境
使用 conda 创建 Python 3.12 虚拟环境,或使用 uv 安装 Python 3.12 并创建环境。
- 激活虚拟环境
每次打开 shell 时激活 lerobot conda 环境,或根据 Linux/macOS 或 Windows PowerShell 使用相应的命令激活 uv 环境。
- 在 WSL 中安装 evdev
在 WSL 中安装 LeRobot 时,使用文档提供的 conda 或 Ubuntu 命令安装 evdev。
- 检查 Apple Silicon 要求
在 Apple Silicon 上,PyTorch 需要 macOS 14 或更高版本。MPS 加速需要 macOS 15 或更高版本;在 macOS 14 上,LeRobot 会回退到 CPU。
- 检查 Linux NVIDIA 要求
在 Linux 上,默认的 PyTorch 轮子需要 580.65 或更高版本的 NVIDIA 驱动程序。对于较旧的驱动程序,请参阅 PyTorch CUDA 变体。
- 检查 ffmpeg 要求
LeRobot 默认使用 TorchCodec 解码视频,因此需要 ffmpeg。在 macOS Intel (x86_64) 和 Linux armv7l 上请跳过安装,因为 LeRobot 会自动回退到 pyav。
- 在 Jetson 上使用 CPU 视频解码
在采用 aarch64 和 CUDA 的 Jetson 上,视频解码默认在 CPU 上运行。提供的 Jetson Dockerfile 会为 JetPack 6.2 从源代码构建 torch 和 torchcodec,并启用 CUDA 支持。
- 在 conda 环境中安装 ffmpeg
在 conda 环境中安装 ffmpeg。此方法适用于所有 PyTorch 版本,并且 PyTorch 2.10 之前的版本必须使用此方法。
- 使用系统级 ffmpeg
使用 PyTorch 2.10 或更高版本以及 TorchCodec 0.10 或更高版本时,TorchCodec 可以动态链接到系统级 ffmpeg 安装。这适合使用 uv 或其他非 conda 环境管理器的情况。
- 在 Ubuntu 或 Debian 上安装 FFmpeg
系统级安装 ffmpeg。系统级 ffmpeg 需要 PyTorch >= 2.10(TorchCodec ≥ 0.10);使用较旧版本 PyTorch 时,应改用 conda install ffmpeg -c conda-forge。
- 在 Apple Silicon macOS 上安装 FFmpeg
使用 Homebrew 系统级安装 ffmpeg。系统级 ffmpeg 需要 PyTorch >= 2.10(TorchCodec ≥ 0.10)。
- 克隆 LeRobot 仓库
克隆 lerobot 仓库并进入该目录。
- 以可编辑模式安装机器人工作流依赖
使用 core_scripts 附加项以可编辑模式安装库,用于记录、回放和校准工作流。
- 以可编辑模式安装策略训练依赖
使用 training 附加项以可编辑模式安装库,用于训练策略。
- 安装全部可编辑模式依赖
以可编辑模式安装库,并包含所有策略、环境、硬件和开发工具。
- 使用 uv 安装可编辑模式机器人工作流
使用 uv 以可编辑模式安装库,并通过 core_scripts 提供记录、回放和校准工作流。
- 使用 uv 安装可编辑模式训练依赖
使用 uv 通过 training 附加项以可编辑模式安装库,用于训练策略。
- 使用 uv 安装全部可编辑模式依赖
使用 uv 以可编辑模式安装库,并包含所有策略、环境、硬件和开发工具。
- 安装 LeRobot 基础软件包
从 PyPI 安装基础 lerobot 软件包。该安装仅包含核心机器学习依赖。
- 使用 uv 安装 LeRobot
使用 uv 从 PyPI 安装基础 lerobot 软件包。该安装仅包含核心机器学习依赖。
- 安装机器人工作流附加功能
安装组合附加项 core_scripts,以支持记录、回放和校准。
- 安装策略训练附加功能
安装 training 附加项以支持策略训练。
- 安装记录和训练附加功能
安装 core_scripts 和 training 组合附加项,以支持记录和训练。
- 安装全部 LeRobot 附加功能
安装全部 LeRobot 功能附加项。
- 安装 Pi 策略依赖
安装 Pi0、Pi0.5 和 Pi0-FAST 的策略依赖。
- 安装 SmolVLA 策略依赖
安装 SmolVLA 策略所需的依赖。
- 安装扩散策略依赖
安装扩散策略依赖,包括 diffusers。
- 安装仿真环境依赖
安装 ALOHA 和 PushT 仿真环境的依赖。
- 安装 Feetech 电机支持
安装提供 Feetech 电机支持的附加项。
- 选择正确的 PyTorch 安装方式
在 macOS 和 Windows 上使用默认的 PyPI wheel,并跳过 CUDA 专用部分。在使用较旧驱动或 GPU 的 Linux 系统上,先从匹配的索引安装 PyTorch,再安装 LeRobot。
- 安装 CUDA 12 PyTorch
为仅支持 CUDA 12 的驱动安装 CUDA 12.6 的 PyTorch 和 torchvision wheel。由于 torch 2.15 没有 CUDA 12 构建,CUDA 12 索引会安装 torch 2.14 或更旧版本。
- 安装 CPU TorchCodec
由于 Linux 上默认的 PyPI TorchCodec 包是 CUDA 13 构建,请从 CPU 索引安装 TorchCodec。当 torch 低于 2.11 时,从 TorchCodec 兼容性表中选择匹配的版本。
- 安装 LeRobot
使用源码检出并安装全部可选依赖,或从 PyPI 安装已发布的包。根据安装来源选择源码或 PyPI 命令。
- 使用 uv 安装 LeRobot
使用 uv pip 的 torch 后端选择器,一步安装使用 CUDA 12.6 构建的 LeRobot。
- 更改 uv 的 CUDA 构建
uv sync 命令使用已提交的 lock 文件。要更改 CUDA 构建,请在 pyproject.toml 的 [tool.uv.index] 和 [tool.uv.sources] 中添加索引,然后重新生成 lock 文件。
- 安装构建依赖
如果遇到构建错误,请在 Linux 上安装 cmake、build-essential、Python 开发头文件、pkg-config 以及列出的 FFmpeg 开发库。对于其他系统,请遵循 PyAV 的 FFmpeg 安装说明。
- 组合可选依赖扩展
仅安装所需功能的可选扩展,可以组合多个扩展。
- 安装仿真环境
可安装 aloha 或 pusht;libero 仅支持 Linux,也可安装 metaworld。这些扩展会自动包含 dataset 扩展,使用 uv 时可将 pip install 替换为 uv pip install。
- 安装电机控制支持
为 SO100、SO101 或 Moss 安装 feetech,或为 Koch v1.1 安装 dynamixel。两种电机控制扩展都通过 rustypot 与电机通信。
标定与测试
- 找到紧急停止装置
了解紧急停止装置的位置及其操作方式。
- 操作前检查机械臂
检查螺钉是否松动、机械限位是否损坏、是否有异常声音以及布线是否损坏。
- 配置跟随臂
按照文档表格中的选项配置跟随臂。
- 配置主臂
按照文档表格中的选项配置主臂。
- 应用电机默认配置
使用电机配置表中的默认值配置达妙电机。
- 检查电源连接
确认电源连接牢固。
- 运行 CAN 诊断
在 can0 接口上运行 CAN 诊断测试。
- 检查 CAN 接口
确认 can0 CAN 接口已正确配置。
- 验证 ROS 2 安装
运行 `ros2 -h` 和 `ros2 topic list`,验证 ROS 2 安装。
- 解决 ffmpeg 版本问题
这通常会安装带有 libsvtav1 编码器的 ffmpeg 8.X。如果缺少 libsvtav1 或出现 torchcodec 版本不匹配,请明确安装 ffmpeg 7.1.1。
采数据与训练
- 写入 0.4.0 格式数据集
使用 dora-openarm-dataset-recorder 或 Dataset.write() 写入数据集;当前格式版本为 0.4.0。
- 创建数据集目录结构
每个 episode 目录包含 action、cameras 和 obs 三个子目录,数据集根目录包含 metadata.yaml。手臂状态保存为 state.parquet,升降器状态保存为 elevation.parquet,相机图像保存为 JPEG 文件。
- 分别记录每个会话
将每个会话记录到新的数据集目录;录制时 episode ID 按顺序分配,取消的 episode 会被删除,因此 ID 可能有间隔。
- 合并兼容的会话数据集
使用 openarm-dataset-merge 合并会话数据;待合并数据集的 metadata.yaml 中版本、设备和频率必须完全相同。
- 统一待合并会话的设置
需要合并的会话必须使用相同的机器人、leader 和 dataflow 进行录制。
- 每个样本保存一行手臂状态
在 obs/arms/<side>/state.parquet 和 action/arms/<side>/state.parquet 中为每个样本保存一行,其中 side 为 right 或 left。timestamp 列使用纳秒 Unix 时间,其余各列是表示一个属性 float32 值的列表。
- 映射手臂状态属性
obs 通常包含 qpos、qvel 和 qtorque;action 包含 dora-openarm-data-collection 数据流中的 qpos,或在直接记录末端执行器目标时包含 pose。gripper 是夹爪电机位置,pose 使用 openarm_control 的坐标系约定。
- 检查右臂状态数据
读取 episodes/0/obs/arms/right/state.parquet,并检查 timestamp、qpos、qvel 和 qtorque 列。首个 qpos 样本包含 8 个 float32 数值。
- 读取升降器高度数据
检查 obs/lifter/elevation.parquet 和 action/lifter/elevation.parquet 中的 timestamp 与 value 列。value 是包含一个数值的列表,表示 OpenArm Cell 升降器从底部起算的毫米高度。
- 整理五路相机数据
每路相机可保存为 cameras/<name>/<timestamp>.jpeg 目录,也可保存为包含相同 JPEG 文件的 cameras/<name>.tar 未压缩归档。文件名使用相机消息的 Unix 纳秒时间戳,上传 Hugging Face Hub 时推荐 tar 格式。
- 填写数据集元数据
在 metadata.yaml 中记录整个数据集的版本、位置、操作员、操作类型、任务、回合、设备、感知配置和频率。OpenArm Cell 元数据还描述 lead_screw 机构、5.0 毫米导程、300 毫米行程、底部原点及 mm 单位。
- 统一任务提示文本
为同一任务使用相同的 prompt,因为 openarm-dataset-merge 会将具有相同 prompt 的任务视为同一任务。prompt 是显示在数据采集 Web UI 中并用于 LeRobot、GR00T 和 robot_eval_logger 转换的简短任务指令。
- 配置采集元数据
在 dora-openarm-data-collection 的数据流元数据文件 metadata_$ROBOT.yaml(例如 metadata_cell.yaml)中设置 location、operator 和 tasks。记录器还会添加 version、operation_type、episodes、frequencies、equipment.leader (KER) 和 model (rollout)。
- 读取旧格式并写出新格式
openarm_dataset 可以读取 0.1.0–0.3.0 和未标版本号的旧格式。Dataset.write() 或 openarm-dataset-convert --format openarm 始终写出最新格式。
- 打开并检查数据集
让 Dataset 指向一次录制的根目录,并检查 episode 数量、版本和任务。示例数据集包含 2 个 episode,版本为 0.4.0。
- 选择 Episode 对象
dataset.meta.episodes 是 Episode 对象列表。将 Episode 对象而不是整数索引传递给后续加载方法;示例 episode 的 id 为 0、success 为 False、task_index 为 0。
- 加载观测与动作数据
使用 dataset.load_obs(episode) 和 dataset.load_action(episode) 读取 episode 数据,返回按信号名索引的 pandas DataFrame 字典,包含 arms/right 与 arms/left 的 qpos、qvel、qtorque 以及 lifter/elevation。
- 使用浮点时间戳索引
向加载函数传入 use_unixtime=True,可获得浮点数索引而不是 datetime 索引。
- 转换为 qpos、pose 或 rot6d 表示
通过 state="qpos"、state="pose" 或 state="rot6d" 选择表示形式,录制数据会即时转换:qpos 转 pose 用正向运动学,pose 转 qpos 用逆向运动学,运动学由 openarm_control 计算。
- 从录制的 qpos 做逆运动学求解
逆向运动学从该 episode 录制的 qpos 出发,无法求解的样本会显示警告;夹爪值直接透传,数据集文件不会被修改。
- 加载并检查相机帧
加载 episode 的相机帧,检查 `ceiling`、`head_left`、`head_right`、`wrist_left` 和 `wrist_right` 相机。获取 ceiling 相机的第 0 帧,它返回形状为 `(600, 960, 3)` 的 NumPy 数组,并可遍历该相机的所有帧。
- 采样同步时间步
以 30 Hz 对齐 observation、action 和相机帧,使其可作为一个 timestep 使用。样本包含时间戳、左右臂的 qpos、qvel、qtorque 以及 `lifter/elevation`,每个相机的图像 shape 为 `(600, 960, 3)`。
- 验证数据集
运行数据集验证工具,检查 null 和 NaN 值、qpos 突跳、超范围 qpos、无效姿态四元数以及过短的 episode。默认会将结果记录为 `metadata.yaml` 中每个 episode 的 valid 标志;使用 `openarm-dataset-convert --valid-only` 时会跳过无效 episode,旧格式数据集需先用 `openarm-dataset-convert --format openarm` 转换,或使用 `--no-update-metadata`。
- 转换为 LeRobot 数据集
将 OpenArmDataset 转换为 LeRobot Dataset,可选择 lerobot_v2.1 或 lerobot_v3.0 格式。
- 配置转换选项
使用 --state {qpos,pose,rot6d} 选择机械臂状态表示,默认值为 qpos;使用 --arm-dynamics 还将关节速度和扭矩导出为 observation.velocity 和 observation.torque。
- 筛选数据集片段
使用 --success-only 仅包含成功的片段,使用 --valid-only 仅包含有效的片段。
- 使用其他数据格式
--format 还支持 gr00t(GR00T LeRobot)、robot_eval_logger 和 openarm(最新的 OpenArm Dataset 格式)。
- 打包相机数据
使用 --format openarm --camera-format tar 时,每个相机会存储为单个 tar 归档,推荐用于上传到 Hugging Face Hub。
- 将运行同步到 Space
先进行 Hugging Face 身份验证,再使用 --trackio.space_id=<user>/<space> 指定目标 Space。如果 Space 不存在,系统会创建它。
- 配置远程作业跟踪
使用 --job.target 启动的远程作业启用跟踪时必须提供 space_id,因为作业结束后 pod 的本地数据库会丢失。
- 设置 Space 隐私选项
除非组织默认设置为私有,否则新 Space 默认公开。创建私有 Space 时传入 --trackio.private=true。
- 控制控制台输出捕获
每次运行都会记录启动命令和控制台输出,包括打印信息、日志和回溯,并在运行页面中显示。在 Space 上,这些内容的可见性与 Space 本身相同;使用 --trackio.capture_console=false 可不记录控制台输出。
用起来
- 阅读官方安全指南
操作 OpenArm 前阅读官方安全指南。
- 保持安全操作距离
操作期间使身体部位和物体保持在机械臂运动范围之外。
- 佩戴必要的防护装备
始终佩戴安全护目镜,并按需使用其他个人防护装备。
- 遵守负载限制
每条机械臂的负载不得超过峰值 6.0 kg 或标称 4.1 kg。
- 设置单向主从遥操作
让 follower arm 通过位置指令直接复现 leader arm 的动作,不返回力反馈。此模式简单稳健,适合初步测试和自由空间运动。
- 设置双向力反馈遥操作
在 leader arm 与 follower arm 之间启用双向力反馈,使操作者能够感受到 follower arm 的接触。按 Bilateral Control guide 完成详细设置和配置。
常见问题
物料
- 关节电机(DAMIAO,24V,CAN,双 14 位磁编码器):肩部 DM‑J8009P‑2EC(额定 20 / 峰值 40 N·m)、上臂与肘 DM4340 系列(9 / 27 N·m,40:1)、腕部 DM‑J4310‑2EC(3 / 7 N·m)
- 两指平行夹爪(WowRobo 页写夹持力 30 N),内置 Arducam B0495 摄像头,手指可替换
- MiSUMi 铝型材立柱;底板 190×250×8 mm,带 48 个 M6 孔(WowRobo);关节有机械限位
- 标准 BOM 视觉:头部 ZED Mini 双目相机与两只腕部相机共用一个 USB 集线器和 5 Gbps 中继线
- USB 转 CAN‑FD 适配器(FAQ 建议用 1.0 BOM 所列型号)、两个 24V 15A 电源、急停按钮(WowRobo 附件清单)
- 遥操作主臂 OpenArm KER:无电机被动臂,16 个 Infineon TLE5012B 15 位绝对磁编码器,连杆按 70% 比例缩放(购买页)
工具
- 自建需外协 CNC 件并打印外壳(LeRobot 文档称所有部件个人或实验室都能采购与制作);多数用户直接买厂商组装好的整机
- Linux 电脑与 CAN‑FD 接口;用螺丝或夹具把底座固定在台面上,配护目镜与急停(安全指南)
技能
- Linux 与 CAN 接口配置(lerobot-setup-can 或 openarm_can 命令行),零位校准
- ROS 2 / MoveIt 2 或 dora-rs 数据流;MIT 模式 PD 增益、重力与摩擦补偿调参(FAQ)
- 模仿学习与策略推理:LeRobot,Isaac Lab、MuJoCo 或 mjlab 仿真
软件
- openarm_can(Apache‑2.0):CAN 电机控制库与命令行
- openarm_ros2(ros2_control 与 MoveIt 2)、openarm_description(URDF/xacro)
- dora-openarm-*:KER、Meta Quest 3 VR 与 WebXR 遥操作,数据采集、推理与评测数据流
- LeRobot(Apache‑2.0):pip install -e ".[damiao]",类型 openarm_follower、openarm_leader 与双臂 bi_openarm_*
- 仿真与数据:openarm_mujoco、openarm_isaac_lab、openarm_mjlab;openarm_dataset 格式可转 LeRobot