跳到主要内容

Fourier高级机器人遥操系统（F.A.R.T.S.）

teleoperation setup

欢迎来到Fourier高级机器人遥操系统（F.A.R.T.S.）。本系统使用VR头显与手势跟踪实现了实时人形机器人控制，其主要是为适配傅利叶GRX系列机器人设计的系统，同时也兼容其他机型。该系统支持多种摄像头（如Depthai Oak、Intel RealSense及通用USB摄像头），同时也可以实现模仿学习与视觉语言动作（VLA）的数据采集。

🗺️ 规划目录​

  • 为数据采集和Docker安装添加更多文档

  • 为带触觉传感器的傅利叶12自由度手提供支持

  • 增加添加新表情教程及通用开发指南

  • 迁移至结构化配置系统

  • 改用evdev替代pynput处理键盘输入以避免Wayland问题

  • 添加GR2机器人立体摄像头应用udev规则的说明

🛍前置条件​

🔧 硬件要求​

  • 机型：傅利叶GRX 系列机器人（GR1T1、GR1T2、GR2）。

  • 灵巧手：傅利叶6自由度灵巧手、傅利叶12自由度灵巧手或因时手。

  • 摄像头：Depthai Oak、Intel RealSense D435 或通用USB摄像头。

  • VR 头显：Apple Vision Pro 或 Meta Quest 3。

  • 主机：Ubuntu 20.04及以上版本操作系统，并搭配性能良好的 CPU。

  • 网络：确保主机和 VR 头显处于同一网络。

    若使用 Apple Vision Pro，需要确保稳定的Wi-Fi连接。

    若使用 Meta Quest 3，可通过USB-C线缆连接头显与主机。

[!重要]

建议您在首次配置机器人或遇到硬件相关问题时，优先联系傅利叶技术支持团队以获取专业指导。

安装机器人以及处理每一代傅利叶机器人的特定问题可能较为复杂，这些内容不包含在本教程的范围内。

后续教程将默认您已基本了解硬件安装以及机器人已完成初始化并正常运行。

👓VR头显设置​

VisionPro

苹果公司限制在非HTTPS连接下访问WebXR功能。如需在本地测试应用程序，需配置自签名证书并在客户端设备上安装该证书。

[!注意]

请确保VisionPro头显与Ubuntu主机处于同一网络内。

  1. 在Safari浏览器中启用WebXR相关功能： 确保VisionPro设备上已安装最新版VisionOS，之后进入Safari高级设置：设置 > 应用 > Safari > 高级 > 功能开关。启用所有WebXR相关功能（不同版本VisionOS中功能选项名称可能不同）

  2. 安装自签名证书：我们将使用 mkcert 工具创建自签名证书。mkcert 是一个零配置的轻量级工具，可快速生成本地开发环境信任的证书。具体设置步骤如下：

    1. 请按照mkcert官网说明完成mkcert安装。

    2. 使用 mkcert 生成证书时，请确保命令中包含计算机的本地IP地址，命令如下所示：

      mkcert -install && mkcert -cert-file cert.pem -key-file key.pem {Your IP address} localhost 127.0.0.

      [!重要]

      请确保将 {Your IP address} 替换为Ubuntu主机的实际IP地址。可以在终端运行 ifconfig 命令查询IP地址，通常格式为 192.168.x.x 或 10.0.x.x。

      [!提示]

      对于 Ubuntu 主机，使用zeroconf地址代替IP地址会更便捷。zeroconf 地址通常为$(hostname).local，可以在终端运行 echo "$(hostname).local" 来获取。

    3. 防火墙设置

      sudo iptables -A INPUT -p tcp --dport 8012 -j ACCEPT
      sudo iptables-save
      sudo iptables -L

      或者使用ufw设置防火墙

      sudo ufw allow 8012

    4. 在 VisionPro 上安装 ca-certificates

      mkcert -CAROOT

      将 rootCA.pem文件通过Airdrop传输到VisionPro设备。或者，可以压缩 rootCA.pem 文件，并在 Ubuntu 主机上启动本地服务器，供 Vision Pro 设备下载。

    5. 将key.pem和cert.pem放入certs文件夹，以确保脚本能够访问这些证书文件。

