SO-101 MuJoCo 遥操作仿真

本项目使用真实 SO-101 Leader 主臂实时控制 MuJoCo 中的 SO-101 机械臂，支持原始夹爪和 PincOpen 平行夹爪，并可自由选择不同任务场景。

控制目标通过 MuJoCo 位置执行器写入，仿真会考虑舵机力矩限制、连杆惯性、接触和摩擦，而不是在运行过程中直接修改关节位置。

功能

• 读取 SO-101 Leader 的六路关节数据。
• 支持原始 SO-101 夹爪和 PincOpen 平行夹爪。
• 支持基础抓取、颜色分类和随机杂乱抓取场景。
• 根据真实时间推进固定步长动力学。
• 自动裁剪关节目标，并对输入进行低通滤波。
• 支持 GUI 和无窗口模式。
• PincOpen 保留四连杆运动、对称开合、碰撞和夹持力限制。
• 杂乱场景支持固定随机种子物体数量。

项目结构

.
├── README.md
├── teleop_to_mujoco.py
└── mujoco_sim/
    ├── robots/
    │   ├── so101_original.xml
    │   └── so101_pincopen.xml
    ├── scenes/
    │   ├── tabletop_blocks.xml
    │   ├── sorting.xml
    │   └── clutter.xml
    ├── objects/
    │   └── common.xml
    └── assets/
        ├── *.stl
        └── pincopen/

• robots/：机械臂、夹爪、关节、执行器、碰撞体和腕部相机。
• scenes/：桌面、任务物体、容器和生成区域。
• objects/common.xml：公共材质、灯光和接触参数。
• assets/：SO-101 与 PincOpen 的可视化网格。

脚本启动时会在 mujoco_sim/ 中短暂生成一个入口 XML，将所选机器人和场景组合起来；模型加载后该文件会立即删除。

环境要求

• Python 3.10 或更高版本
• MuJoCo Python 包
• LeRobot
• 已完成校准的 SO-101 Leader 主臂
• GUI 模式需要可用的桌面环境和 OpenGL

安装 Python 依赖：

python3 -m pip install mujoco lerobot

确认主臂串口：

ls /dev/ttyACM*

脚本使用已有的 LeRobot 校准数据，并以 calibrate=False 连接。首次使用前应先通过 LeRobot 工具完成主臂校准。

快速开始

默认使用 PincOpen 和基础方块场景：

python3 teleop_to_mujoco.py --port=/dev/ttyACM0

使用原始 SO-101 夹爪：

python3 teleop_to_mujoco.py \
  --port=/dev/ttyACM0 \
  --gripper=original

使用 PincOpen 平行夹爪：

python3 teleop_to_mujoco.py \
  --port=/dev/ttyACM0 \
  --gripper=pincopen

如果校准 ID 不是默认值：

python3 teleop_to_mujoco.py \
  --port=/dev/ttyACM0 \
  --leader-id=你的主臂ID

场景

基础抓取

包含红、蓝、绿三个方块，适合测试抓取、搬运和堆叠。

python3 teleop_to_mujoco.py --scene=tabletop_blocks

颜色分类

包含红蓝两类物体和两个目标收纳盒。

python3 teleop_to_mujoco.py --scene=sorting

随机杂乱抓取

包含方块、圆柱、球体、胶囊和椭球等物体。相同种子会生成相同布局。

python3 teleop_to_mujoco.py \
  --scene=clutter \
  --seed=42 \
  --object-count=8

--object-count 的有效范围为 1 至 12。

常用参数

--port           Leader 主臂串口，默认 /dev/ttyACM0
--leader-id      LeRobot 校准 ID
--gripper        original 或 pincopen
--scene          tabletop_blocks、sorting 或 clutter
--seed           clutter 场景随机种子
--object-count   clutter 场景物体数量，1 至 12
--fps            遥操作更新频率，默认 60
--filter-time    输入滤波时间常数，默认 0.03 秒；0 表示关闭
--headless       不打开 MuJoCo 窗口
--model          加载自定义完整 MJCF，并覆盖 gripper 和 scene 选择

查看完整帮助：

python3 teleop_to_mujoco.py --help

夹爪控制

两种夹爪都使用相同的 Leader 输入：

gripper.pos = 0      完全闭合
gripper.pos = 100    完全打开

脚本会自动映射到所选模型的执行器范围：

• 原始夹爪：约 -0.1745 ～ 1.7453 rad
• PincOpen：-0.77 ～ 0 rad

PincOpen 的有效抓取开口约为 5 至 65 mm，指尖碰撞摩擦系数为 1.2，执行器保护力矩限制为 0.8 Nm。

添加新场景

1. 在 mujoco_sim/scenes/ 下新建 XML。
2. 使用 <mujocoinclude> 作为根节点。
3. 复用 objects/common.xml 中的材质和默认类别。
4. 为任务 body、geom、site 和 camera 设置唯一且稳定的名称。
5. 在 teleop_to_mujoco.py 的 SCENE_MODEL_PATHS 中登记场景。

场景文件只应包含环境与任务对象，不要复制机器人模型。

常见问题

找不到 lerobot

确保在运行脚本的 Python 环境中安装 LeRobot：

python3 -m pip show lerobot

无法打开串口

检查串口路径、设备权限，以及是否有其他程序正在占用主臂。

GUI 无法启动

可先用无窗口模式检查硬件与控制：

python3 teleop_to_mujoco.py --headless

遥操作过于抖动或延迟

增大 --filter-time 会更平滑，减小会更跟手：

python3 teleop_to_mujoco.py --filter-time=0.01

资产许可

PincOpen 网格来自 Pollen Robotics 的 PincOpen 项目，采用 CC BY-SA 4.0。详细来源和许可见：

mujoco_sim/assets/pincopen/LICENSE.txt