Skip to main content
Version: 6.1.0 (Latest)

虚拟遥操作MuJoCo

1. 介绍​

本文档介绍如何使用 灵动示教臂真机 对 MuJoCo 中的虚拟操作臂 进行遥操作。该方案适用于以下场景：

  • 在没有实体操作臂时，先完成遥操作流程验证
  • 调试示教臂输入、夹爪映射与控制逻辑
  • 快速开发 MuJoCo 仿真场景、模型和交互逻辑
  • 作为后续接入真实操作臂前的联调环境

遥操作工具包为 Teleoperation-SDK，其中提供两个开箱即用的示例：

Demo功能
01_demo_realtime_joint_plot.py实时关节角度绘图与手柄输入状态显示
02_demo_mujoco_follower.py示教臂到 MuJoCo 虚拟操作臂的遥操作

2. 使用效果​

运行后将同时涉及两个输入输出通道：

  • 输入端：Alicia-D 示教臂真机通过 USB 串口向电脑发送实时关节角度和手柄状态
  • 仿真端：MuJoCo 加载虚拟操作臂模型，并按照示教臂姿态实时更新显示

操作流程如下：

说明
  1. 连接示教臂与电脑，确认系统已经正确识别串口设备，
  2. 启动 MuJoCo 遥操作实例，等待仿真窗口完成加载，
  3. 在仿真窗口中观察虚拟机械臂的初始姿态，确认模型显示正常，
  4. 按住左键启用遥操作；如需固定示教臂真机，可按住右键进行锁定，
  5. 缓慢拖动示教臂，观察虚拟操作臂是否能够同步响应，
  6. 通过扳机控制夹爪开合，检查夹爪映射是否正常。
推荐使用方式

首次联调时，建议先运行 01_demo_realtime_joint_plot.py 确认串口读取和按键状态正常，再启动 02_demo_mujoco_follower.py 进入三维仿真。

3. 环境要求​

项目要求
操作系统Ubuntu 20.04 / 22.04，推荐 Ubuntu
Python3.10 - 3.12，推荐 3.11
硬件Alicia-D 示教臂，USB 串口连接
GPU可选。仅影响 torch 的安装方式
平台说明

虽然 Python 依赖在部分 Windows 环境下也可能安装成功，但针对 MuJoCo 虚拟遥操作的完整链路验证，仍建议使用 Ubuntu 环境，以减少图形界面、串口权限和依赖兼容性问题。

4. 项目结构​

Teleoperation-SDK 主要目录如下：

Teleoperation-SDK/
├── 01_demo_realtime_joint_plot.py
├── 02_demo_mujoco_follower.py
├── assets/
│   └── mujoco/
│       └── Alicia_D_v5_6/
│           └── gripper_50mm/
│               ├── alicia_d_follower.xml
│               ├── base_link.STL
│               ├── link1.STL ~ link6.STL
│               ├── left_gripper_50mm.STL
│               └── right_gripper_50mm.STL
├── teleop_utils/
│   ├── __init__.py
│   └── fps_utils.py
├── pyproject.toml
├── LICENSE
├── .gitignore
└── README.md

其中：

  • 02_demo_mujoco_follower.py 是本文的核心示例
  • assets/mujoco/.../alicia_d_follower.xml 是默认加载的 MuJoCo 模型描述文件
  • teleop_utils/fps_utils.py 提供高精度循环定时能力，用于稳定控制频率

5. 安装配置​

5.1 安装 Conda​

如您尚未安装 Conda，请先参考官方安装说明：

安装完成后，请重新打开终端，确认以下命令可正常使用：

conda --version

5.2 获取代码并创建环境​

git clone https://github.com/Synria-Robotics/Teleoperation-SDK.git
cd Teleoperation-SDK

conda create -n teleop python=3.11 -y
conda activate teleop

5.3 安装方式​

方法一：源码安装​

适用于需要修改源码、查看实现细节或参与二次开发的场景。

pip install -e .

方法二：PyPI 安装​

适用于直接使用 SDK 的场景。

pip install teleoperation-sdk
如何选择
  • 需要调试、改代码、替换模型或扩展遥操作逻辑时，建议使用 pip install -e .
  • 仅运行官方示例时，可使用 PyPI 安装

5.4 依赖验证​

安装完成后，建议执行以下命令检查关键依赖是否齐全：

python -c "
import torch, numpy, matplotlib, mujoco, alicia_d_sdk, serial
print('torch         ', torch.__version__)
print('numpy         ', numpy.__version__)
print('matplotlib    ', matplotlib.__version__)
print('mujoco        ', mujoco.__version__)
print('alicia_d_sdk  OK')
print('pyserial      OK')
print()
print('All dependencies installed successfully!')
"

如果上述输出全部正常且无报错，说明运行环境已经具备。

5.5 串口权限配置​

首次在 Linux 上使用时，请先为当前用户添加串口访问权限：

