Feat/g1 native deploy

[MrH-creater]

G1 29-DOF Deployment Guide / 部署操作手册

Expand your preferred language below. / 请展开所需语言。

中文 — sim2sim / sim2real 部署操作手册

适用：MotrixLab 0.4.0，分支 feat/g1-native-deploy。

以下使用已经准备好的代码及两份 artifact，不包含大文件下载步骤。sim2sim 使用开发机现有环境；sim2real 包含机器人首次配置环境的步骤。仓库内命令均从仓库根目录执行，默认策略路径为 artifacts/g1-flat.deploy 和 artifacts/g1-wbt-dance.deploy。

1. sim2sim：开发机运行

进入本地仓库，激活已安装 mxlab 的环境。例如使用现有的 motrix-lab 环境：

cd ~/MotrixLab
conda activate motrix-lab
mxlab deploy deploy=g1-sim

如果使用仓库内的 .venv，将激活环境的命令换成 source .venv/bin/activate。

需要指定策略路径时：

mxlab deploy deploy=g1-sim \
  program.walk_artifact=/home/user/MotrixLab/artifacts/g1-flat.deploy \
  program.wbt_artifact=/home/user/MotrixLab/artifacts/g1-wbt-dance.deploy

仿真窗口获得焦点后，使用以下按键：

操作	按键
FixStand	1
Walk	2
从 Walk 启动 WBT	3
Passive	0 或 x
前后 / 横移 / 转向	W/S、A/D、Q/E

在终端按 Ctrl+C 结束运行。

2. sim2real：配置 DDS 并运行

登录并进入代码目录

在开发机上，将变量替换为机器人的实际 SSH 地址后登录：

ROBOT_HOST=REPLACE_WITH_ROBOT_SSH_ADDRESS
ssh "unitree@$ROBOT_HOST"

在机器人上进入代码目录；路径不同的，替换为实际位置：

cd ~/MotrixLab

首次配置机器人环境

已完成下列安装并通过验证的，可以直接跳到“以后每次运行”。真机部署所需的主要依赖如下，Python 包由后面的安装命令统一处理：

类别	必要依赖
系统	Ubuntu，aarch64 或 x86_64
Python	3.10；构建扩展还需要对应头文件，下面使用包含头文件的 uv 托管 Python
安装与编译工具	uv、git、支持 C++17 的编译器、CMake ≥ 3.18
C++ SDK	完整的 Unitree SDK2 头文件，以及与本机架构匹配的 SDK2、DDS 库
Python 部署依赖	numpy>=1.26、onnxruntime==1.23.2、pydantic==2.12.5、hydra-core、omegaconf、gymnasium 等，由仓库声明自动安装
Python SDK 依赖	仓库指定版本的 unitree-sdk2py，及其依赖 cyclonedds==0.10.2、opencv-python

真机控制配置使用 native_cpp。当前包依赖和下文的 DDS 只读检查仍需要 Python SDK，因此一并安装。机器人仅运行 sim2real 时，无需安装训练环境、Torch/CUDA 或仿真后端。

1）准备工具和 Python 3.10 环境

安装系统工具：

sudo apt update
sudo apt install -y build-essential git curl ca-certificates

若尚未安装 uv，执行：

curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"

仅在尚未创建 .venv 时，执行以下命令；已有可用的 Python 3.10 环境则直接激活：

uv python install 3.10
uv venv --managed-python --python 3.10 .venv

激活环境并安装编译工具：

source .venv/bin/activate
python --version
uv pip install "cmake>=3.18,<4" ninja
cmake --version

确认 Python 输出为 3.10.x。如果复用系统 Python 创建的环境，编译时提示缺少 Python.h，还需安装匹配的 python3.10-dev；上述 uv 托管环境不需要另装此包。

2）指定 Unitree C++ SDK2 路径

优先复用机器人上已经安装并验证过的 SDK2。例如已安装在 /usr/local：

