前言
本文介绍基于宇树 G1 人形机器人的 VR 遥操作开发与数据训练流程。涉及开源库 avp_teleoperate 及其升级版 xr_teleoperate，以及 unitree_IL_lerobot 的集成使用。
第一部分 基于宇树开源的 avp(xr 以前的版本) 摇操程序
1.1 Ubuntu、双臂 inverse kinematics 环境配置、unitree_dds_wrapper 配置
- Ubuntu 20.04 和 Ubuntu 22.04 操作系统下进行测试
注意，原 h1_2 分支中的临时版本 unitree_dds_wrapper 已更新为 Python 版控制通信库 unitree_sdk2_python。
# 安装 unitree_sdk2_python 库
git clone https://github.com/unitreerobotics/unitree_sdk2_python.git
cd unitree_sdk2_python
pip install -e .
双臂 inverse kinematics 环境配置 该部分用于配置人形机器人 H1 双臂（共 14 个自由度）的末端位姿逆运动学求解相关的软件库。Apple Vision Pro 获取左右两个手腕位姿后，使用 pinocchio 和 CasADi 库加载 URDF 并进行逆运动学计算。
conda create -n tv python=3.8
conda activate tv
# 确保 pinocchio 版本为 3.1.0
conda install pinocchio -c conda-forge
pip install meshcat
pip install casadi
*注意：使用 pip 安装的 pinocchio 有可能不是最新版本 3.1.0，本环境需要使用 3.1.0 版本。必须先安装 pinocchio 并确保安装成功，然后再进行 TeleVision 的环境配置。
1.2 TeleVision 环境配置和 Apple Vision Pro 通信配置
1.2.1 基本环境配置和 Isaac Gym 安装
cd ~
git clone https://github.com/unitreerobotics/avp_teleoperate.git
cd avp_teleoperate
pip install -r requirements.txt
之后，在 Isaac Gym 下载页面下载 Isaac Gym 安装包并解压，然后到 IsaacGym_Preview_4_Package/isaacgym/python 目录下执行下面命令：
pip install -e .
1.2.2 证书生成相关配置
由于苹果不允许在非 HTTPS 连接上使用 WebXR。要在本地测试应用程序，需要创建一个自签名证书并在客户端上安装它。
首先，安装 mkcert
brew install mkcert
eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"
sudo apt-get install build-essential procps curl file git
cd ~
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"' >> $HOME/.bash_profile
接下来，生成证书
mkcert -CAROOT
系统防火墙设置
sudo ufw allow 8012
假设本机 IP 地址是 192.168.123.2，创建证书：
mkcert -install && mkcert -cert-file cert.pem -key-file key.pem 192.168.123.2 localhost 127.0.0.1
把生成的 cert.pem 和 key.pem 两个文件拷贝到项目的 teleop 目录下：
cp cert.pem key.pem ~/avp_teleoperate/teleop/
查看本机 IP 地址：
tv) unitree@Host:~/avp_teleoperate$ ifconfig | grep inet
1.2.3 启用 Apple Vision Pro 的 WebXR 相关功能、进入 VR
设置 >> Apps >> Safari 浏览器 >> 高级 >> 功能标志 >> 启用 WebXR 相关功能。
在新版本 Vision OS 2 系统中，将证书通过 AirDrop 复制到 Apple Vision Pro 设备后，将会在设置 APP 中左上角账户栏的下方出现证书相关信息栏，点击进去即可启用对该证书的信任。
接下来，便可以进入 VR：
cd ~/avp_teleoperate/teleop
python teleop_hand.py
打开 Apple Vision Pro 的浏览器输入 https://192.168.123.2:8012?ws=wss://192.168.123.2:8012，点击 "Enter VR" 并且允许跟踪。
1.3 硬件清单
1.3.1 VR 和头部的双目相机
| 物品名称 | 数量 | 说明 |
|---|---|---|
| Apple Vision Pro | 1 | 参考 Apple 官方网址 |
| 计算机 | 1 | x86_64 架构 |
| 人形机器人 H1 | 1 | 具体型号为 H1_2 |
| 灵巧手 | 1 | H1 可搭载 Inspire Robotics (RH56DFX) 的仿人五指灵巧手 |
| 头部双目相机 | 1 | 普通 USB 免驱动双目相机 |
| 头部相机支架 | 1 | 参考 GitHub 仓库 hardware 目录 |
1.3.2 手腕上的深度相机 D405
| 物品名称 | 数量 | 说明 |
|---|---|---|
| 英特尔 RealSense D405 相机 | 2 | 深度相机 |
| 腕部相机环形支架 | 2 | 参考 GitHub 仓库 hardware 目录 |
| 左腕相机支架 | 1 | 参考 GitHub 仓库 hardware 目录 |
| 右腕相机支架 | 1 | 参考 GitHub 仓库 hardware 目录 |
1.4 启动程序
1.4.1 开启灵巧手服务
可以参考《RH56DFX 灵巧手开发》配置相关环境和编译控制程序。
- 下载灵巧手控制接口程序，并将之拷贝到 机器人 Unitree H1_2 的 PC2 中。
- 在 PC2 中解压完成后，使用下述命令进行编译：
unitree@PC2:~$ sudo apt install libboost-all-dev libspdlog-dev
cd h1_inspire_service & mkdir build & cd build
unitree@PC2:~/h1_inspire_service/build$ cmake .. -DCMAKE_BUILD_TYPE=Release
unitree@PC2:~/h1_inspire_service/build$ make
# 终端 1. 运行 h1 inspire 手部服务
unitree@PC2:~/h1_inspire_service/build$ sudo ./inspire_hand -s /dev/ttyUSB0
# 终端 2. 运行示例
unitree@PC2:~/h1_inspire_service/build$ ./h1_hand_example
1.4.2 开启图像推流服务 image_server
把 avp_teleoperate/teleop/image_server 目录中的 image_server.py 拷贝到机器人 Unitree G1/H1/H1_2 的开发计算单元 PC2 中，并在 PC2 内执行下面命令：
# 提醒：目前该图像传输程序支持 OpenCV 和 Realsense SDK 两种读取图像的方式
unitree@PC2:~/image_server$ python image_server.py
注意：这里需要检查 OpenCV 读取图像时的参数是否与双目相机硬件匹配，以及对于推流使用的默认 5555 端口是否可用。
1.4.3 启动遥操作程序
在需要使用 SDK 进行开发调试时，请确保 G1 已经进入调试模式（阻尼：①长按 L2 + 单击 B，或零力矩：长按 L2 + 单击 Y 模式下，遥控器长按 L2 + 单击 R2 进入调试模式），以停止运动控制程序发送指令。
操作员 B 修改 ~/avp_teleoperate/teleop/teleop_hand_and_arm.py 中 img_config 图像客户端配置。程序如果正常启动，终端最后一行将停留在 'Please enter the start signal (enter 'r' to start the subsequent program):' 的字符串输出。
操作员 A 戴上 Apple Vision Pro 设备。在 Apple Vision Pro 上打开 Safari，访问：https://192.168.123.2:8012?/ws=wss://192.168.123.2:8012。点击 Enter VR 并选择 Allow 以启动 VR 会话。
操作员 B 可以在终端中按下 r 键以启动远程操作程序。
根据你的机器人配置选择不同的启动参数。以下是一些启动命令示例：
# 1. G1(29DoF) 机器人 + Dex3-1 灵巧手
tv) unitree@Host:~/avp_teleoperate/teleop$ python teleop_hand_and_arm.py --arm=G1_29 --hand=dex3
# 2. 仅 G1(29DoF) 机器人
tv) unitree@Host:~/avp_teleoperate/teleop$ python teleop_hand_and_arm.py
# 3. G1 (23DoF) 机器人
tv) unitree@Host:~/avp_teleoperate/teleop$ python teleop_hand_and_arm.py --arm=G1_23
# 4. H1_2 机器人 + 一代 Inspire 灵巧手
tv) unitree@Host:~/avp_teleoperate/teleop$ python teleop_hand_and_arm.py --arm=H1_2 --hand=inspire1
# 5. H1 机器人
tv) unitree@Host:~/avp_teleoperate/teleop$ python teleop_hand_and_arm.py --arm=H1
# 6. 如果您想开启数据可视化 + 录制，还可以追加 --record 选项
tv) unitree@Host:~/avp_teleoperate/teleop$ python teleop_hand_and_arm.py --arm=G1_23 --record
1.5 avp_teleoperate 与 OpenTeleVision 的差异对比
1.5.1 核心架构的差异对比
| avp_teleoperate | OpenTeleVision | |
|---|---|---|
| 项目定位与目标 | 由 Unitree Robotics 开发，专注于使用 Apple Vision Pro 控制 Unitree 系列机器人 | 学术研究项目，有 CoRL 2024 论文支持，更通用的远程操作框架 |
| 核心架构差异 | 分层设计——明确分为三大模块：image_server, open_television, robot_control | 功能模块化：act(模仿学习) 和 teleop(远程操作) 两大功能模块 |
| 技术实现差异 | 图像处理使用专门的 image_server、image_client 架构；支持多相机同步 | 通用 VR 交互，使用 WebRTC 实现跨设备通信 |
1.5.2 代码结构上的差异对比
avp_teleoperate 的代码结构:
avp_teleoperate/
├── LICENSE
├── README.md
├── requirements.txt
├── assets/
├── hardware/
├── img/
└── teleop/
├── teleop_hand_and_arm.py
├── image_server/
├── open_television/
├── robot_control/
└── utils/
第二部分 xr_teleoperate：avp_teleoperate 的升级版
2.1 安装
xr 整个系统的示意图和原来 avp 的差不太多。系统依然是 Ubuntu 20.04 或 Ubuntu 22.04。
2.1.1 基础环境
# 创建 conda 基础环境
conda create -n tv python=3.10 pinocchio=3.1.0 numpy=1.26.4 -c conda-forge
conda activate tv
# 克隆本仓库
git clone https://github.com/unitreerobotics/xr_teleoperate.git
cd xr_teleoperate
# 浅克隆子模块
git submodule update --init --depth 1
# 安装 televuer 模块
cd teleop/televuer
pip install -e .
# 生成 televuer 模块所需的证书文件
openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout key.pem -out cert.pem
# 安装 dex-retargeting 模块
cd ../robot_control/dex-retargeting/
pip install -e .
cd ../../../
pip install -r requirements.txt
2.1.2 unitree_sdk2_python
# 安装 unitree_sdk2_python 库
git clone https://github.com/unitreerobotics/unitree_sdk2_python.git
cd unitree_sdk2_python
pip install -e .
注意：在 xr_teleoperate >= v1.1 版本中，unitree_sdk2_python 仓库的 commit 必须是等于或高于特定版本。
2.2 仿真部署
2.2.1 环境配置
首先，请安装 unitree_sim_isaaclab。其次，启动 unitree_sim_isaaclab 仿真环境。
conda activate unitree_sim_env
cd ~/unitree_sim_isaaclab
python sim_main.py --device cpu --enable_cameras --task Isaac-PickPlace-Cylinder-G129-Dex3-Joint --enable_dex3_dds --robot_type g129
2.2.2 启动遥操
以下是本程序的启动参数说明：
| ⚙️ 参数 | 📜 说明 |
|---|---|
--record | 【启用数据录制模式】按 r 键进入遥操后，按 s 键可开启数据录制 |
--motion | 【启用运动控制模式】开启本模式后，可在机器人运控程序运行下进行遥操作程序 |
--headless | 【启用无图形界面模式】适用于本程序部署在开发计算单元等无显示器情况 |
--sim | 【启用仿真模式】 |
基础控制参数：
| ⚙️ 参数 | 📜 说明 | 🔘 目前可选值 |
|---|---|---|
--xr-mode | 选择 XR 输入模式 | hand（手势跟踪）, controller（手柄跟踪） |
--arm | 选择机器人设备类型 | G1_29, G1_23, H1_2, H1 |
--ee | 选择手臂的末端执行器设备类型 | dex1, dex3, inspire1, brainco |
启动命令示例：
cd ~/xr_teleoperate/teleop/
python teleop_hand_and_arm.py --xr-mode=hand --arm=G1_29 --ee=dex3 --sim --record
程序正常启动后，戴上您的 XR 头显设备，连接对应的 WiFi 热点。在终端中按下 r 键后，正式开启遥操作程序。
2.3 真机部署
2.3.1 图像服务
将 xr_teleoperate/teleop/image_server 目录中的 image_server.py 复制到宇树机器人（G1/H1/H1_2 等）的开发计算单元 PC2。
scp ~/xr_teleoperate/teleop/image_server/image_server.py [email protected]:~/image_server/
并在 PC2 上执行以下命令：
unitree@PC2:~/image_server$ python image_server.py
2.3.2 BrainCo 手部服务
请参考官方文档。安装完毕后，请手动启动两个巧手的服务，命令示例如下：
# Terminal 1.
sudo ./brainco_hand --id 126 --serial /dev/ttyUSB1
# Terminal 2.
sudo ./brainco_hand --id 127 --serial /dev/ttyUSB2
2.3.3 启动遥操
- 在没有开启运动控制模式（--motion）时，请务必确保机器人已经进入调试模式（L2+R2）。
- 如果要开启运动控制模式遥操作，请提前使用 R3 遥控确保机器人进入主运控模式。
- 开启运动控制模式（--motion）时：右手柄按钮 A 为遥操作退出功能按钮；左手柄和右手柄的两个摇杆按键同时按下为软急停按键。
第三部分 unitree_IL_lerobot 的安装与运行
3.1 环境安装与数据采集、转换
3.1.1 环境安装：LeRobot 环境安装、unitree_sdk2_python
git clone https://github.com/unitreerobotics/unitree_sdk2_python.git
cd unitree_sdk2_python && pip install -e .
# 下载源码
git clone --recurse-submodules https://github.com/unitreerobotics/unitree_IL_lerobot.git
git submodule update --init --recursive
# 创建 conda 环境
conda create -y -n unitree_lerobot python=3.10
conda activate unitree_lerobot
# 安装 LeRobot
cd lerobot && pip install -e .
cd .. && pip install -e .
3.1.2 数据采集
可以通过 avp/xr 现采，或者从 huggingface 上加载数据集。
from lerobot.common.datasets.lerobot_dataset import LeRobotDataset
import tqdm
episode_index = 1
dataset = LeRobotDataset(repo_id="unitreerobotics/G1_ToastedBread_Dataset")
from_idx = dataset.episode_data_index["from"][episode_index].item()
to_idx = dataset.episode_data_index["to"][episode_index].item()
for step_idx in tqdm.tqdm(range(from_idx, to_idx)):
step = dataset[step_idx]
可视化：
cd unitree_lerobot/lerobot
python lerobot/scripts/visualize_dataset.py \
--repo-id unitreerobotics/G1_ToastedBread_Dataset \
--episode-index 0
3.1.3 针对 avp/xr 现采数据的 数据转换：json 格式转换到 lerobot 格式
转换 json 格式到 lerobot 格式——通过 convert_unitree_json_to_lerobot 函数：
python unitree_lerobot/utils/convert_unitree_json_to_lerobot.py \
--raw-dir $HOME/datasets/g1_grabcube_double_hand \
--repo-id your_name/g1_grabcube_double_hand \
--robot_type Unitree_G1_Dex3 \
--push_to_hub true
排序和重命名：
python unitree_lerobot/utils/sort_and_rename_folders.py \
--data_dir $HOME/datasets/g1_grabcube_double_hand
3.2 训练与测试
3.2.1 训练
训练 pi0：
cd unitree_lerobot/lerobot
python lerobot/scripts/train.py \
--dataset.repo_id=unitreerobotics/G1_ToastedBread_Dataset \
--policy.type=pi0
训练 diffusion policy：
python lerobot/scripts/train.py \
--dataset.repo_id=unitreerobotics/G1_ToastedBread_Dataset \
--policy.type=diffusion
训练 ACT：
python lerobot/scripts/train.py \
--dataset.repo_id=unitreerobotics/G1_ToastedBread_Dataset \
--policy.type=act
3.2.2 真机测试
在打开 image_server 之后，然后执行以下程序：
# --policy.path 训练保存模型路径
# --repo_id 训练加载的数据集
python unitree_lerobot/eval_robot/eval_g1/eval_g1.py \
--policy.path=unitree_lerobot/lerobot/outputs/train/2025-03-25/22-11-16_diffusion/checkpoints/100000/pretrained_model \
--repo_id=unitreerobotics/G1_ToastedBread_Dataset
如果你想验证模型在数据集上的表现，使用下面去测试：
python unitree_lerobot/eval_robot/eval_g1/eval_g1_dataset.py \
--policy.path=unitree_lerobot/lerobot/outputs/train/2025-03-25/22-11-16_diffusion/checkpoints/100000/pretrained_model \
--repo_id=unitreerobotics/G1_ToastedBread_Dataset