sudo usermod -aG dialout $USER

执行后请 注销并重新登录，否则权限不会立即生效。

若未完成此步骤，运行时可能出现以下报错：

Permission denied: '/dev/ttyACM0'

6. 快速开始​

6.1 运行前检查​

启动前请确认：

  1. 已激活正确的 Conda 环境
  2. 示教臂已通过 USB 连接到电脑
  3. 当前终端对串口具有访问权限
  4. MuJoCo 图形界面可以正常打开

6.2 先检查示教臂输入是否正常​

建议先运行实时监控脚本：

python 01_demo_realtime_joint_plot.py

运行后将弹出 matplotlib 窗口，显示：

  • 6 个关节的实时角度曲线
  • 手柄输入状态
  • 当前采样更新情况

如果该示例无法正常读取姿态或按键状态，请先解决串口、权限或依赖问题，再进行 MuJoCo 遥操作。

实例01界面

实例01界面

6.3 启动 MuJoCo 虚拟遥操作​

python 02_demo_mujoco_follower.py

正常情况下，将弹出 MuJoCo 三维窗口，并加载内置虚拟操作臂模型。此时示教臂的动作会被持续读取，但只有在满足交互条件时才会驱动虚拟机械臂执行遥操作。

实例02界面

实例02界面

7. 交互说明​

7.1 基本操作​

操作效果
左键启用/切断遥操作
邮件锁住示教臂真机
扳机控制夹爪开合幅度
按 R重新加载 MuJoCo XML 模型
关闭窗口退出程序

7.2 推荐操作习惯​

  • 启动程序后，先确认窗口正常显示，再开始移动示教臂
  • 启用遥操作前，先让示教臂处于较自然、较安全的姿态
  • 首次使用时，建议缓慢移动各关节，确认映射方向与幅度正常
  • 修改 XML 或 mesh 后，优先使用 R 重载进行验证

8. 常见问题​

8.1 启动时报依赖错误​

报错信息原因解决方法
ImportError: torch_utils 需要 PyTorch未安装 torch在仓库目录执行 pip install . 或 pip install -e .
ModuleNotFoundError: No module named 'torch'未安装 torch同上
ModuleNotFoundError: No module named 'mujoco'未安装 MuJoCo Python 包重新执行安装步骤
ModuleNotFoundError: No module named 'alicia_d_sdk'SDK 未安装重新执行安装步骤
Permission denied: '/dev/ttyACM0'串口权限不足参考上文串口权限配置
device disconnected or multiple access on port设备未连接或串口被占用检查 USB 连接并关闭其他占用程序

8.2 不连接机械臂能否运行 MuJoCo Demo​

可以启动程序，也通常能打开 MuJoCo 窗口，但由于没有可用的示教臂输入，终端会持续打印串口相关错误，且无法控制虚拟机械臂。

如果您的目标只是检查 XML 场景渲染是否正常，这种方式仍可用于静态验证。

8.3 --variant 支持哪些选项​

支持以下选项：

  • leader
  • gripper_50mm
  • gripper_100mm
  • leader_ur
  • vertical_50mm

当您切换硬件形态或夹爪规格时，请确保参数设置与实际设备一致。

8.4 为什么建议先运行 Demo 01​

因为 Demo 01 更容易定位问题来源：

  • 如果 Demo 01 无法读取关节角度，通常是串口、权限或 SDK 安装问题
  • 如果 Demo 01 正常，但 Demo 02 异常，问题通常集中在 MuJoCo 环境、模型文件或图形界面

这能显著缩短排障时间。

9. 依赖关系说明​

Teleoperation-SDK
├── numpy
├── matplotlib
├── mujoco >= 3.0
├── pyserial
└── alicia_d_sdk
	└── synria-robocore
		└── torch

其中：

  • numpy 用于数值计算
  • matplotlib 用于实时曲线显示
  • mujoco 用于三维仿真与模型加载
  • pyserial 用于串口通信
  • alicia_d_sdk 用于读取示教臂状态并接入遥操作逻辑
  • torch 由下游依赖间接引入，因此某些场景下即使未直接使用深度学习功能，也仍需正确安装

10. 推荐调试流程​

如果您是首次接触该工具链，建议按以下顺序完成调试：

  1. 安装 Conda 与 Python 环境
  2. 通过 pip install -e . 安装 Teleoperation-SDK
  3. 执行依赖验证命令
  4. 连接示教臂，确认串口号正确
  5. 运行 01_demo_realtime_joint_plot.py 检查关节与按键状态
  6. 运行 02_demo_mujoco_follower.py 打开 MuJoCo 仿真
  7. 按住左键并缓慢拖动示教臂，确认映射关系正常
  8. 修改 XML 并使用 R 验证场景重载

11. 相关文档​

通过以上文档，您可以进一步完成示教臂基础使用、SDK 开发以及第三方机械臂遥操作扩展。