export UNITREE_SDK2_ROOT=/usr/local
ls "$UNITREE_SDK2_ROOT/include/unitree/robot/channel/channel_factory.hpp"

将 /usr/local 替换为实际 SDK2 根目录。若尚未准备 SDK2，也可以取得完整 SDK2 目录后直接使用：

git clone --depth 1 https://github.com/unitreerobotics/unitree_sdk2.git "$HOME/unitree_sdk2"
export UNITREE_SDK2_ROOT="$HOME/unitree_sdk2"

使用 SDK2 源码目录时，须保留其中的 include、lib 和 thirdparty，并包含本机架构对应的库；无需构建 SDK 示例程序。

3）安装仓库部署包

在已激活的环境中，从仓库根目录执行：

uv pip install \
  -e ./motrix_env_core \
  -e ./motrix_robots \
  -e ./motrix_deploy \
  -e ./motrix_deploy_tasks \
  -e ./motrix_deploy_unitree \
  "unitree-sdk2py @ git+https://github.com/motphys-developers/unitree_sdk2_python@ff87e731174f7258e0d09980897c55116634939a"

uv pip install --no-deps -e ./motrixlab

这里的 Python SDK 使用仓库指定提交。motrixlab 的 --no-deps 用于安装 mxlab 命令入口，所需部署依赖已在上一条命令中安装。构建所需的 pybind11、scikit-build-core 等会在构建扩展时自动安装，无需逐个手动配置。

如果安装成功，继续下一步。如果提示 Could not locate cyclonedds，按下面的方法准备 CycloneDDS，然后重新执行本小节的安装命令；ARM 机器人尤其需要检查这一项。

缺少 CycloneDDS 时的处理方法

若已有 CycloneDDS 0.10.2 安装目录，直接将 CYCLONEDDS_HOME 指向该目录。否则构建并安装到用户目录：

git clone --depth 1 --branch 0.10.2 \
  https://github.com/eclipse-cyclonedds/cyclonedds.git "$HOME/cyclonedds-0.10.2"
cmake -S "$HOME/cyclonedds-0.10.2" -B "$HOME/cyclonedds-0.10.2/build" \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_INSTALL_PREFIX="$HOME/.local/cyclonedds-0.10.2" \
  -DCMAKE_INSTALL_LIBDIR=lib
cmake --build "$HOME/cyclonedds-0.10.2/build" --parallel 2
cmake --install "$HOME/cyclonedds-0.10.2/build"

export CYCLONEDDS_HOME="$HOME/.local/cyclonedds-0.10.2"
export LD_LIBRARY_PATH="$CYCLONEDDS_HOME/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"

使用已有安装时，将最后两条命令中的安装路径换成实际位置。采用此方法后，每次重新打开终端也应执行这两条 export。

4）构建 native 扩展并验证

保持 UNITREE_SDK2_ROOT 指向上面确认过的 SDK2 目录：

uv pip install -e ./motrix_unitree_native \
  -C "cmake.define.UNITREE_SDK2_ROOT=$UNITREE_SDK2_ROOT"

python -c "from motrix_unitree_native import G1Backend; print('native backend OK')"
python -c "from unitree_sdk2py.core.channel import ChannelFactoryInitialize; print('Python SDK OK')"
python -c "import onnxruntime; print('ONNX Runtime:', onnxruntime.__version__)"
mxlab --version

应看到 native backend OK、Python SDK OK、ONNX Runtime 1.23.2 和 mxlab 0.4.0。仅看到安装成功还不够，必须通过 native 导入检查，之后再进行 DDS 网卡检查。

若之前在缺少 SDK2 的情况下安装过 native 包，确认 SDK2 路径后重新构建：

uv pip install --no-deps --reinstall -e ./motrix_unitree_native \
  -C "cmake.define.UNITREE_SDK2_ROOT=$UNITREE_SDK2_ROOT"

以后每次运行

无需重复安装依赖。登录机器人后进入目录并激活环境：