Meta Quest

  1. 按照官方指南在MetaQuest设备上启用开发者模式。

  2. 可以执行下面的命令在主机上安装adb（默认使用是Ubuntu系统）：

    sudo apt install android-tools-adb

    接着执行以下命令来启动adb服务器：

    adb start-server

  3. 使用USB-C数据线将Meta Quest设备连接至电脑，当弹出提示时，请允许USB调试。

  4. 每次运行程序前，使用以下命令转发端口：

    adb reverse tcp:8012 tcp:8012

📷摄像头驱动程序安装​

[!注意]

目前仅全面测试了RealSense D435和OAK-D-W-97摄像头，使用其他型号摄像头可能需要调整部分配置。

DepthAI Oak Camera

使用以下命令安装DepthAI库：

sudo wget -qO- https://docs.luxonis.com/install_dependencies.sh | bash

[!注意]

如果使用多摄像头设置，请务必在oak_multi.yaml文件中更新每台摄像头的序列号。

Intel RealSense Camera

请按照官方说明安装librealsense库

[!注意]

请务必在 realsense_multi.yaml 或 realsense.yaml文件中更新每台摄像头的序列号。

ZED Camera

ZED 安装包括两个部分：

  • 安装 ZED SDK: ZED SDK 可以从 官方网站中安装. 请选择与你的操作系统匹配的版本。

  • 安装 ZED Python API

    ZED python API 可以通过运行一下命令进行安装:

    # Activate the your virtual environment
    conda activate teleop

    # install Python (x64 version) and the pip package manager. Then install the dependencies via pip in a terminal.
    python -m pip install cython numpy opencv-python pyopengl

    # Install ZED python API
    cd /usr/local/zed/
    python get_python_api.py

📐GR1T1/T2标定​

FARTS 兼容多个版本的傅利叶机器人SDK。 对于GR1T1或GR1T2机器人，目前建议使用grx后端。尽管grx后端正逐步被 hardware 后端取代，但它仍是经过最充分测试且最稳定的版本。 推荐通过Docker容器使用grx后端，我们提供了一个便捷脚本，用于运行搭载 grx 后端的 Docker 容器，可以通过运行以下命令启动容器：

cd ./server_config # You need to be in the server_config directory for the directory to be mounted correctly to the docker container
./run_server.sh gr1t1

上述操作会将server_config目录挂载到 Docker 容器中，并启动GRX服务器。可以通过指定“gr1t1”或“gr1t2”作为参数选择运行不同版本的机器人Docker 容器。

[!重要]

如果是首次运行grx后端，则需要先对机器人进行标定。当grx Docker 容器已运行且已将机器人置于初始位置时，可通过在新终端中执行以下命令来完成标定：

./scripts/grx_calibrate.sh

执行此脚本将触发标定流程，标定数据会自动保存至server_config目录下的sensor_offset.json文件中。 标定完成后，请先终止grx Docker容器并重新启动，以确保标定数据正确加载。

🚀入门指南​

首先克隆repo：

git clone https://github.com/FFTAI/teleoperation.git

使用uv来管理依赖项，可以按照官方指南在机器上安装 uv。

安装成功后，执行以下命令创建一个新的虚拟环境：

# create a 3.11 virtual environment using uv
uv venv -p 3.11

或者，如果想使用conda管理Python版本，可以执行以下操作：

# create a 3.11 virtual environment using conda
conda create -n teleop python=3.11 ffmpeg==7.1.1
conda activate teleop
uv venv -p $(which python)

接着执行以下命令安装依赖项：

# resolve the dependencies
uv sync --extra depthai # if you are using Oak camera
# OR
uv sync --extra realsense # if you are using realsense camera
# activate the virtual environment
source .venv/bin/activate

下面就可以执行以下命令来运行demo脚本：

[!提示]

若系统为 Ubuntu 22.04 或更高版本，建议使用Hyper 终端或 VSCode 的内置终端来运行脚本。由于 pynput 在 Wayland 环境下对键盘事件的监听可能存在兼容性问题，使用上述终端可避免潜在问题。

# if you are using Apple Vision Pro:
python -m teleoperation --config-name teleop robot=gr1t1_legacy hand=fourier_dexpilot_dhx camera=oak_97 robot.visualize=true mocap=avp sim=true

