宇树 G1-D Pico 4 XR 遥操作环境搭建xr_teleoperate 项目解析与踩坑总结官方项目地址https://github.com/unitreerobotics/xr_teleoperate适用平台Ubuntu 20.04 / 22.04适用场景G1-D Dex3-1 Pico 4 遥操作部署目录项目是做什么的系统架构环境安装关键踩坑依赖版本冲突证书配置Pico vs AVP图形化启动器 xr_teleop真机启动 SOP关键参数说明总结一、项目是做什么的xr_teleoperate是宇树官方开源的遥操作系统目标是让操作者戴上 XR 设备后通过手势或控制器直接驱动机器人双臂和灵巧手并支持数据采集。支持的硬件组合机器人末端执行器XR 设备G1、H1、H1_2Dex3-1、Dex1、Inspire、BrainCoPico 4、Quest、Apple Vision Pro二、系统架构2.1 数据流XR 设备输入头部/手腕/手指姿态 ↓ TeleVuerWrapperOpenXR坐标系 → 机器人坐标系 ↓ Arm IK双臂逆运动学求解 Hand Retargeting人手25关键点 → 机械手关节角 ↓ unitree_sdk2_pythonDDS下发控制命令 ↓ 机器人双臂 灵巧手执行 机器人相机图像 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 opensslgit3.2 创建 conda 环境# 必须在创建时就锁定 numpy1.26.4 和 pinocchio3.1.0后装会有冲突conda create-ntvpython3.10pinocchio3.1.0numpy1.26.4 pip-cconda-forge-yconda activate tv3.3 克隆仓库并初始化子模块gitclone https://github.com/unitreerobotics/xr_teleoperate.gitcdxr_teleoperate# 必须加 --recursivedex-retargeting 本身还有嵌套子模块gitsubmodule update--init--recursive--depth13.4 安装依赖pipinstall-rrequirements.txt pipinstall-eteleop/televuer pipinstall-eteleop/robot_control/dex-retargeting pipinstall-eteleop/teleimager3.5 修复版本冲突关键步骤# 强制锁回 numpy防止 vuer 把它升到 2.xpipinstallnumpy1.26.4vuer[all]0.0.60# 回退 params-proto防止 televuer 导入失败pipinstallparams-proto2.13.03.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 版本不兼容 解决创建环境时就锁定 numpy1.26.4安装 vuer 后再次强制锁回4.2 params-proto 版本问题vuer0.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-proto2.13.04.3 版本锁定总结包要求版本原因numpy1.26.4多个依赖不支持 numpy 2.xvuer0.0.60与 televuer 配套params-proto2.13.03.x 移除了 Flagpinocchio3.1.0IK 求解器版本要求五、证书配置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_teleop6.1 工作原理PyQt6 参数面板 ↓ 用户选择参数 拼接 teleop_hand_and_arm.py 启动命令 注入 CYCLONEDDS_URI 环境变量 ↓ PTY 启动进程 通过发送 r、q 等按键控制运行状态GUI 和命令行是同一套底层逻辑的两种入口参数完全一致。6.2 GUI 封装的关键参数参数说明--arm机器人型号g1、h1 等--ee末端执行器类型dex3、inspire 等--input-modehand手势/ controller手柄--display-modeimmersive / pass-through / ego--network-interfaceDDS 网卡名必须正确--img-server-ip图像服务端 IPCYCLONEDDS_URIDDS 配置文件路径6.3 使用建议长期在实验室使用时建议保留 GUI主要好处是降低现场误操作概率减少 DDS 网卡、脚本路径、Python 环境路径输错的情况。七、真机启动 SOP1. 确认机器人网络通畅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/?wswss://PC_IP:8012 首次需要接受自签名证书警告 4. XR 页面中点击 virtual reality 5. 等待 XR 手臂与机器人手臂完成映射 6. PC 端点击开始遥操机器人进入跟随 7. 结束时先做安全收尾动作再退出程序八、关键参数说明–network-interface决定 DDS 走哪张网卡。机器人局域网通常是192.168.123.X如果 PC 有多张网卡填错这个参数机器人侧收不到任何控制指令。–input-modehand使用手势跟踪需要 XR 设备支持手部追踪controller使用手柄跟踪–display-modeimmersive机器人第一视角沉浸显示链路最直观调试首选pass-throughXR 透传不显示机器人图像ego中央小窗显示机器人视角周围保留现实视野–img-server-ip图像服务端所在主机的 IP通常是机器人本体或外接计算单元的地址必须与实际服务地址一致。九、总结9.1 项目本质xr_teleoperate不是一个简单的 demo而是一个完整的遥操作系统原型XR输入 视频回传 双臂IK 灵巧手 retargeting DDS控制 数据录制每一层都有对应的模块。9.2 部署核心要点1. conda 环境创建时就锁定 numpy1.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_URIfile://$(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
宇树 G1-D + Pico 4 XR 遥操作环境搭建
发布时间：2026/5/25 9:01:30
宇树 G1-D Pico 4 XR 遥操作环境搭建xr_teleoperate 项目解析与踩坑总结官方项目地址https://github.com/unitreerobotics/xr_teleoperate适用平台Ubuntu 20.04 / 22.04适用场景G1-D Dex3-1 Pico 4 遥操作部署目录项目是做什么的系统架构环境安装关键踩坑依赖版本冲突证书配置Pico vs AVP图形化启动器 xr_teleop真机启动 SOP关键参数说明总结一、项目是做什么的xr_teleoperate是宇树官方开源的遥操作系统目标是让操作者戴上 XR 设备后通过手势或控制器直接驱动机器人双臂和灵巧手并支持数据采集。支持的硬件组合机器人末端执行器XR 设备G1、H1、H1_2Dex3-1、Dex1、Inspire、BrainCoPico 4、Quest、Apple Vision Pro二、系统架构2.1 数据流XR 设备输入头部/手腕/手指姿态 ↓ TeleVuerWrapperOpenXR坐标系 → 机器人坐标系 ↓ Arm IK双臂逆运动学求解 Hand Retargeting人手25关键点 → 机械手关节角 ↓ unitree_sdk2_pythonDDS下发控制命令 ↓ 机器人双臂 灵巧手执行 机器人相机图像 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 opensslgit3.2 创建 conda 环境# 必须在创建时就锁定 numpy1.26.4 和 pinocchio3.1.0后装会有冲突conda create-ntvpython3.10pinocchio3.1.0numpy1.26.4 pip-cconda-forge-yconda activate tv3.3 克隆仓库并初始化子模块gitclone https://github.com/unitreerobotics/xr_teleoperate.gitcdxr_teleoperate# 必须加 --recursivedex-retargeting 本身还有嵌套子模块gitsubmodule update--init--recursive--depth13.4 安装依赖pipinstall-rrequirements.txt pipinstall-eteleop/televuer pipinstall-eteleop/robot_control/dex-retargeting pipinstall-eteleop/teleimager3.5 修复版本冲突关键步骤# 强制锁回 numpy防止 vuer 把它升到 2.xpipinstallnumpy1.26.4vuer[all]0.0.60# 回退 params-proto防止 televuer 导入失败pipinstallparams-proto2.13.03.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 版本不兼容 解决创建环境时就锁定 numpy1.26.4安装 vuer 后再次强制锁回4.2 params-proto 版本问题vuer0.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-proto2.13.04.3 版本锁定总结包要求版本原因numpy1.26.4多个依赖不支持 numpy 2.xvuer0.0.60与 televuer 配套params-proto2.13.03.x 移除了 Flagpinocchio3.1.0IK 求解器版本要求五、证书配置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_teleop6.1 工作原理PyQt6 参数面板 ↓ 用户选择参数 拼接 teleop_hand_and_arm.py 启动命令 注入 CYCLONEDDS_URI 环境变量 ↓ PTY 启动进程 通过发送 r、q 等按键控制运行状态GUI 和命令行是同一套底层逻辑的两种入口参数完全一致。6.2 GUI 封装的关键参数参数说明--arm机器人型号g1、h1 等--ee末端执行器类型dex3、inspire 等--input-modehand手势/ controller手柄--display-modeimmersive / pass-through / ego--network-interfaceDDS 网卡名必须正确--img-server-ip图像服务端 IPCYCLONEDDS_URIDDS 配置文件路径6.3 使用建议长期在实验室使用时建议保留 GUI主要好处是降低现场误操作概率减少 DDS 网卡、脚本路径、Python 环境路径输错的情况。七、真机启动 SOP1. 确认机器人网络通畅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/?wswss://PC_IP:8012 首次需要接受自签名证书警告 4. XR 页面中点击 virtual reality 5. 等待 XR 手臂与机器人手臂完成映射 6. PC 端点击开始遥操机器人进入跟随 7. 结束时先做安全收尾动作再退出程序八、关键参数说明–network-interface决定 DDS 走哪张网卡。机器人局域网通常是192.168.123.X如果 PC 有多张网卡填错这个参数机器人侧收不到任何控制指令。–input-modehand使用手势跟踪需要 XR 设备支持手部追踪controller使用手柄跟踪–display-modeimmersive机器人第一视角沉浸显示链路最直观调试首选pass-throughXR 透传不显示机器人图像ego中央小窗显示机器人视角周围保留现实视野–img-server-ip图像服务端所在主机的 IP通常是机器人本体或外接计算单元的地址必须与实际服务地址一致。九、总结9.1 项目本质xr_teleoperate不是一个简单的 demo而是一个完整的遥操作系统原型XR输入 视频回传 双臂IK 灵巧手 retargeting DDS控制 数据录制每一层都有对应的模块。9.2 部署核心要点1. conda 环境创建时就锁定 numpy1.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_URIfile://$(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