cd ~/MotrixLab
source .venv/bin/activate

若使用上面的独立 CycloneDDS 安装，还需执行对应的两条 export，再继续下面的网卡检查和运行步骤。

选择并检查 DDS 网卡

查看运行程序的这台机器上的网卡和 IPv4 地址：

ip -br addr
DDS_IFACE=eth0
ip -br addr show dev "$DDS_IFACE"

将 eth0 替换为连接机器人控制网络的实际网卡名。它应处于启用状态，并具有控制网段的地址；常见网段为 192.168.123.0/24，以现场配置为准。SSH 使用的无线网卡与 DDS 网卡可以不同。

只读检查是否能够收到机器人状态：

motrix-deploy-unitree read-lowstate "$DDS_IFACE" \
  --robot g1-29dof --duration-s 5

结尾 Summary 中应有 valid > 0。如果没有有效数据，先检查网卡、网段、网线及机器人状态。本流程直接使用 DDS，无需 ROS master。

检查配置并启动

先查看启动配置；此命令不会启动机器人控制：

mxlab deploy deploy=g1-real \
  runtime.network_interface="$DDS_IFACE" --cfg job

确认网卡名称正确，且配置中包含 backend: unitree、transport: native_cpp 和 initial_state: passive。

完成机器人低层控制准备，确认没有其他程序同时发送电机命令。首次验证使用吊装或支架保护，并准备好急停，然后启动：

mxlab deploy deploy=g1-real runtime.network_interface="$DDS_IFACE"

需要指定策略路径时，在上述命令后添加 program.walk_artifact=实际路径 和 program.wbt_artifact=实际路径。

操作	手柄按键
起身至 FixStand	按住 LT，再按 ↑
从 FixStand 进入 Walk	按住 RB，再按 X
从 Walk 启动 WBT	按住 RB，再按 Y
返回 Passive	按住 LT，再按 B
急停并结束本次运行	select
移动 / 转向	左摇杆 / 右摇杆

在终端按 Ctrl+C 结束程序。若直接从开发机连接机器人运行，也使用同一条真机命令，但应激活开发机的部署环境，并将 DDS_IFACE 设置为开发机上连接机器人的网卡。

English — sim2sim / sim2real Deployment Guide

Applies to MotrixLab 0.4.0, branch feat/g1-native-deploy.

This guide assumes that the code and both deployment artifacts are already available. It does not include large asset downloads. sim2sim uses the existing environment on the development computer; sim2real includes the initial environment setup on the robot. Run repository commands from the repository root. The default policy paths are artifacts/g1-flat.deploy and artifacts/g1-wbt-dance.deploy.

1. sim2sim: Run on the development computer

Enter the local repository and activate an environment with mxlab installed. For example, using the existing motrix-lab environment:

cd ~/MotrixLab
conda activate motrix-lab
mxlab deploy deploy=g1-sim

If you use the repository's .venv, replace the activation command with source .venv/bin/activate.

To specify the policy paths explicitly:

mxlab deploy deploy=g1-sim \
  program.walk_artifact=/home/user/MotrixLab/artifacts/g1-flat.deploy \
  program.wbt_artifact=/home/user/MotrixLab/artifacts/g1-wbt-dance.deploy

Give the simulation window keyboard focus, then use these keys:

Action	Key
FixStand	1
Walk	2
Start WBT from Walk	3
Passive	0 or x
Forward/backward / sideways / turn	W/S, A/D, Q/E

Press Ctrl+C in the terminal to stop the run.

2. sim2real: Configure DDS and run

Log in and enter the code directory

On the development computer, replace the placeholder with the robot's actual SSH address, then log in:

ROBOT_HOST=REPLACE_WITH_ROBOT_SSH_ADDRESS
ssh "unitree@$ROBOT_HOST"

On the robot, enter the code directory. Adjust the path if your checkout is elsewhere:

cd ~/MotrixLab

Set up the robot environment for the first time