# OR if you are using Meta Quest 3
python -m teleoperation --config-name teleop robot=gr1t1_legacy hand=fourier_dexpilot_dhx camera=oak_97 robot.visualize=true mocap=quest sim=true

之后，在主机上访问http://127.0.0.1:7000/static/，就可以看到机器人的可视化界面。

robot visualization

如果使用的是Apple Vision Pro，请在设备的浏览器中访问 https://your-hostname.local:8012?ws=wss://your-hostname.local:8012；如果使用的是Meta Quest 3，则访问 http://localhost:8012?ws=ws://localhost:8012。随后就可以在浏览器页面上看到摄像头画面。

最后，点击网页中的Enter VR按钮并授予必要的权限来启动VR会话。

若可视化画面中手部位置出现偏移，可通过长按 Vision Pro 设备上的旋钮按钮（直至听到提示音）来重置跟踪系统。

teleoperation

🕹️使用方式​

🕹️遥控操作​

我们使用Hydra管理配置，可以选择配置文件并通过 Hydra 的覆盖语法进行参数覆盖。 脚本默认加载 teleop 配置，运行时必须指定手部、摄像头和机器人的参数配置。

python -m teleoperation --config-name teleop robot=??? hand=??? camera=??? robot.visualize=true mocap=avp

机器人（robot）、手部（hand）和 摄像头（camera）参数的可选配置如下：

  • 机器人（robot）
    • gr1t1_legacy: 使用旧版grxSDK的gr1t1机器人
    • gr1t2_legacy: 使用旧版grxSDK的gr1t2机器人
    • gr2_hardware: 使用全新试用版SDK的gr2机器人
  • 手部（hand）
    • fourier_dexpilot_dhx:傅利叶6自由度灵巧手
    • fourier_12dof_dexpilot:傅利叶12自由度灵巧手
    • inspire_dexpilot:因时手
  • 摄像头（camera）
    • oak_97: Depthai Oak-D-W-97摄像头
    • realsense: Intel RealSense D435 摄像头（需在配置文件中指定设备序列号）
    • realsense_multi: Intel RealSense D435多摄像头配置
    • opencv: 基于OpenCV的通用 USB 摄像头，需在命令行中添加camera=opencv camera.instance.port=/dev/video0 指定设备端口

下面是一些其他有用的参数：

  • robot.visualize: 是否在浏览器中可视化机器人状态，默认值为 false。

  • mocap: 使用的动作捕捉系统类型，选项为avp（适用于Apple Vision Pro）和quest（适用于Meta Quest 3），默认值为avp。

  • sim: 是否启用仿真模式，默认值为 false。使用真实机器人时值为false，使用仿真模式时值为 true。

  • debug_hand: 是否在浏览器中可视化手部跟踪数据，默认值为 false。

  • use_depth: 是否采集深度数据，默认值为 false。

  • use_head: 是否启用头部跟踪功能，默认值为 false。若设为 true，机器人将同步操作者的头部运动（适用于需要边操作边环视四周的远程控制场景）。

  • use_waist: 是否启用腰部跟踪功能，默认值为 false。若设为 true，机器人将同步操作者的腰部动作。

    [!注意]

    请确保机器人已正确标定零位，并且在运行脚本前取出所有标定插销，否则可能会损坏机器人或导致异常运行。如需使用该功能，请联系傅利叶技术支持团队获取更多详细指导。

  • gravity_compensation: 是否启用重力补偿功能，默认值为 false。若设为 true，机器人运动时将自动进行重力补偿。

    [!注意]

    该功能为实验性特性，对网络延迟极为敏感。如需使用，请咨询傅利叶技术支持团队获取更多详细指导。

[!提示]

可以在configs目录中查看详细的配置说明，其中包含多种摄像头和机器人的配置示例。

🏭数据采集​

若要记录数据，可以使用daq配置文件并指定任务名称，其语法与遥操配置文件相同，但需使用不同的配置文件：

python -m teleoperation --config-name daq robot=gr1t2_legacy camera=oak task_name=${task_name}

如需了解更多配置选项，请参考configs/daq.yaml文件或查看scripts/data_collection.sh文件。

[!注意]

如果使用真实机器人，请在启动脚本前确保机器人周围留有足够的空间，因为机器人会自动移动到起始位置。

开始遥操/数据采集​

