SONIC 是一个类人行为基础模型，它为机器人提供

系列文章目录

目录

系列文章目录

前言

0.1 什么是 GR00T-WholeBodyControl？

0.2 GEAR-SONIC

0.3 快速入门：Sim2Sim

一、安装（部署）

1.1 先决条件

1.2 克隆仓库

1.3 设置

1.3.1 原生开发（推荐）

1.3.1.1 先决条件：

1.3.1.2 设置步骤：

1.3.2 Docker（ROS2 开发环境）

1.3.2.1 先决条件：

1.3.2.2 快速设置：

1.3.2.3 选项：

1.3.2.4 支持的架构：

1.3.2.5 容器内部：

1.3.3 故障排除：

二、下载模型检查点

2.1 快速下载

2.1.1 安装依赖项

2.1.2 运行下载脚本

2.2 选项

2.2.1 示例

2.3 通过 CLI 手动下载:

2.4 通过 Python 手动下载

2.5 可用文件

2.6 身份验证

2.7 后续步骤:

三、快速入门

3.1 IsaacLab 评估版

3.2 MuJoCo 中的 Sim2Sim

3.2.1 一次性设置：安装 MuJoCo 仿真环境

3.2.2 运行 sim2sim 循环

3.2.2.1 终端 1 — MuJoCo 模拟器（主机，从仓库根目录开始）：

3.2.2.2 终端 2 — 部署（主机或 Docker，来自 gear_sonic_deploy/）：

3.3 Real Robot

3.4 在线可视化

四、VR 遥操作设置（PICO）

4.1 所需硬件

4.2 安装XRoboToolkit

4.2.1 PC 服务

4.2.2 PICO 应用程序

4.3 运动追踪器设置

4.3.1 动作追踪器校准

4.4 安装 PICO 遥控环境

4.5 将 PICO 连接到您的工作站

---

前言

        欢迎阅读 GR00T 全身控制（WBC）的官方文档！这是一个用于开发和部署先进人形机器人控制器的统一平台。

0.1 什么是 GR00T-WholeBodyControl？

        该代码库是以下内容的基础：

• NVIDIA Isaac-Gr00t、Gr00t N1.5 和 N1.6 中使用的解耦 WBC 模型
• GEAR-SONIC 系列：来自 GEAR 团队的尖端控制器

0.2 GEAR-SONIC

SONIC 是一个类人行为基础模型，它为机器人提供了一套从大规模人类动作数据中学习而来的核心运动技能。与为每个动作单独构建控制器不同，SONIC 将动作追踪作为可扩展的训练任务，因此单一套统一策略即可产生自然的全身运动，并支持多种多样的行为。

        ???? 主要特点：

• ???? 自然的全身运动（行走、爬行、动态动作）
• ???? 支持实时 VR 遥操作
• ???? 高级规划与交互的基础
• ???? 即用型 C++ 推理栈

0.3 快速入门：Sim2Sim

        在将代码部署到真实硬件之前，先在 MuJoCo 中快速测试 SONIC 部署栈。

---

一、安装（部署）

1.1 先决条件

        所有配置均需满足：

• Ubuntu 20.04/22.04/24.04 或其他基于 Debian 的 Linux 发行版
• CUDA 工具包（用于 GPU 加速）
• TensorRT（用于推理优化）——请先安装此组件！
• Jetpack 6（用于机载部署）
• Python 3.8+
• 支持 LFS 的 Git

        从 NVIDIA 开发者网站下载 TensorRT：

Platform	TensorRT Version
x86_64 (Desktop)	10.13
Jetson / G1 onboard Orin	10.7 (requires JetPack 6 )

提示

        请下载 TAR 包（而非 DEB 包），这样您就可以将 TensorRT 解压到任意位置。该压缩包大小约为 10 GB；建议使用 pv 命令监控下载进度：

警告:

        上述版本均为经过测试的版本。使用其他版本的 TensorRT 可能会导致推理问题。如果您打算使用其他版本，请先在模拟环境中进行测试。

sudo apt-get install -y pv
pv TensorRT-*.tar.gz | tar -xz -f -

        将解压后的 TensorRT 移动到 ~/TensorRT（或类似路径），并在 ~/.bashrc 中添加以下内容：

export TensorRT_ROOT=$HOME/TensorRT

1.2 克隆仓库

git clone https://github.com/NVlabs/GR00T-WholeBodyControl.git
cd GR00T-WholeBodyControl
git lfs pull          # make sure all large files are fetched

1.3 设置

1.3.1 原生开发（推荐）

        优点：直接系统安装，构建速度更快，可直接投入生产。

