从宇树摇操avp_teleoperate到unitree_IL_lerobot：如何基于宇树人形进行二次开发(含Open-TeleVision源码解析)
前言
如之前的文章所述，我司「七月在线」正在并行开发多个订单，目前正在全力做好每一个订单，因为保密协议的原因，暂时没法拿出太多细节出来分享
但可以持续解读我们所创新改造或二次开发的对象，即解读paper和开源库「当然 有些paper/库还没开始用，但也可以提前解读，作为关注了解」
而对于我司人形开发的订单，背后的机器人多半基于这三家：宇树、傅利叶、乐聚
- 通过此文《Fourier-Lerobot——把斯坦福人形动作策略iDP3封装进了Lerobot(含我司七月的idp3落地实践)》可知，傅利叶 把我司用的比较多的idp3 装进了lerobot
- 类似的，宇树 通过此开源库「unitree_IL_lerobot」，也把lerobot 集成了下
该库包含了我司同样用的比较多的：π0策略
且无论咱们是用傅利叶集成的lerobot——idp3，还是宇树集成的lerobot——π0，都是可以用宇树开源的摇操代码avp_teleoperate「其基于此文《UC San Diego的三大机器人：AnyTeleop、Open-TeleVision、Bunny-VisionPro——从RGB相机到VR远程控制机器人》第二部分介绍的Open-television改造」去收集数据的，相当于
| ipd3 | π0 | ACT | 附录：直接支持3d输入的vla | ||||
| 第一步 摇操采集 | 可以宇树VR摇操采集3d数据 | 也可以通过ipd3官方开源的摇操代码采集3d点云数据 | 可以宇树VR摇操采集3d数据，然后3d 改成2d数据，以去适配π0的 数据输入格式 | 宇树VR摇操采集3d数据 毕竟其改造的Open-television | 任意摇操方式 | ||
| 第二步 动作预测 | 要么傅利叶集成idp3的lerobot库：Fourier-Lerobot，做模仿学习 | 要么直接通过ipd3官方库做模仿学习 | 宇树集成的unitree_IL_lerobot | lerobot官方库：包含π0 | π0官方库 | 那自然可以用Open-television中所用的ACT策略 | 直接VLA交互 |
如此，本文便来了：从宇树摇操avp_teleoperate到unitree_IL_lerobot：如何基于宇树人形机器人进行二次开发
第一部分 Apple Vision Pro实现Unitree 人形机器人的远程操作
接下来，我们通过此教程《Apple Vision Pro 遥操作示例》，详细介绍下如何使用 Apple Vision Pro 进行遥操作，以控制宇树科技的 Unitree H1_2 手臂的示例程序。开发者只需佩戴 Vision Pro，即可通过摄像头进行手势追踪以操作机器人
1.1 Ubuntu、双臂 inverse kinematics 环境配置、unitree_dds_wrapper 配置
- Ubuntu 20.04 和 Ubuntu 22.04 操作系统下进行测试
- 双臂 inverse kinematics 环境配置
该部分用于配置人形机器人 H1 双臂（共14个自由度）的末端位姿逆运动学求解相关的软件库
Apple Vision Pro 获取左右两个手腕位姿后，使用 pinocchio 和 CasADi 库加载 URDF 并进行逆运动学计算，求解出到达该位姿的关节电机角度值
meshcat 库则用于调试时在 Web 端进行可视化显示
注意conda create -n tv python=3.8 conda activate tv conda install pinocchio -c conda-forge pip install meshcat
使用 pip 安装的 pinocchio 有可能不是最新版本 3.1.0，本环境需要使用 3.1.0 版本，请仔细检查
必须先安装 pinocchio 并确保安装成功，然后再进行 TeleVision 的环境配置。安装顺序颠倒可能导致会安装好的 TeleVision 环境出错
下文所有终端命令都应该在 conda 的 tv 环境内执行，除非另有说明 - unitree_dds_wrapper 配置
该部分用于配置计算机主机与人形机器人的 unitree_dds_wrapper，可以使用python实现主机和机器人之间的通信、控制。请执行下面命令进行安装# 安装python版本的 unitree_dds_wrapper git clone https://github.com/unitreerobotics/unitree_dds_wrapper.git cd unitree_dds_wrapper/python pip3 install -e .
1.2 TeleVision 环境配置和 Apple Vision Pro 通信配置
本例程在 TeleVision 开源项目基础上修改完成，下述部分配置也可参考该项目的 README 及相关页面。在此，Isaac Gym 仿真环境用于测试配置正确性
1.2.1 基本环境配置和Isaac Gym安装
使用 git 克隆本项目「avp_teleoperate」至本地后，进入到项目路径下，安装基本功能库：
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 证书生成相关配置
首先，安装mkcert
- 安装brew
当要求输入回车键时，请按下回车。然后继续执行：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 - 配置环境变量
eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)" - 使用 brew 安装mkcert
brew install mkcert
接下来，生成证书
- 查看本机 IP 地址
ifconfig | grep inet - 假设本机 IP 地址是192.168.123.2
创建证书
把生成的cert.pem 和 key.pem 两个文件拷贝到项目的 teleop 目录下：mkcert -install && mkcert -cert-file cert.pem -key-file key.pem 192.168.123.2 localhost 127.0.0.1cp cert.pem key.pem ~/avp_teleoperate/teleop/ - 系统防火墙设置
sudo ufw allow 8012 - 在 Apple Vision Pro 中安装证书
上面命令可以获取到 rootCA.pem 的路径。然后通过苹果的隔空投送功能把 rootCA.pem 文件发送到 Apple Vision Promkcert -CAROOT
注意：Apple Vision Pro 接收文件前需要启动文件接收功能，方法是：设置 >> 通用 >> 隔空投送 >> 所有人(10分钟)
1.2.3 启用 Apple Vision Pro 的 WebXR 相关功能、进入VR
设置 >> Apps >> Safari浏览器 >> 高级 >> 功能标志 >> 启用 WebXR 相关功能
接下来，便可以进入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 硬件适配
硬件清单如下所示
| 物品名称 | 数量 | 渲染图 | 说明 |
|---|---|---|---|
| Apple Vision Pro | 1 |
| 参考 Apple 官方网址 |
| 计算机 | 1 | / | x86_64 架构 |
| 人形机器人 H1 | 1 | / | 具体型号为 H1_2 |
| 灵巧手 | 1 |
| H1可搭载 Inspire Robotics (RH56DFX) 的仿人五指灵巧手，该灵巧手具有6个自由度和12个运动关节，可以模拟人手实现复杂动作 具体可参考该文档 |
| 双目相机 | 1 |
| 普通 USB 免驱动双目相机 戴在机器人头部，主要作用是辅助操作人员，通过 Apple Vision Pro 观看到机器人视角下工作空间的视野 |
1.3 启动程序
在执行遥操作的程序前，需要预先启动一些服务支撑的程序
1.3.1 开启灵巧手服务
可以参考《RH56DFX灵巧手开发》配置相关环境和编译控制程序
关于控制方式，因时机械手官方SDK通过串口进行通讯，H1提供一个USB转串口模块，用户可以将该USB插在H1开发计算单元(PC2, PC3)上进行通讯控制灵巧手。此时端口通常为/dev/ttyUSB0
- 使用因时官方SDK控制
用户可以根据因时灵巧手官方通讯协议自行编写程序控制灵巧手- 使用宇树灵巧手SDK控制
H1通信建立在DDS框架之上，为便于使用unitree_sdk2进行控制灵巧手。宇树提供将串口收发的数据转为DDS消息的示例程序关于宇树SDK接口的说明
- 用户向 "rt/inspire/cmd" 话题发送 "unitree_go::msg::dds::MotorCmds_" 消息控制灵巧手
从 "rt/inspire/state" 话题接受 "unitree_go::msg::dds::MotorStates_" 消息获取灵巧手状态
- 首先到 该网址oss-global-cdn.unitree.com/static 下载灵巧手控制接口程序，并将之拷贝到 机器人 Unitree H1_2 的 PC2 中
- 其次，在 PC2 中解压完成后，使用下述命令进行编译
sudo apt install libboost-all-dev libspdlog-dev # Build project cd h1_inspire_service & mkdir build & cd build cmake .. -DCMAKE_BUILD_TYPE=Release make# Terminal 1. Run h1 inspire hand service sudo ./inspire_hand -s /dev/ttyUSB0# Terminal 2. Run example ./h1_hand_example
如果发现左右灵巧手所有手指不断循环张开、闭合动作则表示成功。确认成功后，关闭 Terminal 2 中的 ./h1_hand_example 程序即可
- 双臂可以进行遥操作，但是灵巧手却不会动，怎么办？
- A: 程序中，双臂和灵巧手的控制指令是分开的。先通过上面「开启灵巧手服务」内容中所述的 h1_hand_example 程序检测灵巧手是否正常工作
1.3.2 开启图像推流服务
- 把 avp_teleoperate/teleop/image_server 目录中的 image_server.py 拷贝到机器人 Unitree H1_2 的 PC2 中，并在 PC2 内执行下面命令：
注意：这里需要检查 OpenCV 读取图像时的参数是否与双目相机硬件匹配，以及对于推流使用的默认5555端口是否可用sudo python3 image_server.py - 图像推流服务开启以后，可以在主机终端使用 image_client.py 测试通信是否成功（测试成功后记得关闭该程序）：
python image_client.py
1.3.3 启动遥操作程序
python teleop_hand_and_arm.py
# 程序启动后，如果配置正确，终端最终输出 `Please enter the start signal (enter 's' to start the subsequent program):` 信息。# 此时，佩戴 Apple Vision Pro 的操作人员应将手臂形状摆放为与 Unitree H1_2 初始姿态相接近的姿势，避免初始位姿差距过大导致机器人产生过大的摆动。
# 当操作人员姿势摆放好后，主机操作人员可按下 `s` 字母和回车键，正式启动遥操作程序。这时，机器人双臂便可跟随佩戴 Apple Vision Pro 的操作人员双臂移动1.4 avp_teleoperate的代码结构
代码的整体结构与 TeleVision 保持一致，此处只着重介绍与 Unitree Robot 相关的文件目录
avp_teleoperate/
│
├── act 存放模仿学习策略相关文件
│
├── assets 存放机器人 URDF 相关文件
│
├── scripts 存放一些工具类文件
│
├── teleop 存放遥操作主要文件
│ │
│ ├── image_server/ 图像推流服务端与客户端相关代码
│ │ |
│ │ ├── image_client.py 客户端（仅用于测试 Unitree H1_2 上的图像推流服务是否正常）
│ │ |
│ │ ├── image_server.py 服务端（捕获相机的图像并通过网络对外发送，该代码在 Unitree H1_2 上运行）
│ │
│ ├── robot_control/ 存放IK解算、手臂控制相关文件
│ │ |
│ │ ├── robot_arm_ik.py 双臂IK解算代码
│ │ |
│ │ ├── robot_arm.py 双臂控制代码
│ │ |
│ │ ├── robot_hand.py 机械手控制代码
│ │
│ │──teleop_hand_and_arm.py 遥操作的启动程序代码
│ │
│ │──teleop_hand.py 可用于测试环境配置// 待更
第二部分 Open-TeleVision与avp_teleoperate的源码解析
如本文开头所提到的， 此文《UC San Diego的三大机器人：AnyTeleop、Open-TeleVision、Bunny-VisionPro——从RGB相机到VR远程控制机器人》第二部分介绍了Open-television，其GitHub地址为：github.com/OpenTeleVision/TeleVision
接下来，我们来整体了解下该television库的整体结构——不过 不逐行分析了
该项目主要分为以下几个核心部分：
- 远程操作系统(teleop/)
- 模仿学习模块(act/)
- 机器人资源文件** (assets/)
- 辅助脚本(scripts/)
- 图像资源** (img/)
2.1 远程操作系统 (teleop/)
这是项目的核心部分，负责实现远程操作功能
2.1.1 TeleVision.py
核心类 `OpenTeleVision`，负责初始化远程操作系统，处理视觉反馈和用户交互。它通过 `vuer` 库创建用户界面，并处理手部移动和相机移动事件
2.1.2 teleop_hand.py
处理手部跟踪和控制，将用户手部动作转换为机器人手部控制命令
2.1.3 teleop_active_cam.py
实现主动摄像机控制逻辑，根据用户头部动作调整摄像机视角
2.1.4 Preprocessor.py
处理输入数据预处理，如手部姿态和头部位置的标准化
2.1.5 motion_utils.py
提供运动相关的实用函数，如姿态变换和平滑处理
2.1.6 constants_vuer.py
定义系统中使用的常量
2.1.7 dynamixel/ 子目录
- dynamixel_robot.py：实现 Dynamixel 电机控制的机器人类，继承自基本的 `Robot` 类
- active_cam.py：控制主动摄像机，通过 Dynamixel 电机调整摄像机朝向
- robot.py：定义基本机器人接口，提供关节控制等基础功能
- driver.py：Dynamixel 电机驱动程序，负责底层电机通信和控制
- agent.py**：实现代理类，用于机器人行为策略的执行
2.1.8 webrtc/ 子目录
- zed_server.py：ZED 立体摄像头的 WebRTC 流媒体服务器，用于捕获和传输高质量视频流
- webcam_server.py**：普通网络摄像头的 WebRTC 服务器实现
- webcam.py：网络摄像头处理逻辑，用于捕获图像
- client.js和 **index.html：前端界面代码，用于显示视频流和交互
2.2 模仿学习模块 (act/)
这部分实现了基于视觉的模仿学习功能
2.2.1 imitate_episodes.py：处理训练数据和学习过程
模仿学习的主要脚本，处理训练数据和学习过程
2.2.2 policy.py：策略网络，将视觉输入映射到机器人动作
定义机器人策略网络，将视觉输入映射到机器人动作
2.2.3 utils.py
提供模仿学习相关的实用函数
2.2.4 detr/ 子目录
这是基于 DETR(DEtection TRansformer)的视觉模型实现
- models/：
- detr_vae.py：结合 DETR 和变分自编码器的视觉模型。
- transformer.py：Transformer 架构实现。
- backbone.py：视觉骨干网络，如 ResNet
- position_encoding.py：位置编码实现
- util/：
- box_ops.py：处理边界框操作的函数
- misc.py：实用函数集合
- plot_utils.py：可视化工具
2.3 机器人资源文件 (assets/)
包含机器人的 3D 模型和配置文件
2.3.1 h1_inspire/
包含 Inspire 机器人的 URDF 模型、网格文件和启动脚本
2.3.2 inspire_hand/
Inspire 机器人手部的 URDF 模型和网格文件
2.4 辅助脚本 (scripts/)
包含用于部署、评估和数据处理的脚本
2.4.1 deploy_sim.py：部署仿真环境的脚本
2.4.2 replay_demo.py「回放演示数据的脚本
2.4.3 plot_action.py：绘制机器人动作的脚本
2.4.4 post_process.py：后处理数据的脚本
2.5 核心调用关系
2.5.1 远程操作系统的调用流程
- TeleVision.py 作为入口点，初始化 `OpenTeleVision` 类
- 它使用 `webrtc/zed_server.py` 或直接共享内存图像来提供视觉反馈
- 当收到用户交互事件时（如手部移动或相机移动），调用相应的处理函数
- 手部控制通过 `teleop_hand.py` 实现，将用户手势转换为机器人控制命令
- 摄像机控制通过 `teleop_active_cam.py` 和 `dynamixel/active_cam.py` 实现
2.5.2 机器人控制链
- `teleop_hand.py` → `dynamixel/agent.py` → dynamixel_robot.py → `dynamixel/driver.py`
- 从高级手势识别到低级电机指令的转换过程。
2.5.3 视觉反馈路径
- `webrtc/zed_server.py` 捕获 ZED 摄像头数据
- 通过 WebRTC 协议将视频流传输到客户端
- 客户端通过 `webrtc/client.js` 和 `webrtc/index.html` 显示视频流
2.5.4 模仿学习流程：收集和处理数据，之后DETR提取特征、策略训练、控制
- imitate_episodes.py 收集和处理用户演示数据
- 使用 detr 中的视觉模型提取特征
- policy.py 学习将视觉状态映射到机器人动作
- 学习后的策略可用于自动化控制
2.5.5 数据共享机制
- 系统使用进程间通信机制，如共享内存、队列和事件
- 手部姿态数据通过 `left_hand_shared` 和 `right_hand_shared` 共享数组传递
- 头部位置数据通过 `head_matrix_shared` 共享
- 这些共享数据结构允许实时、低延迟的数据传输
// 待更