# 宇树 G1 基于 MuJoCo 仿真与 SDK 接口预研实践

> 原文链接：https://robotics.hellobike.com/wiki/g1-mujoco-sim-notes
> 频道：wiki | 更新日期：2026-10-10 | 标签：G1, MuJoCo, 仿真, 动力学, SDK, 双足平衡
> 核心摘要：记录使用 MuJoCo 物理引擎对宇树 G1 进行 29 DoF 动力学建模与姿态控制仿真的验证结果，并梳理 Loco、Arm、Audio 等 SDK 接口形状。

# 宇树 G1 基于 MuJoCo 仿真与 SDK 接口预研实践

> 本文为宇树 G1 EDU 真机实操记录，固件/SDK 版本以文中标注为准。

## 1. 物理仿真验证环境与结论

在缺乏硬件实体或进行早期算法探索时，通过物理仿真可以验证运动规划轨迹在机器人动力学约束下的稳定裕度。

### 1.1 仿真环境搭建

- **物理仿真引擎**：MuJoCo 3.x
- **机型模型资产**：DeepMind `mujoco_menagerie` 中的 `unitree_g1` 官方资产
- **模型特征**：
  - 29 个可控自由度（DoF）；
  - 关节作动器配置位置控制器（`kp = 500`, `dampratio = 1`）；
  - 默认加载标准站立关键帧（`stand`），标称骨盆高度为 `0.79m`。

### 1.2 双足站立与手臂协同回放实验

实验目标：验证在保持下半身双足直立锁定的状态下，上半身执行小幅度肢体动作是否会破坏整机平衡。
- **动作设计**：右臂执行平滑起止的正弦波挥手轨迹（肩部 roll 轴抬臂 + 肘关节 1Hz 摆动，结合 smoothstep 起止曲线），持续执行 8 秒。
- **实验表现**：骨盆中心高度全程维持在 `0.790m`，未发生明显下沉、颤震或失稳倾覆。
- **工程结论**：在受控场景下，“上半身预制轨迹回放 + 下半身刚性姿态锁定”在物理仿真层面具备可行性，可用于制作动作素材。

## 2. 官方 SDK 接口结构剖析

结合 `unitree_sdk2py` 源码与通信协议分析，G1 提供的上层控制客户端主要涵盖运动、手臂动作、音频与状态遥测四部分：

### 2.1 高层运动控制：LocoClient

服务常量对应 `LOCO_SERVICE_NAME = "sport"`，核心方法包括：
- **姿态管理**：`Squat2StandUp()`（起立）、`Sit()`（坐下）、`HighStand()`、`BalanceStand(mode)`。
- **位移与速度控制**：`Move(vx, vy, vyaw, continuous_move)`、`SetVelocity(vx, vy, omega, duration)`、`StopMove()`。
- **状态机与急停**：`SetFsmId(id)`、`Damp()`（阻尼急停模式）。

### 2.2 手臂动作编排：G1ArmActionClient

提供 `ExecuteAction(action_id)` 与 `GetActionList()`，机载固件内置了动作映射表（预设肢体动作 ID）：
- 释放与待机：`release arm` (ID 99)
- 迎宾交互：`face wave` (ID 25)、`high wave` (ID 26)、`hands up` (ID 15)
- 表演互动：`clap` (ID 17)、`heart` (ID 20/21)
- 接触类动作：`hug` (ID 19)、`shake hand` (ID 27)

在实际工程落地中，涉及肢体接触的动作需要严密的距离围栏与防夹安全策略。

### 2.3 音频与播报：AudioClient

- **机载 TTS 合成**：`TtsMaker(text, speaker_id)`，下发文本由机载语音引擎实时朗读。
- **PCM 流式推流**：`PlayStream(app_name, stream_id, pcm_data)`，支持将预处理并审核后的 PCM 音频数据直接推送到机载扬声器播放，提供更一致的语音质感。
- **状态管理**：`PlayStop(app_name)`、`SetVolume(volume)`、`LedControl(R, G, B)`。

### 2.4 底盘遥测与 DDS 初始化

底层遥测消息通过 CycloneDDS 话题分发，定义于 `unitree_hg.msg.dds_`：
- `LowState`、`IMUState`、`BmsState`（电池电量与状态）、`MotorState` 等。
- 通信初始化需通过 `ChannelFactoryInitialize(domain_id, network_interface)` 指定绑定的有线网卡名称，控制工作站需与机器人计算单元处于同一二层网络中。

## 3. 运行环境与跨平台注意事项

1. **依赖兼容性**：`unitree_sdk2py` 依赖底层 CycloneDDS C 语言动态库。macOS 环境缺乏预编译的 aarch64/x86_64 wheel，直接通过 pip 安装通常会在编译阶段阻断；真机调试与生产运行建议统一运行于 Ubuntu Linux 环境。
2. **无头（Headless）仿真**：在无图形界面的服务器或持续集成沙箱中执行 MuJoCo 仿真时，如果调用窗口渲染可能产生 OpenGL 上下文错误，但纯物理模拟、刚体运动学和动力学矩阵解算仍可无头正常运行。

## 原始参考来源 (Sources)

- [MuJoCo Menagerie Unitree G1 Model](https://github.com/google-deepmind/mujoco)
- [unitree_sdk2_python](https://github.com/unitreerobotics/unitree_sdk2_python)