feat: Full LeRobot G1 integration via EnvHub (with DDS/SDK layer)

[MiaoDX]

Context

LeRobot's Unitree G1 MuJoCo environment uses a digital twin architecture — even in pure simulation, it communicates via DDS (Data Distribution Service) through unitree_sdk2py. This is by design: controllers written for the real robot work identically in sim.

In #65 we validated the wrapper with a simplified model. The sibling issue covers loading the real 29-DOF model without SDK. This issue tracks full, native LeRobot integration.

The challenge: SDK dependency chain

lerobot/unitree-g1-mujoco (HuggingFace repo)
  └── unitree_sdk2py >= 1.0.0
       └── cyclonedds == 0.10.2  ← hard-pinned, binary wheel availability varies

Key constraints discovered in #65 investigation:

1. unitree_sdk2py claims python_requires='>=3.8', but cyclonedds==0.10.2 may lack wheels for newer Python versions
2. LeRobot main repo requires python >= 3.12, yet commented out the SDK from [unitree_g1] extras: # "unitree-sdk2==1.0.1"
3. LeRobot main code (src/lerobot/robots/unitree_g1/unitree_g1.py) already has conditional imports for the SDK, but the HuggingFace sim repo does unconditional module-level imports throughout simulator_factory.py, base_sim.py, unitree_sdk2py_bridge.py
4. The sim uses DDS on loopback (INTERFACE: "lo") — ChannelFactoryInitialize(DOMAIN_ID, "lo") — even in pure simulation

Proposal

Full integration with the native LeRobot G1 environment:

1. Use lerobot.envs.factory.make_env() to create the env the official way:

   from lerobot.envs.factory import make_env
   env = make_env("lerobot/unitree-g1-mujoco", trust_remote_code=True)

2. Wrap with RobotHarnessWrapper — the returned UnitreeG1Env inherits from gym.Env
3. Document the full dependency setup (conda env, SDK install, Python version)
4. Handle the SDK availability gracefully in the example

Known blockers to investigate

• Does cyclonedds==0.10.2 install on Python 3.11/3.12/3.13? (Our CI tests 3.10-3.13)
• Can the HuggingFace sim repo be patched to make SDK optional (contribute upstream)?
• Does make_env() return an env with render_camera() or only render()?
• Is there a camera configuration for multi-view in the G1 sim config?

Acceptance criteria

• examples/lerobot_g1_native.py using make_env() from LeRobot
• Full dependency documentation (install steps, Python version requirements)
• Works on at least one Python version in CI (likely 3.10 or 3.12)
• Multi-view checkpoint capture if the env supports it
• Graceful error if SDK/LeRobot not installed
• OR: documented list of incompatibilities with upstream fix suggestions

Relationship to other issues

• Follow-up to feat: Validate RobotHarnessWrapper on LeRobot G1 MuJoCo simulation #65 (simplified validation — completed)
• Sibling: SDK-free approach (load real model from HuggingFace, bypass DDS)
• May require upstream contributions to lerobot/unitree-g1-mujoco (conditional SDK imports)

[MiaoDX]

SDK 兼容性：已有的社区方案

Upstream PR: unitreerobotics/unitree_sdk2_python#107

carlosdp 的 PR 做了三件关键改进：

1. fastcrc 替换自定义 CRC — 跨平台兼容（包括 macOS），源码可审计
2. 添加 __init__.py — 使模块成为标准 Python 包，兼容标准包管理工具
3. 预编译 cyclonedds (v0.10.5) — 无需本地编译，pip install 一行搞定

该 PR 已验证兼容 uv 包管理器。

我们的 Fork: MiaoDX-fork-and-pruning/unitree_sdk2_python_uv

基于上述 PR 的方向，维护了一个 fork，目标是：

• 迁移到 uv managed 项目结构（现代 Python 包管理）
• 支持 Python 3.10+（解决 cyclonedds==0.10.2 的版本钉死问题）
• 更干净的提交历史

背景：官方 unitree_sdk2_python 硬钉 cyclonedds==0.10.2，该版本在新 Python 上可能没有 binary wheel。上游 PR #107 升级到预编译的 v0.10.5，但尚未合入。我们的 fork 在实际项目中已有使用经验。

建议的行动路径

1. 在 fork 上完成 uv 迁移 + Python 3.10+ 全版本支持
2. 验证 cyclonedds 预编译 wheel 在 3.10–3.13 上的可用性
3. 用我们的 fork 作为 unitree_sdk2py 的安装源来测试完整 LeRobot G1 集成
4. 如验证可行，向 upstream 提交更干净的 PR