警告

        对于 G1 板载部署，我们需要将板载 Orin 升级至 Jetpack 6 以支持 TensorRT。请按照刷写指南进行升级！

1.3.1.1 先决条件：

• 基本开发工具（cmake、git 等）
• （可选）若计划使用基于 ROS2 的输入/输出，请安装 ROS2

1.3.1.2 设置步骤：

1. 安装系统依赖项：

   cd gear_sonic_deploy
   chmod +x scripts/install_deps.sh
   ./scripts/install_deps.sh

2. 环境配置：

   source scripts/setup_env.sh

   安装脚本将自动：

   配置 TensorRT 环境

   设置所有必要的路径

   为了方便起见，您可以将环境配置添加到您的 shell 配置文件中：

   echo "source $(pwd)/scripts/setup_env.sh" >> ~/.bashrc

3. 构建项目：

   just build

1.3.2 Docker（ROS2 开发环境）

        我们提供了一个基于 ROS2 Humble 的统一 Docker 环境，支持 x86_64 和 Jetson 平台。

1.3.2.1 先决条件：

• 已安装 Docker 且用户已加入 docker 组
• 主机上已设置 TensorRT_ROOT 环境变量
• 对于 Jetson：JetPack 6.1+ (CUDA 12.6)

1.3.2.2 快速设置：

# 1. Add user to docker group (one-time setup)
sudo usermod -aG docker $USER
newgrp docker

# 2. Set TensorRT path (add to ~/.bashrc for persistence)
export TensorRT_ROOT=/path/to/TensorRT

# 3. Launch container
cd gear_sonic_deploy
./docker/run-ros2-dev.sh

1.3.2.3 选项：

./docker/run-ros2-dev.sh               # Standard build (fast)
./docker/run-ros2-dev.sh --rebuild     # Force rebuild
./docker/run-ros2-dev.sh --with-opengl # Include OpenGL for visualization (RViz, Gazebo)

1.3.2.4 支持的架构：

• x86_64：CUDA 12.4.1（需要 NVIDIA 驱动程序 550 及以上版本）
• Jetson：运行于 CUDA 12.6 主机上的 CUDA 12.4.1 容器（向前兼容）

1.3.2.5 容器内部：

source scripts/setup_env.sh # set up dependency
just build                  # Build
just --list                 # Show all commands

1.3.3 故障排除：

• 如果出现“权限被拒绝”的提示，请确保您已加入 docker 用户组
• 在启动容器之前，必须在主机上配置好 TensorRT
• 对于 Jetson：请先在主机上运行 source scripts/setup_env.sh（用于设置 jetson_clocks）

二、下载模型检查点

        预训练的 GEAR-SONIC 检查点（ONNX 格式）托管在 Hugging Face 上：

nvidia/GEAR-SONIC

2.1 快速下载

2.1.1 安装依赖项

pip install huggingface_hub

2.1.2 运行下载脚本

        在仓库根目录下，运行：

python download_from_hf.py

        这将把最新的策略编码器、解码器和运动规划器下载到 gear_sonic_deploy/ 目录下，并保留与部署二进制文件所期望的相同目录结构。

2.2 选项

Flag	Description
--no-planner	跳过运动学规划器下载
--output-dir PATH	覆盖目标目录
--token TOKEN	HF 令牌（huggingface-cli 登录的替代方案）

2.2.1 示例

# Policy + planner (default)
python download_from_hf.py

# Policy only
python download_from_hf.py --no-planner

# Download into a custom directory
python download_from_hf.py --output-dir /data/gear-sonic

2.3 通过 CLI 手动下载:

        如果您更倾向于使用 Hugging Face CLI：

pip install huggingface_hub[cli]

# Policy only
huggingface-cli download nvidia/GEAR-SONIC \
    model_encoder.onnx \
    model_decoder.onnx \
    observation_config.yaml \
    --local-dir gear_sonic_deploy

# Everything (policy + planner)
huggingface-cli download nvidia/GEAR-SONIC --local-dir gear_sonic_deploy

2.4 通过 Python 手动下载

from huggingface_hub import hf_hub_download

REPO_ID = "nvidia/GEAR-SONIC"

encoder = hf_hub_download(repo_id=REPO_ID, filename="model_encoder.onnx")
decoder = hf_hub_download(repo_id=REPO_ID, filename="model_decoder.onnx")
config  = hf_hub_download(repo_id=REPO_ID, filename="observation_config.yaml")
planner = hf_hub_download(repo_id=REPO_ID, filename="planner_sonic.onnx")

