宇树 G1-D + Pico 4 XR 遥操作环境搭建：xr_teleoperate 项目解析与踩坑总结

官方项目地址：https://github.com/unitreerobotics/xr_teleoperate
适用平台：Ubuntu 20.04 / 22.04
适用场景：G1-D + Dex3-1 + Pico 4 遥操作部署

---

目录

1. 项目是做什么的
2. 系统架构
3. 环境安装
4. 关键踩坑：依赖版本冲突
5. 证书配置：Pico vs AVP
6. 图形化启动器 xr_teleop
7. 真机启动 SOP
8. 关键参数说明
9. 总结

---

一、项目是做什么的

xr_teleoperate 是宇树官方开源的遥操作系统，目标是让操作者戴上 XR 设备后，通过手势或控制器直接驱动机器人双臂和灵巧手，并支持数据采集。

支持的硬件组合：

机器人	末端执行器	XR 设备
G1、H1、H1_2	Dex3-1、Dex1、Inspire、BrainCo	Pico 4、Quest、Apple Vision Pro

---

二、系统架构

2.1 数据流

XR 设备输入（头部/手腕/手指姿态）
        ↓
  TeleVuerWrapper（OpenXR坐标系 → 机器人坐标系）
        ↓
  Arm IK（双臂逆运动学求解）
  Hand Retargeting（人手25关键点 → 机械手关节角）
        ↓
  unitree_sdk2_python（DDS下发控制命令）
        ↓
  机器人双臂 + 灵巧手执行

机器人相机图像
  TeleImager（图像服务端）→ ImageClient（上位机拉流）→ XR端显示

2.2 四层架构

XR 输入层：   televuer        接收头显/手势/控制器数据，坐标系转换
图像传输层：  teleimager       相机图像采集、ZMQ/WebRTC发布
运动映射层：  IK + dex-retargeting  双臂IK求解，手部关节映射
机器人控制层：unitree_sdk2_python  DDS通信，下发关节控制命令

2.3 项目结构

xr_teleoperate/
├── teleop/
│   ├── teleop_hand_and_arm.py   ← 真正的主入口
│   ├── robot_control/           双臂控制、IK、灵巧手控制
│   ├── teleimager/              图像服务与客户端
│   ├── televuer/                XR交互封装
│   └── utils/                   录制、滤波等工具
├── xr_teleop/
│   ├── xr_teleop_gui.py         PyQt图形化启动器（封装主入口参数）
│   └── cyclonedds_pc.xml        DDS配置文件
└── assets/                      URDF / retargeting配置

注意：xr_teleop_gui.py 不是主程序，它只是把参数做成可点选的界面，本质上是拼接命令后去启动 teleop_hand_and_arm.py。

2.4 televuer 的核心作用

XR 设备输出的是 OpenXR 坐标系下的原始数据，机器人 IK 和 URDF 使用的是另一套约定，TeleVuerWrapper 负责这层"姿态翻译"，这是整个遥操作链路的关键。

2.5 dex-retargeting 的核心作用

人手25个关键点无法直接等于机械手关节角，必须经过 retargeting。项目通过 RetargetingConfig 和对应的 YAML/URDF 配置，把 XR 手部姿态映射到 Dex3-1、Inspire、BrainCo 等不同手型的关节定义。这也是为什么安装时必须把 dex-retargeting 单独 pip install -e。

---

三、环境安装

3.1 基础工具

sudo apt update
sudo apt install -y android-tools-adb android-tools-fastboot openssl git

3.2 创建 conda 环境

# 必须在创建时就锁定 numpy=1.26.4 和 pinocchio=3.1.0，后装会有冲突
conda create -n tv python=3.10 pinocchio=3.1.0 numpy=1.26.4 pip -c conda-forge -y
conda activate tv

3.3 克隆仓库并初始化子模块

git clone https://github.com/unitreerobotics/xr_teleoperate.git
cd xr_teleoperate
# 必须加 --recursive，dex-retargeting 本身还有嵌套子模块
git submodule update --init --recursive --depth 1

3.4 安装依赖

pip install -r requirements.txt
pip install -e teleop/televuer
pip install -e teleop/robot_control/dex-retargeting
pip install -e teleop/teleimager

3.5 修复版本冲突（关键步骤）

# 强制锁回 numpy，防止 vuer 把它升到 2.x
pip install "numpy==1.26.4" "vuer[all]==0.0.60"
# 回退 params-proto，防止 televuer 导入失败
pip install "params-proto==2.13.0"

3.6 验证安装

python -c "
from televuer import TeleVuerWrapper
from dex_retargeting.retargeting_config import RetargetingConfig
from teleimager.image_client import ImageClient
print('All imports OK')
"

先验证 import，再跑 GUI。如果这三项有任何一项失败，直接点 GUI 只会把问题藏起来，无法定位。

---

四、关键踩坑：依赖版本冲突

4.1 numpy 版本问题

dex-retargeting、teleimager、rerun-sdk、matplotlib 等依赖链都要求 numpy < 2.0.0，但 vuer[all]==0.0.60 会自动把 numpy 升到 2.x，导致整条链一起崩。

症状：import dex_retargeting 报错，提示 numpy 版本不兼容
解决：创建环境时就锁定 numpy=1.26.4，安装 vuer 后再次强制锁回

4.2 params-proto 版本问题