If the following installation and verification steps are already complete, skip to “For subsequent runs.” The main dependencies for hardware deployment are listed below. The installation commands handle the Python packages together.

Category	Required dependencies
System	Ubuntu on aarch64 or x86_64
Python	3.10; building the extension also requires the matching headers. The uv-managed Python used below includes them.
Installation and build tools	uv, git, a compiler supporting C++17, and CMake ≥ 3.18
C++ SDK	Complete Unitree SDK2 headers and SDK2/DDS libraries matching the machine's architecture
Python deployment dependencies	numpy>=1.26, onnxruntime==1.23.2, pydantic==2.12.5, hydra-core, omegaconf, gymnasium, and other dependencies installed automatically from the repository declarations
Python SDK dependencies	The repository-pinned unitree-sdk2py, plus its dependencies cyclonedds==0.10.2 and opencv-python

The hardware control configuration uses native_cpp. The current package dependencies and the read-only DDS check below still require the Python SDK, so it is installed as well. A robot running only sim2real does not need the training environment, Torch/CUDA, or a simulation backend.

1) Prepare the tools and Python 3.10 environment

Install the system tools:

sudo apt update
sudo apt install -y build-essential git curl ca-certificates

If uv is not installed, run:

curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"

Run the following commands only if .venv does not already exist. If you already have a working Python 3.10 environment, activate it instead:

uv python install 3.10
uv venv --managed-python --python 3.10 .venv

Activate the environment and install the build tools:

source .venv/bin/activate
python --version
uv pip install "cmake>=3.18,<4" ninja
cmake --version

Confirm that Python reports 3.10.x. If you reuse an environment created from system Python and the build reports a missing Python.h, install the matching python3.10-dev package. The uv-managed environment above does not require that additional package.

2) Set the Unitree C++ SDK2 path

Prefer the SDK2 installation already verified on the robot. For example, if it is installed under /usr/local:

export UNITREE_SDK2_ROOT=/usr/local
ls "$UNITREE_SDK2_ROOT/include/unitree/robot/channel/channel_factory.hpp"

Replace /usr/local with the actual SDK2 root directory. If SDK2 is not available yet, you can obtain a complete SDK2 checkout and use it directly:

git clone --depth 1 https://github.com/unitreerobotics/unitree_sdk2.git "$HOME/unitree_sdk2"
export UNITREE_SDK2_ROOT="$HOME/unitree_sdk2"

When using an SDK2 source checkout, keep its include, lib, and thirdparty directories, including the libraries for your machine's architecture. You do not need to build the SDK examples.

3) Install the repository deployment packages

With the environment activated, run the following from the repository root:

uv pip install \
  -e ./motrix_env_core \
  -e ./motrix_robots \
  -e ./motrix_deploy \
  -e ./motrix_deploy_tasks \
  -e ./motrix_deploy_unitree \
  "unitree-sdk2py @ git+https://github.com/motphys-developers/unitree_sdk2_python@ff87e731174f7258e0d09980897c55116634939a"

uv pip install --no-deps -e ./motrixlab

The Python SDK is pinned to the commit specified by the repository. Installing motrixlab with --no-deps provides the mxlab command; the required deployment dependencies are installed by the preceding command. Build dependencies such as pybind11 and scikit-build-core are installed automatically when building the extension.

If installation succeeds, continue to the next step. If it reports Could not locate cyclonedds, prepare CycloneDDS as described below, then rerun the installation commands in this subsection. Check this dependency particularly on ARM robots.

If CycloneDDS is missing

If CycloneDDS 0.10.2 is already installed, point CYCLONEDDS_HOME to its installation directory. Otherwise, build and install it under your user directory:

git clone --depth 1 --branch 0.10.2 \
  https://github.com/eclipse-cyclonedds/cyclonedds.git "$HOME/cyclonedds-0.10.2"
