宇树 G1-D + Pico 4 XR 遥操作环境搭建

宇树 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 设备后，通过手势或控制器直接驱动机器人双臂和灵巧手，并支持数据采集。

支持的硬件组合：

二、系统架构

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 基础工具

sudoaptupdatesudoaptinstall-yandroid-tools-adb android-tools-fastboot opensslgit

3.2 创建 conda 环境

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

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

gitclone https://github.com/unitreerobotics/xr_teleoperate.gitcdxr_teleoperate# 必须加 --recursive，dex-retargeting 本身还有嵌套子模块gitsubmodule update--init--recursive--depth1

3.4 安装依赖

pipinstall-rrequirements.txt pipinstall-eteleop/televuer pipinstall-eteleop/robot_control/dex-retargeting pipinstall-eteleop/teleimager

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

# 强制锁回 numpy，防止 vuer 把它升到 2.xpipinstall"numpy==1.26.4""vuer[all]==0.0.60"# 回退 params-proto，防止 televuer 导入失败pipinstall"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 版本锁定总结

五、证书配置：Pico vs AVP

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

Pico（自签名证书，够用）

cdteleop/televuer openssl req-x509-nodes-days365-newkeyrsa:2048\-keyoutkey.pem-outcert.pem

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

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

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

# 1. 生成 root CAopenssl genrsa-outrootCA.key2048openssl req-x509-new-nodes-keyrootCA.key-sha256-days1024-outrootCA.pem# 2. 生成服务器证书openssl req-new-newkeyrsa:2048-nodes-keyoutkey.pem-outserver.csr# 配置 server_ext.cnf（需要添加 SAN 扩展）openssl x509-req-inserver.csr-CArootCA.pem-CAkeyrootCA.key\-CAcreateserial-outcert.pem-days365-extfileserver_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 封装的关键参数

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 tvcdxr_teleoperate# 设置 DDS 配置exportCYCLONEDDS_URI=file://$(pwd)/xr_teleop/cyclonedds_pc.xml# 启动遥操作python teleop/teleop_hand_and_arm.py\--armg1\--eedex3\--input-mode hand\--display-mode immersive\--network-interface eth0\--img-server-ip192.168.123.164