Unitree Cpp

A lightweight Python binding for Unitree SDK2, designed to overcome the performance issues of the official unitree_sdk2_python on the Unitree G1 (Jetson Orin).

FREE YOUR UNITREE G1 FROM THE ETHERNET CABLE!

News 🎉: Our Deployment Framework is released at RoboJuDo, try it out!

Inspiration

On Unitree G1, unitree_sdk2_python often suffers from serious performance issues, making it difficult to achieve real-time deploy with built-in Jetson pc2.

Using unitree_sdk2 directly avoids these performance problems, but C++ development and compilation can be cumbersome and time-consuming.

This project provides the best of both worlds:

• Python interface for simplicity and quick prototyping
• C++ backend for high-frequency communication and efficiency

As a result, you can write simple control code in Python, without dealing with the C++ compilation, while still ensuring real-time performance.

We tested the performance of unitree_cpp with AMO on G1 pc2. The results are as follows:

Implementation	Cost of control (μs/hit)
unitree_sdk2_python	3871.039
unitree_cpp	40.045

Installation

1. Install Unitree SDK2

Follow the instructions on Unitree SDK2
to install the SDK2 on your system.

Note: It is recommended to use the default installation path.
If you choose a custom path, make sure to update CMakeLists.txt accordingly,
so that the required libraries can be found.

2. Install unitree_cpp Python Binding

# switch to your python env
# tested on python>=3.8
pip install .

Getting Started

Please refer to the example file: example/unitree_cpp_env.py.

Test the example with your robot:

• pip install -r example/requirements.txt
• change ethernet interface eth_if in example/config.py
• run the example
• your robot should move slowly into default position

This project supports:

• Unitree G1
• Dex-3 hand
• Odometry service

CHANGELOG

1.0.2

• Fix: shutdown as damping mode

1.0.3 [IMPORTANT FIX]

• Fix control delay, send command immediately after step.
  • this bug could lead to jittering and stability issue, see #2.

1.0.4

• Add torso (secondary) IMU data for G1, exposed via RobotState.torso_imu_state. see #5.

TESTING guide

Debug / development only. The dummy SDK has no hardware or DDS and serves simulated data — never deploy a dummy build to a real robot.

The real Unitree SDK2 + CycloneDDS cannot be installed on every machine (e.g. macOS dev laptops). For development and interface testing, a header-only dummy SDK is bundled under dummy_sdk/. It provides stand-ins for the SDK symbols so the extension builds and import unitree_cpp works without any hardware or DDS.

To make the pipeline runnable, the dummy simulates inbound data: subscribers synthesize a stationary robot (zeroed joints, identity base IMU, a slightly tilted torso IMU, zero odometry) and deliver it to the controller's callbacks, so self_check() passes and get_robot_state() returns a populated state. Commands sent via publishers are simply dropped.

The dummy is opt-in. A normal build links the real unitree_sdk2 and fails loudly if it is not found, so a missing SDK is never silently replaced by a non-functional module. Enable the dummy explicitly:

pip install . --config-settings=cmake.define.USE_DUMMY_SDK=ON
# or, with uv:
uv pip install . --config-settings=cmake.define.USE_DUMMY_SDK=ON

A dummy build also emits a RuntimeWarning on import unitree_cpp, so it is never mistaken for a real one.

License

CC-BY-4.0