cmake -S "$HOME/cyclonedds-0.10.2" -B "$HOME/cyclonedds-0.10.2/build" \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_INSTALL_PREFIX="$HOME/.local/cyclonedds-0.10.2" \
  -DCMAKE_INSTALL_LIBDIR=lib
cmake --build "$HOME/cyclonedds-0.10.2/build" --parallel 2
cmake --install "$HOME/cyclonedds-0.10.2/build"

export CYCLONEDDS_HOME="$HOME/.local/cyclonedds-0.10.2"
export LD_LIBRARY_PATH="$CYCLONEDDS_HOME/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"

For an existing installation, use its actual path in the last two commands. After using this setup, also run these two export commands whenever you open a new terminal.

4) Build and verify the native extension

Keep UNITREE_SDK2_ROOT set to the SDK2 directory verified above:

uv pip install -e ./motrix_unitree_native \
  -C "cmake.define.UNITREE_SDK2_ROOT=$UNITREE_SDK2_ROOT"

python -c "from motrix_unitree_native import G1Backend; print('native backend OK')"
python -c "from unitree_sdk2py.core.channel import ChannelFactoryInitialize; print('Python SDK OK')"
python -c "import onnxruntime; print('ONNX Runtime:', onnxruntime.__version__)"
mxlab --version

Expected output includes native backend OK, Python SDK OK, ONNX Runtime 1.23.2, and mxlab 0.4.0. A successful installation alone is insufficient: the native import check must pass before you proceed to the DDS network interface check.

If the native package was previously installed without SDK2, confirm the SDK2 path and rebuild:

uv pip install --no-deps --reinstall -e ./motrix_unitree_native \
  -C "cmake.define.UNITREE_SDK2_ROOT=$UNITREE_SDK2_ROOT"

For subsequent runs

You do not need to reinstall the dependencies. Log in to the robot, enter the directory, and activate the environment:

cd ~/MotrixLab
source .venv/bin/activate

If you use the separate CycloneDDS installation described above, also run its two export commands before continuing with the network checks and launch steps below.

Select and check the DDS network interface

List the network interfaces and IPv4 addresses on the machine that will run the program:

ip -br addr
DDS_IFACE=eth0
ip -br addr show dev "$DDS_IFACE"

Replace eth0 with the actual interface connected to the robot's control network. It must be enabled and have an address on the control subnet. A common subnet is 192.168.123.0/24; use your actual network configuration. The Wi-Fi interface used for SSH may differ from the DDS interface.

Run this read-only check to confirm that robot state messages are received:

motrix-deploy-unitree read-lowstate "$DDS_IFACE" \
  --robot g1-29dof --duration-s 5

The final Summary should report valid > 0. If no valid data is received, check the interface, subnet, cable, and robot status first. This workflow uses DDS directly and does not require a ROS master.

Check the configuration and launch

Inspect the launch configuration first. This command does not start robot control:

mxlab deploy deploy=g1-real \
  runtime.network_interface="$DDS_IFACE" --cfg job

Confirm that the interface name is correct and the configuration contains backend: unitree, transport: native_cpp, and initial_state: passive.

Prepare the robot for low-level control and confirm that no other program is publishing motor commands. For the first test, support the robot with a harness or stand and have the emergency stop ready. Then launch:

mxlab deploy deploy=g1-real runtime.network_interface="$DDS_IFACE"

To override the policy paths, append program.walk_artifact=YOUR_WALK_PATH and program.wbt_artifact=YOUR_WBT_PATH to the command above.

Action	Gamepad control
Rise into FixStand	Hold LT, then press ↑
Enter Walk from FixStand	Hold RB, then press X
Start WBT from Walk	Hold RB, then press Y
Return to Passive	Hold LT, then press B
Emergency stop and end the run	select
Move / turn	Left stick / right stick

Press Ctrl+C in the terminal to stop the program. If you run it on a development computer connected directly to the robot, use the same hardware launch command, activate that computer's deployment environment, and set DDS_IFACE to its interface connected to the robot.