print("Policy encoder :", encoder)
print("Policy decoder :", decoder)
print("Obs config     :", config)
print("Planner        :", planner)

2.5 可用文件

nvidia/GEAR-SONIC/
├── model_encoder.onnx         # Policy encoder
├── model_decoder.onnx         # Policy decoder
├── observation_config.yaml    # Observation configuration
└── planner_sonic.onnx         # Kinematic planner

        该下载脚本会将它们放置到部署二进制文件所期望的布局中：

gear_sonic_deploy/
├── policy/release/
│   ├── model_encoder.onnx
│   ├── model_decoder.onnx
│   └── observation_config.yaml
└── planner/target_vel/V2/
    └── planner_sonic.onnx

2.6 身份验证

        该仓库为公开仓库——下载无需令牌。

        如果您触发了速率限制或需要访问私有分支：

# Option 1: CLI login (recommended — token is saved once)
huggingface-cli login

# Option 2: environment variable
export HF_TOKEN="hf_..."
python download_from_hf.py

# Option 3: pass token directly
python download_from_hf.py --token hf_...

        请访问 huggingface.co/settings/tokens 获取免费令牌。

2.7 后续步骤:

        下载完成后，请按照《快速入门指南》的说明，在 MuJoCo 仿真环境或真实硬件上运行部署堆栈。

三、快速入门

        几分钟内即可开始使用 SONIC！

        首先，请确保您已完成安装指南。

安全警告

        机器人可能具有危险性。请确保安全区域畅通无阻，安排一名安全操作员在键盘前方待命以触发紧急停止，并自行承担使用本软件的风险。作者和贡献者对因使用或误用本项目而造成的任何损害、伤害或损失概不负责。

3.1 IsaacLab 评估版

        即将推出！

3.2 MuJoCo 中的 Sim2Sim

        要在 MuJoCo 模拟器中进行测试，请在不同的终端中分别运行模拟循环和部署脚本。

注意

        MuJoCo 模拟器（终端 1）在主机的 Python 虚拟环境中运行——它不在 Docker 容器内。部署二进制文件（终端 2）既可以在主机上原生运行，也可以在 Docker 容器内运行。若使用 Docker，请在主机上运行终端 1，并在容器内运行终端 2。

3.2.1 一次性设置：安装 MuJoCo 仿真环境

        在主机（Docker 外部）的仓库根目录（GR00T-WholeBodyControl/）下，运行：

bash install_scripts/install_mujoco_sim.sh

        这将创建一个轻量级的 .venv_sim 虚拟环境，其中仅包含模拟器所需的包（MuJoCo、Pinocchio、Unitree SDK2 等）。

3.2.2 运行 sim2sim 循环

        我们强烈建议您在将代码部署到真实硬件之前，先完整运行此流程，并在模拟环境中熟悉各项控制操作。

3.2.2.1 终端 1 — MuJoCo 模拟器（主机，从仓库根目录开始）：

source .venv_sim/bin/activate
python gear_sonic/scripts/run_sim_loop.py

3.2.2.2 终端 2 — 部署（主机或 Docker，来自 gear_sonic_deploy/）：

bash deploy.sh sim

        启动控制：

1. 在终端 2（deploy.sh）中，按 ] 键启动策略。
2. 点击 MuJoCo 查看器窗口，按 9 键将机器人降落至地面。
3. 返回终端 2。按 T 键播放当前参考动作——机器人将执行该动作直至完成。
4. 按 N 或 P 切换到下一或上一动作序列。
5. 再次按 T 播放新动作。
6. 动作结束后，您可以再次按 T 重播同一动作。若需停止并返回当前动作的第一帧，请按 R 从头开始重启。此操作可在不终止策略的情况下停止动作。
7. 操作完成或需要紧急停止时，按 O 键停止控制并退出。

3.3 Real Robot

        要在真实的 G1 机器人上部署，请运行：

./deploy.sh real

3.4 在线可视化

        启动可视化工具，并连接到正在运行的 g1_deploy 可执行文件：

python visualize_motion.py --realtime_debug_url tcp://localhost:5557

        注：

• 默认端口：5557（可通过 --zmq-out-port <port> 进行修改）
• 默认主题：g1_debug（可在可执行文件中使用 --zmq-out-topic <topic> 进行修改，在可视化工具中使用 --realtime_debug_topic <topic> 进行修改）
• 对于实体机器人，请将 localhost 替换为机器人的 IP 地址

        有关离线运动 CSV 可视化和日志记录的详细信息，请参阅《部署代码与程序流程》。

四、VR 遥操作设置（PICO）