建议两人一起进行遥操，尤其是数据采集。一人是佩戴 VR 并控制机器人的操作员A，另一人是监控机器人位置并帮助操作员A启动遥操的操作员B。

启动程序后，可以在 Apple VisionPro 设备上打开浏览器并访问：https://your-hostname.local:8012?ws=wss://your-hostname.local:8012。若使用 Meta Quest 3，则访问：http://localhost:8012?ws=ws://localhost:8012。若已经打开网址，刷新页面并单击，直至在 VR 会话中看到摄像头图像。随后点击Enter VR按钮，授予启动 VR 会话所需的权限。长按Vision Pro设备上的表冠按钮直至听到提示音，来重置Vision Pro 跟踪。

VR会话启动后，头显中将显示 FOV 摄像头画面，此时操作员A尚未进入遥操状态。操作员A需将双手放置在和机器人相同的起始位置，随后通知操作员B在主机上按下Space空格键来启动遥操。建议让操作员B在浏览器可视化界面中检查机器人的位置，确保机器人与操作员A的双手处于相同的位置。

随后，操作员A可通过在VR会话中移动双手启动遥操，机器人将实时跟踪操作员A的手部动作。

如需停止遥操，操作员B可再次按下Space空格键，或直接在终端输入Ctrl+C终止脚本运行。

数据采集过程与遥操大致相同。首次按下Space空格键启动遥操后，操作员B可再次按下Space空格键开始数据采集。数据采集启动后，操作员A会在visionPro的 VR 会话中看到一个红点，表明数据采集正在进行。操作员B可再次按下Space空格键停止数据采集，或按下x键丢弃当前片段。采集的数据将按照命令行中指定的任务名称保存到data目录。

可以观看视频了解如何在Vision Pro设备中访问 VR 会话：

📦Docker 安装​

以下是使用我们提供的Docker容器在GR1 pro（GR1T2）机器人上进行数据采集的步骤： 首先，在server_config目录中启动run_server.sh脚本。请务必先对机器人进行标定。

接着可以使用以下命令运行脚本：

mkdir -p ./outputs
mkdir -p ./data
./scripts/run_daq_docker.sh gr1t2 oak_97 daq_test

🚀部署策略​

此框架也可用于部署通过lerobot训练的策略。首先在server_config目录中启动run_server.sh脚本。

uv sync --extra lerobot --extra depthai
uv pip install -e path/to/lerobot
source .venv/bin/activate
python -m teleoperation.eval \
    --config-name eval_lerobot \
    policy=$POLICY \
    robot.instance.namespace="gr/daq" \
    eval.rerun_enabled=false \
    eval.rerun_endpoint=192.168.xx.xx:9876 \
    policy.instance.pretrained_path=$CKPT

🛠️开发进展​

正在推进

❓常见问题​

在VisionPro设备上打开浏览器时，看到"Your connection is not secure"的提示信息。​

出现该提示是因为使用了自签名证书，依次点击"高级"和"继续前往网站"，系统将提示您接受该证书。

键盘输入无响应或运行脚本时出现 AttributeError: record_create_context 错误。​

这是由于pynput库的限制导致的，Ubuntu 22.04 及更高版本已切换至 Wayland，而 Wayland 对监控键盘事件施加了更多限制。 而这些问题通常在通过SSH运行脚本或使用纯Wayland终端时出现。 解决这个问题最简单的方法是在支持X11的终端中运行脚本，例如VSCode的内置终端或我们内部使用的Hyper 终端。 我们正在开发基于evdev的解决方案来彻底解决问题。

如何重置 Apple Vision Pro 的跟踪功能​

若要重置跟踪功能，请长按Vision Pro设备上的表冠按钮，直至听到提示音，这会将跟踪原点重置为设备的当前位置。

🙏致谢​

本项目基于优秀的OpenTeleVision项目开发，在此特别感谢原作者的杰出贡献。

📖引用​

若本项目对您的研究有所帮助，请考虑引用：

@misc{teleoperation,
  author = {Yuxiang Gao, Shuo Hu, Fourier Co Ltd},
  title = {teleoperation},
  year = {2024},
  publisher = {GitHub},
  journal = {GitHub repository},
  howpublished = {\url{https://github.com/FFTAI/teleoperation}}
}