From 71c2adb050bcabab68c73bf1f2c8d12feb2a14f8 Mon Sep 17 00:00:00 2001 From: daifawo Date: Thu, 22 Oct 2026 17:00:46 +0800 Subject: [PATCH] docs(go2): add sim2sim and sim2real deployment guide --- docs/source/_static/videos/go2_sim2real.mp4 | 3 + .../_static/videos/go2_sim2real_h264.mp4 | 3 + docs/source/_static/videos/go2_sim2sim.mp4 | 3 + .../envs/quadruped_velocity_tracking.md | 1 + .../go2_flat_sim2real.md | 137 +++++++++++++++++ .../envs/quadruped_velocity_tracking.md | 1 + .../go2_flat_sim2real.md | 145 ++++++++++++++++++ 7 files changed, 293 insertions(+) create mode 100644 docs/source/_static/videos/go2_sim2real.mp4 create mode 100644 docs/source/_static/videos/go2_sim2real_h264.mp4 create mode 100644 docs/source/_static/videos/go2_sim2sim.mp4 create mode 100644 docs/source/en/user_guide/envs/quadruped_velocity_tracking/go2_flat_sim2real.md create mode 100644 docs/source/zh_CN/user_guide/envs/quadruped_velocity_tracking/go2_flat_sim2real.md diff --git a/docs/source/_static/videos/go2_sim2real.mp4 b/docs/source/_static/videos/go2_sim2real.mp4 new file mode 100644 index 00000000..35d55eb5 --- /dev/null +++ b/docs/source/_static/videos/go2_sim2real.mp4 @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:730620ee7b682aff4b763f7f6bbed45565fca0fc9d274c9e294ff8e35e6298b2 +size 2100189 diff --git a/docs/source/_static/videos/go2_sim2real_h264.mp4 b/docs/source/_static/videos/go2_sim2real_h264.mp4 new file mode 100644 index 00000000..ad851e67 --- /dev/null +++ b/docs/source/_static/videos/go2_sim2real_h264.mp4 @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:6eb584e79bcc72b455af94a4c0ed260b041f1f407a7612305625187c28375858 +size 4422316 diff --git a/docs/source/_static/videos/go2_sim2sim.mp4 b/docs/source/_static/videos/go2_sim2sim.mp4 new file mode 100644 index 00000000..edd3f3c5 --- /dev/null +++ b/docs/source/_static/videos/go2_sim2sim.mp4 @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:9969b4dd31e4245604b7743e1b00a03a69963f87babefbb2483177e13cde6411 +size 990750 diff --git a/docs/source/en/user_guide/envs/quadruped_velocity_tracking.md b/docs/source/en/user_guide/envs/quadruped_velocity_tracking.md index ef8c7af7..41af007f 100644 --- a/docs/source/en/user_guide/envs/quadruped_velocity_tracking.md +++ b/docs/source/en/user_guide/envs/quadruped_velocity_tracking.md @@ -64,6 +64,7 @@ The following videos replay the `rslrl.ppo` policies for Go1, Go2, and ANYmal-C. quadruped_velocity_tracking/adding_robot quadruped_velocity_tracking/env_design quadruped_velocity_tracking/config_tuning +quadruped_velocity_tracking/go2_flat_sim2real ``` diff --git a/docs/source/en/user_guide/envs/quadruped_velocity_tracking/go2_flat_sim2real.md b/docs/source/en/user_guide/envs/quadruped_velocity_tracking/go2_flat_sim2real.md new file mode 100644 index 00000000..3ba55177 --- /dev/null +++ b/docs/source/en/user_guide/envs/quadruped_velocity_tracking/go2_flat_sim2real.md @@ -0,0 +1,137 @@ +# Go2 flat-ground walking: sim2sim and sim2real + +This page describes the complete path from a `go2-walk-flat` training policy to deployment: export an artifact, check it in MuJoCo or MotrixSim, and then run it on the real robot through the Unitree SDK2 DDS backend. The artifact keeps the policy, joint order, default pose, action scaling, and control period together; passing simulation does not guarantee hardware safety. + +## 1. Train the policy + +```bash +source .venv/bin/activate +mxlab train task=go2-walk-flat/rslrl.ppo +``` + +Training outputs are stored under `runs/go2-walk-flat/`, and the trained gait should be replayed with `mxlab play` for inspection. + +## 2. Export and inspect the artifact + +```bash +mxlab export-deploy env=go2-walk-flat output=artifacts/go2-walk-flat.deploy +mxlab deploy inspect artifact=artifacts/go2-walk-flat.deploy +``` + +To pin a specific experiment, use `run_dir=/path/to/run` instead of `env`; exactly one may be set. Inspection must report `valid: true`. The artifact is self-contained: + +```text +go2-walk-flat.deploy/ +├── manifest.json # robot, control, task settings, and payload checksums +├── policy/model.onnx # exported actor with input normalization +└── task/ # task-owned payloads (for example, a G1 motion NPZ) +``` + +Deployment also requires the `motrix_deploy_tasks` plugin, which provides the walking task implementation, deployment scene, and Hydra recipe, together with the runtime plugin for the selected target. The recipe is installed with the plugin and does not require a workspace configuration path when run outside the repository. Task defaults compose the typed runtime configuration, so no separate runtime group override is needed. Common top-level settings are `artifact` and `duration_s`. Runtime settings live under `runtime`; Unitree robot options live under `runtime.robot`, while transport settings such as `runtime.network_interface` remain directly under `runtime`. The configuration distinguishes simulation and hardware execution; `runtime.backend` selects `mujoco` or `motrixsim` for simulation and `unitree` for hardware. It is a scalar string selector, not a nested configuration mapping or Hydra config group. + +## 3. sim2sim: MuJoCo + +Headless bounded run: + +```bash +mxlab deploy task=go2-walk-flat/sim \ + artifact=artifacts/go2-walk-flat.deploy \ + runtime.viewer=false duration_s=2.0 +``` + +For interactive viewing, omit `runtime.viewer=false` to use the MuJoCo viewer: + +```bash +mxlab deploy task=go2-walk-flat/sim \ + artifact=artifacts/go2-walk-flat.deploy +``` + +In the viewer, use `W/S` for forward/backward motion, `A/D` for lateral motion, and `Q/E` for yaw; press Esc or Ctrl-C to exit. + +```{video} /_static/videos/go2_sim2sim.mp4 +:nocontrols: +:autoplay: +:playsinline: +:muted: +:loop: +:width: 60% +:align: center +``` + +To select native MotrixSim, install `motrix-deploy-motrixsim` and reuse the same artifact: + +```bash +mxlab deploy task=go2-walk-flat/sim \ + artifact=artifacts/go2-walk-flat.deploy \ + runtime.backend=motrixsim runtime.viewer=true +``` + +Use `task=go2-walk-rough/sim` to select the packaged rough-terrain scene. Changing the scene does not mean that a flat-ground policy is suitable for rough terrain; confirm policy applicability before testing. + +Velocity tracking in simulation also does not equal hardware tracking. Simulation may randomize action delay, friction, mass, center of mass, observation noise, and other factors. A policy that walks in simulation is not necessarily stable on the real robot. Go2 simulation training and the artifact use approximately `kp=35, kd=0.5` by default, while the hardware recipe overrides these to `kp=50, kd=1`; this is one clear difference between sim2sim and sim2real. + +## 4. Hardware deployment: Unitree Go2 sim2real + +Before starting, prepare reliable load-bearing supports, sufficient clearance for all legs, an independent emergency stop that the operator can reach, and a second operator. Stop all other low-level command publishers. Damping and deployment shutdown do not provide standing support; do not continue without a supported recovery plan. Before hardware execution, suspend the Go2 and switch it to low-level/debug mode. + +Find the wired network interface and replace `enp5s0` in the commands below with the actual interface: + +```bash +ip -br addr +``` + +Connect the PC and Go2 with an Ethernet cable and verify that they can communicate. Set the PC Ethernet address on the same subnet as the robot, for example: + +```text +PC address: 192.168.123.100 +Go2 address: 192.168.123.161 +``` + +Test the connection to the Go2 onboard computer: + +```bash +ping 192.168.123.161 +``` + +### Read-only state check + +This diagnostic does not create a command publisher. Replace `enp5s0` with the actual interface: + +```bash +motrix-deploy-unitree read-lowstate enp5s0 +``` + +Check that valid state messages continue to arrive and that there are no CRC or decoding errors. The tool does not send motor commands or take official control. While official control remains active, remote buttons may also trigger official actions; do not treat button checks as side-effect-free operations. + +### Bounded single-joint check + +This test does not require an artifact or policy, but the whole body first transitions to a hold pose. Therefore all 12 joints may move even with `--offset 0`. Prepare supports and clearance, and use gains verified for the current robot and support arrangement, such as `kp=50` and `kd=1`. + +```bash +motrix-deploy-unitree joint-control enp5s0 FL_thigh_joint 0.9 \ + --artifact artifacts/go2-walk-flat.deploy +``` + +`Start` begins the hold-pose transition and `A` starts the selected joint test. `B` returns to the hold pose and then stops; before the test starts or while the startup transition is still running, `B` cancels and applies damping directly. + +### Full hardware run + +Keep `kp=50` and `kd=1` for the first run; do not increase gains before the suspended check. To reduce the fall risk from a DDS disconnect, press `L2+A` twice first to request lie-down. Replace `enp5s0` with the actual interface: + +```bash +mxlab deploy task=go2-walk-flat/hardware \ + artifact=artifacts/go2-walk-flat.deploy \ + runtime.network_interface=enp5s0 +``` + +Press `Start`, wait for the pose transition to finish, then press `A` to enable the policy. Hold `L1` while moving the stick to send commands. `B` requests lie-down and `Select` triggers the emergency stop. Send damping before closing DDS. + +```{video} /_static/videos/go2_sim2real_h264.mp4 +:nocontrols: +:autoplay: +:playsinline: +:muted: +:loop: +:width: 50% +:align: center +``` diff --git a/docs/source/zh_CN/user_guide/envs/quadruped_velocity_tracking.md b/docs/source/zh_CN/user_guide/envs/quadruped_velocity_tracking.md index 5c51b4a9..728dcab9 100644 --- a/docs/source/zh_CN/user_guide/envs/quadruped_velocity_tracking.md +++ b/docs/source/zh_CN/user_guide/envs/quadruped_velocity_tracking.md @@ -63,6 +63,7 @@ quadruped_velocity_tracking/adding_robot quadruped_velocity_tracking/env_design quadruped_velocity_tracking/config_tuning +quadruped_velocity_tracking/go2_flat_sim2real ``` diff --git a/docs/source/zh_CN/user_guide/envs/quadruped_velocity_tracking/go2_flat_sim2real.md b/docs/source/zh_CN/user_guide/envs/quadruped_velocity_tracking/go2_flat_sim2real.md new file mode 100644 index 00000000..f56fefcd --- /dev/null +++ b/docs/source/zh_CN/user_guide/envs/quadruped_velocity_tracking/go2_flat_sim2real.md @@ -0,0 +1,145 @@ +# Go2 平地步行：sim2sim 与 sim2real + +本页描述 `go2-walk-flat` 从训练策略到部署的完整路径：导出 artifact，在 MuJoCo 或 MotrixSim 中检查，再通过 Unitree SDK2 DDS 运行真机。 +artifact 统一保存策略、关节顺序、默认姿态、动作缩放和控制周期；仿真通过不代表真机安全。 + +## 1. 训练策略 + +```bash +source .venv/bin/activate +mxlab train task=go2-walk-flat/rslrl.ppo +``` + +训练结果位于 `runs/go2-walk-flat/`，训练后的步态需要通过 `mxlab play` 回放策略查看。 + +## 2. 导出并检查 artifact + +```bash +mxlab export-deploy env=go2-walk-flat output=artifacts/go2-walk-flat.deploy +mxlab deploy inspect artifact=artifacts/go2-walk-flat.deploy +``` + +固定某次实验时用 `run_dir=/path/to/run` 替代 `env`，二者只能设置一个。检查输出必须为 `valid: true`。 +artifact 目录自包含： + +```text +go2-walk-flat.deploy/ +├── manifest.json # 机器人/控制/任务设置与 payload 校验和 +├── policy/model.onnx # 导出的 actor（含输入归一化） +└── task/ # 任务自有 payload（例如 G1 的 motion NPZ） +``` + +部署还需要安装 `motrix_deploy_tasks` 插件，提供行走任务实现、 +部署场景和 Hydra 配方，以及目标对应的运行时插件。配方安装在插件中，在仓库外运行也不需要 workspace 配置路径。 +任务 defaults 组合类型化运行时配置，无需另行覆盖运行时组。 +顶层公共设置为 `artifact` 和 `duration_s`。运行时设置位于 `runtime` 下；Unitree 机器人专用选项 +位于 `runtime.robot` 下，而 `runtime.network_interface` 等传输设置仍直接位于 `runtime` 下。 +配置类型区分仿真与硬件执行路径；`runtime.backend` 选择插件（仿真为 `mujoco` 或 `motrixsim`，硬件为 `unitree`）。 +`runtime.backend` 是标量字符串选择器，不是嵌套配置映射或 Hydra 配置组。 + +## 3. sim2sim：MuJoCo + +无窗口短跑： + +```bash +mxlab deploy task=go2-walk-flat/sim \ + artifact=artifacts/go2-walk-flat.deploy \ + runtime.viewer=false duration_s=2.0 +``` + +有窗口交互：查看时省略 `runtime.viewer=false`，默认使用MuJoco viewer。 + +```bash +mxlab deploy task=go2-walk-flat/sim \ + artifact=artifacts/go2-walk-flat.deploy +``` + +若要选择原生的MotrixSim，安装 `motrix-deploy-motrixsim` 后可复用同一 artifact： + +```bash +mxlab deploy task=go2-walk-flat/sim \ + artifact=artifacts/go2-walk-flat.deploy \ + runtime.backend=motrixsim +``` +窗口中 `W/S` 前后移动、`A/D` 横移、`Q/E` 转向，Esc 或 Ctrl-C 退出。 + +```{video} /_static/videos/go2_sim2sim.mp4 +:nocontrols: +:autoplay: +:playsinline: +:muted: +:loop: +:width: 60% +:align: center +``` + +使用 `task=go2-walk-rough/sim` 可选择随包提供的粗糙地形场景。更换场景不代表平地策略适合粗糙地形，测试前需确认策略适用范围。 + +同时仿真中的速度跟踪并不等于真机跟踪，仿真中还涉及动作延迟、摩擦、质量、质心、观测噪声等随机化。即使 sim 中能走，也不能直接说明真机一定稳定。 +Go2 的仿真训练和 artifact 默认增益约为 `kp=35, kd=0.5`，而真机配方覆盖成了 `kp=50, kd=1`，这也是 sim2sim 到 sim2real 的一个明显差异。 + +## 4. 真机部署sim2real：Unitree Go2 + +事前准备：准备可靠承重支撑、所有腿的活动空间、操作员就绪的独立急停，以及另一名操作人员。停止其他所有低层指令发布程序。 +阻尼和部署停止都不能维持站立支撑；没有受支撑的恢复方案时不要继续。 +真机前将 Go2 悬空，切换低层/调试模式，准备独立急停和现场操作员。 + +查找连接机器人的有线网卡，把后续指令的`enp5s0` 换成实际网卡： + +```bash +ip -br addr +``` +将PC与Go2通过网线连接后，需要观察是否能够ping通，需将电脑 Ethernet 地址设置为与机器狗同一网段，如： + +```text +PC 地址：192.168.123.100 +Go2 地址：192.168.123.161 +``` +为了测试用户电脑与Go2机器人内置电脑是否正常连接，可在终端中输入: + +```bash +ping 192.168.123.161 +``` + +### 只读状态检查： + +只读诊断不创建指令 publisher，把 `enp5s0` 换成实际网卡。： +```bash +motrix-deploy-unitree read-lowstate enp5s0 +``` +检查是否持续收到有效状态，以及是否有 CRC 或解码错误。该工具不发送电机指令，也不释放官方控制权。 +官方控制仍活动时，遥控器按键可能同时触发官方动作，不要将按键检查视为无副作用操作。 + +### 有界单关节检查： + +此测试不需要 artifact 或策略，但会先让全身过渡到保持姿态，因此即使 `--offset 0`，全部 12 个关节仍可能运动。 +必须准备支撑和活动空间，并使用已针对当前机器人和支撑方式核验的增益，如 `kp=50`、`kd=1`。 + +```bash +motrix-deploy-unitree joint-control enp5s0 FL_thigh_joint 0.9 \ + --artifact artifacts/go2-walk-flat.deploy +``` +`Start` 开始保持姿态过渡，`A` 开始所选关节测试。`B` 返回保持姿态后停止；尚未开始或仍在启动过渡时，`B` 直接取消并阻尼。 + +### 正式真机运行： + +首次运行保持 `kp=50`、`kd=1`，不要在悬空检查前提高增益。为了防止DDS断联Go2摔落，可先按两次L2+A，让机器人趴下，`enp5s0` 换成实际网卡，运行： + +```bash +mxlab deploy task=go2-walk-flat/hardware \ + artifact=artifacts/go2-walk-flat.deploy \ + runtime.network_interface=enp5s0 +``` + +按 `Start`，等待姿态过渡完成后按 `A` 接管策略；按住 `L1` 并移动摇杆发送指令。 +`B` 请求趴下，`Select` 急停。结束时先发送阻尼，再关闭 DDS。 + +```{video} /_static/videos/go2_sim2real_h264.mp4 +:nocontrols: +:autoplay: +:playsinline: +:muted: +:loop: +:width: 50% +:align: center +```