本页面介绍 PICO VR 全身遥操作的一次性软硬件设置。完成这些步骤后，请继续阅读 ZMQ Manager 教程，以在模拟环境或真实硬件上运行遥操作。

4.1 所需硬件

• PICO 4 / PICO 4 Pro 头显
• 2 个 PICO 控制器
• 2个PICO动作追踪器（绑在脚踝上）
• 高速、低延迟的Wi-Fi连接；遥操作性能在很大程度上取决于网络质量。

4.2 安装XRoboToolkit

        XRoboToolkit由PC服务（在您的工作站上运行）和PICO应用程序（在头显上运行）组成，用于传输身体追踪数据。

4.2.1 PC 服务

1. 访问 XR-Robotics。
2. 按照“安装 XRoboToolkit-PC-Service”的说明，在您的工作站上安装 PC 服务。
3. 若在设备上运行，请执行

   sudo dpkg -i gear_sonic_deploy/thirdparty/roboticsservice_1.0.0.0_arm64.deb

4.2.2 PICO 应用程序

1. 佩戴 PICO 头显以开始设置和安装流程。
2. 在 PICO 上完成快速设置。
3. 确保 PICO 已连接至 Wi-Fi。
4. 在 PICO 上打开浏览器应用。
5. 在搜索栏中输入“xrobotoolkit”，并选择 GitHub 页面 XR-Robotics。
6. 请确保已启用开发者模式（设置 → 开发者）。
7. [PICO 内部] 在 GitHub 页面向下滚动，直到看到 APK 下载选项，然后点击 PICO 扳机进行下载。

4.3 运动追踪器设置

1. 将一个 PICO 动作追踪器绑在左脚踝上，另一个绑在右脚踝上。将宽松的衣物卷起，确保追踪器可见。请确保带有指示灯的一面朝上。
2. 进入 PICO 设置。在左侧菜单中，向下滚动至最后一个选项：“开发者”。确保“安全防护”已关闭。
   1. 如果“开发者”选项未显示，请点击“软件”直至其出现。
3. 点击PICO菜单中的Wi-Fi图标。此时将显示头显的图片。头显上方会有一个代表运动追踪器的圆形小图标。如果没有该图标，请直接打开“运动追踪器”应用。
   1. 头显和2个控制器将显示出来——请选择“运动追踪器”（小圆圈）。
4. 每个追踪器旁边都有一个“i”图标。点击该图标并解除所有追踪器的配对。
5. 清除所有追踪器后，点击右上角的“配对”按钮。
6. 按住每个运动追踪器顶部的按钮 6 秒钟。进入配对模式后，指示灯将交替闪烁红蓝两色。

4.3.1 动作追踪器校准

1. 将 PICO 头显戴在头上。
2. 按下蓝色的“校准”按钮，并按照以下两个校准步骤操作：
   1. 保持身体笔直站立，手持控制器自然垂于身体两侧。
   2. 低头注视脚部动作追踪器，直到头显摄像头识别到它们。
3. 校准完成后，将 PICO 头显戴在额头上（确保 PICO 朝前，以便继续检测动作追踪器）。

4.4 安装 PICO 遥控环境

        在仓库根目录下：

bash install_scripts/install_pico.sh

        这将创建一个名为 .venv_teleop 的虚拟环境（Python 3.10），其中包含：

• teleop 扩展（ZMQ、Pinocchio、PyVista）
• sim 扩展（MuJoCo、tyro）
• XRoboToolkit SDK
• Unitree SDK2 Python 绑定

        使用以下命令激活它：

source .venv_teleop/bin/activate   # prompt: (gear_sonic_teleop)

4.5 将 PICO 连接到您的工作站

1. 在笔记本电脑/台式机和 PICO 上分别打开 Wi-Fi 设置，并确保它们连接到同一个 Wi-Fi 网络。记下 Wi-Fi 的 IPv4 地址。
   1. 要查找 PICO 的 Wi-Fi，请选择菜单右下角的控制中心。
2. 打开 XRoboToolKit 应用程序。点击“PC Service:”旁边的“Enter”，输入笔记本电脑的 IP 地址。如果“Status:”旁边显示“WORKING”，则表示已成功连接。
   1. 如果您的 IP 地址已输入，请在“Network”部分的“Status:”处选择“Reconnect”。
3. 请确保勾选下图所示的以下选项：
   1. “跟踪”部分下的“头部”和“控制器”。
   2. 在“数据/控制”选项中，请务必选择“发送”按钮。
   3. 对于“Pico 动作追踪器”，请务必选择“全身”。