---

Generated by Claude Code

[MiaoDX]

https://github.com/MiaoDX-fork-and-pruning/unitree_sdk2_python_uv for easier sdk integration via uv.

[MiaoDX]

新发现：LeRobot 已封装轻量 WBC 控制器，无需 GR00T 大仓库

LeRobot 的做法

LeRobot 在 src/lerobot/robots/unitree_g1/gr00t_locomotion.py 里做了自己的轻量封装，完全绕过了 NVlabs GR00T-WholeBodyControl 仓库（1GB+ with LFS）：

# 直接从 HuggingFace 下载预训练 ONNX，不 clone 任何仓库
DEFAULT_GROOT_REPO_ID = "nepyope/GR00T-WholeBodyControl_g1"
balance_path = hf_hub_download(repo_id=repo_id, filename="GR00T-WholeBodyControl-Balance.onnx")
walk_path = hf_hub_download(repo_id=repo_id, filename="GR00T-WholeBodyControl-Walk.onnx")

运行时依赖仅需：onnxruntime + huggingface_hub + numpy（共 ~几十 MB pip install）
ONNX 模型：两个文件 ~几 MB，从 HuggingFace 自动下载缓存
Python 版本：LeRobot G1 文档推荐 Python 3.12（不是 3.10！）

另一个选择：Holosoma 控制器

LeRobot 还提供了 HolosomaLocomotionController（来自 amazon-far/holosoma），同样是 ONNX + onnxruntime，200Hz PPO/FastSAC。用法：--robot.controller=HolosomaLocomotionController

对我们的启示

我们不需要 DDS/SDK 也能让 G1 站起来。可以：

1. 参考 LeRobot 的 gr00t_locomotion.py，提取出纯 ONNX 推理逻辑
2. 下载 Balance + Walk ONNX 模型
3. 在 examples/lerobot_g1.py 里直接用 onnxruntime 推理，把关节目标写入 MuJoCo data.ctrl
4. 不需要 DDS，不需要 unitree_sdk2py，不需要 cyclonedds

新的验收条件建议

在现有条件基础上增加：

• 集成 GR00T Balance ONNX 策略让 G1 在 MuJoCo 中站立
• 可选依赖 onnxruntime（加入 [lerobot] optional deps）
• CI 中验证 G1 站立（torso height > 0.5m 持续 1000 步）

关键文件参考

LeRobot 文件	用途
src/lerobot/robots/unitree_g1/gr00t_locomotion.py	GR00T 双策略（Balance+Walk）ONNX 控制器
src/lerobot/robots/unitree_g1/holosoma_locomotion.py	Holosoma ONNX 控制器
src/lerobot/robots/unitree_g1/g1_utils.py	工厂 make_locomotion_controller()、关节枚举

HuggingFace ONNX 模型：nepyope/GR00T-WholeBodyControl_g1

---

Generated by Claude Code

[MiaoDX]

如果直接用 LeRobot 作为依赖

最简路径：pip install lerobot[unitree_g1]，然后直接用它的控制器：

from lerobot.robots.unitree_g1.gr00t_locomotion import GrootLocomotionController
from lerobot.robots.unitree_g1.g1_utils import make_locomotion_controller

# 或者用 Holosoma
controller = make_locomotion_controller("HolosomaLocomotionController")

好处：零代码，开箱即用，跟随 LeRobot 上游更新
坏处：绑定 LeRobot 的 DDS 通信架构（控制器通过 publish_lowcmd() 发指令），不能直接写 MuJoCo data.ctrl；且引入 unitree_sdk2py / cyclonedds 依赖链

等 #74 的 SDK 问题解决后，这条路是最终方案。

---

当前选择：自己实现轻量 ONNX 推理

先自己写 ONNX 推理封装（参考 LeRobot 的 gr00t_locomotion.py），直接控制 MuJoCo，不走 DDS。好处：

1. 不受 LeRobot 限制 — 不需要 SDK/DDS/cyclonedds
2. 可以同时支持多个 WBC — GR00T (Balance+Walk) 和 Holosoma (PPO/FastSAC) 作为可选控制器
3. 符合我们的 Controller Protocol — compute(command, state) -> action
4. 之后可删 — 等 feat: Full LeRobot G1 integration via EnvHub (with DDS/SDK layer) #74 完成后切换到直接用 LeRobot 的实现

依赖只需加 onnxruntime 到 [lerobot] optional deps。

---

Generated by Claude Code