vuer==0.0.60 内部使用 from params_proto import Flag，但 params-proto >= 3.x 已经移除了 Flag，导致 from vuer import Vuer 直接报错。

症状：from televuer import TeleVuerWrapper 报 ImportError
     ImportError: cannot import name 'Flag' from 'params_proto'
解决：pip install "params-proto==2.13.0"

4.3 版本锁定总结

包	要求版本	原因
numpy	==1.26.4	多个依赖不支持 numpy 2.x
vuer	==0.0.60	与 televuer 配套
params-proto	==2.13.0	3.x 移除了 Flag
pinocchio	==3.1.0	IK 求解器版本要求

---

五、证书配置：Pico vs AVP

这是官方文档里最容易让人误解的地方：Pico 和 Apple Vision Pro 的证书流程完全不同，不要混着抄。

Pico（自签名证书，够用）

cd teleop/televuer
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
    -keyout key.pem -out cert.pem

一条命令搞定，Pico 浏览器接受自签名证书。

Apple Vision Pro（需要完整 root CA 流程）

AVP 的 Safari 不接受自签名证书，需要：

# 1. 生成 root CA
openssl genrsa -out rootCA.key 2048
openssl req -x509 -new -nodes -key rootCA.key -sha256 -days 1024 -out rootCA.pem

# 2. 生成服务器证书
openssl req -new -newkey rsa:2048 -nodes -keyout key.pem -out server.csr
# 配置 server_ext.cnf（需要添加 SAN 扩展）
openssl x509 -req -in server.csr -CA rootCA.pem -CAkey rootCA.key \
    -CAcreateserial -out cert.pem -days 365 -extfile server_ext.cnf

# 3. 将 rootCA.pem 安装到 AVP 系统信任链

结论：用 Pico 的话，直接用一条 openssl 命令，不需要 root CA 那套完整流程。

---

六、图形化启动器 xr_teleop

6.1 工作原理

PyQt6 参数面板
    ↓ 用户选择参数
拼接 teleop_hand_and_arm.py 启动命令
注入 CYCLONEDDS_URI 环境变量
    ↓
PTY 启动进程
通过发送 r、q 等按键控制运行状态

GUI 和命令行是同一套底层逻辑的两种入口，参数完全一致。

6.2 GUI 封装的关键参数

参数	说明
--arm	机器人型号（g1、h1 等）
--ee	末端执行器类型（dex3、inspire 等）
--input-mode	hand（手势）/ controller（手柄）
--display-mode	immersive / pass-through / ego
--network-interface	DDS 网卡名（必须正确）
--img-server-ip	图像服务端 IP
CYCLONEDDS_URI	DDS 配置文件路径

6.3 使用建议

长期在实验室使用时建议保留 GUI，主要好处是降低现场误操作概率，减少 DDS 网卡、脚本路径、Python 环境路径输错的情况。

---

七、真机启动 SOP

1. 确认机器人网络通畅，DDS 网卡配置正确

2. PC端启动遥操作程序
   python teleop/teleop_hand_and_arm.py \
       --arm g1 \
       --ee dex3 \
       --input-mode hand \
       --display-mode immersive \
       --network-interface eth0 \
       --img-server-ip 192.168.123.164

3. Pico 浏览器打开：
   https://<PC_IP>:8012/?ws=wss://<PC_IP>:8012
   （首次需要接受自签名证书警告）

4. XR 页面中点击 "virtual reality"

5. 等待 XR 手臂与机器人手臂完成映射

6. PC 端点击开始遥操，机器人进入跟随

7. 结束时先做安全收尾动作，再退出程序

---

八、关键参数说明

–network-interface

决定 DDS 走哪张网卡。机器人局域网通常是 192.168.123.X，如果 PC 有多张网卡，填错这个参数机器人侧收不到任何控制指令。

–input-mode

• hand：使用手势跟踪（需要 XR 设备支持手部追踪）
• controller：使用手柄跟踪

–display-mode

• immersive：机器人第一视角沉浸显示，链路最直观，调试首选
• pass-through：XR 透传，不显示机器人图像
• ego：中央小窗显示机器人视角，周围保留现实视野

–img-server-ip

图像服务端所在主机的 IP，通常是机器人本体或外接计算单元的地址，必须与实际服务地址一致。

---

九、总结

9.1 项目本质

xr_teleoperate 不是一个简单的 demo，而是一个完整的遥操作系统原型：XR输入 + 视频回传 + 双臂IK + 灵巧手 retargeting + DDS控制 + 数据录制，每一层都有对应的模块。

9.2 部署核心要点

1. conda 环境创建时就锁定 numpy=1.26.4，不要后装
2. 安装 vuer 后立刻锁回 numpy 和 params-proto
3. Pico 用一条 openssl 命令，不要套 AVP 的 root CA 流程
4. 先验证三个核心 import，再跑 GUI
5. --network-interface 填错机器人侧收不到任何指令

9.3 启动命令

conda activate tv
cd xr_teleoperate

# 设置 DDS 配置
export CYCLONEDDS_URI=file://$(pwd)/xr_teleop/cyclonedds_pc.xml

# 启动遥操作
python teleop/teleop_hand_and_arm.py \
    --arm g1 \
    --ee dex3 \
    --input-mode hand \
    --display-mode immersive \
    --network-interface eth0 \
    --img-server-ip 192.168.123.164