unitree-g1/context/sdk-programming.md

id	title	status	source_sections	related_topics	key_equations	key_terms	images	examples	open_questions
sdk-programming	SDK & Programming Interface	established	reference/sources/github-unitree-sdk2.md, reference/sources/github-unitree-sdk2-python.md, reference/sources/official-get-sdk.md, reference/sources/official-dds-services.md	[ros2-integration networking-comms joint-configuration sensors-perception]	[]	[unitree_sdk2 dds cyclone_dds pybind11 lowcmd lowstate motor_cmd force_position_hybrid domain_id]	[]	[]	[Python vs C++ API coverage parity (are all C++ features wrapped?) High-level sport mode API details for G1 specifically Camera API — how to access D435i frames via SDK]

SDK & Programming Interface

Software development kits, APIs, and programming interfaces for controlling the G1.

1. Unitree SDK2 (C++)

The primary SDK for robot control. DDS-based, works without ROS2 but remains ROS2-compatible. [T0 — GitHub]

Property	Value
Repository	https://github.com/unitreerobotics/unitree_sdk2
Version	v2.0.2 (as of July 2025)
Language	C++ (99.2% of codebase)
License	BSD-3-Clause
Middleware	CycloneDDS v0.10.2
Supported OS	Ubuntu 20.04 LTS
Architectures	aarch64 (Jetson), x86_64 (development PC)
Compiler	GCC 9.4.0+
Build system	CMake 3.10+
GitHub stars	~888

Dependencies

sudo apt install cmake libyaml-cpp-dev libeigen3-dev libboost-all-dev libspdlog-dev libfmt-dev

Build & Install

git clone https://github.com/unitreerobotics/unitree_sdk2.git
cd unitree_sdk2
mkdir build && cd build
cmake .. && make

# System-wide install (optional)
sudo make install

# Custom install location
cmake .. -DCMAKE_INSTALL_PREFIX=/custom/path
sudo make install

Key Features

• Request-response and topic subscription/publishing patterns
• Low-level motor control (LowCmd/LowState)
• High-level sport mode commands
• IMU data access
• Wireless controller input
• Native DDS — no ROS2 dependency required

2. Python SDK (unitree_sdk2_python)

Python wrapper maintaining API consistency with C++ SDK. [T0 — GitHub]

Property	Value
Repository	https://github.com/unitreerobotics/unitree_sdk2_python
Binding	pybind11
Python version	≥ 3.8
CycloneDDS version	0.10.2 (critical — must match)
License	BSD-3-Clause
GitHub stars	~579

Installation

git clone https://github.com/unitreerobotics/unitree_sdk2_python.git
cd unitree_sdk2_python
pip3 install -e .

Note: May require separate CycloneDDS compilation from source and setting the CYCLONEDDS_HOME environment variable. [T1]

G1 Examples

Located in /example/g1/ directory:

• High-level control: stand/lie down, velocity commands, attitude adjustment, trajectory tracking
• Low-level control: direct motor position/torque commands
• Peripherals: wireless controller, front camera (OpenCV), obstacle avoidance, LED/volume control

All examples require a network interface parameter (e.g., enp2s0) for robot connectivity.

3. Control Modes

The SDK supports multiple control modes via the MotorCmd_ structure: [T0 — Developer Guide]

Mode	Field	Description
Position control	q	Target joint angle in radians
Velocity control	dq	Target joint velocity in rad/s
Torque control	tau	Feed-forward torque in Nm
Force-position hybrid	q + tau	Position target with torque feed-forward
Enable/disable	mode	0 = Disable motor, 1 = Enable motor

Control loop rate: 500 Hz (commands should be published at this rate for smooth control)

4. Data Streams (DDS Topics)

Body Control

Topic	Type	Direction	Description
rt/lowstate	unitree_hg::msg::dds_::LowState_	Subscribe	Full robot state
rt/lowcmd	unitree_hg::msg::dds_::LowCmd_	Publish	Motor commands for all joints

Dexterous Hand (Dex3-1)

Topic	Type	Direction	Description
rt/dex3/left/cmd	unitree_hg protocol	Publish	Left hand commands
rt/dex3/right/cmd	unitree_hg protocol	Publish	Right hand commands
rt/dex3/left/state	unitree_hg protocol	Subscribe	Left hand state
rt/dex3/right/state	unitree_hg protocol	Subscribe	Right hand state

LowState_ Contents (HG variant for G1)

• mode_pr: Parallel mechanism control mode
• mode_machine: G1 type identifier (5=g1_29dof_rev_1_0, 11-16=newer revisions)
• tick: Timer (increments every 1ms)
• imu_state: IMU sensor data (quaternion [w,x,y,z], angular velocity, acceleration)
• motor_state: State for all body motors (position, velocity, torque)
• wireless_remote: Remote control data (all zeros until button pressed)
• crc: Checksum for data integrity

LowCmd_ Variants [T1 — Verified 2026-02-15]

The G1 uses the HG message variant (unitree_hg_msg_dds__LowCmd_), NOT the GO variant:

Field	HG (G1)	GO (Go2)
mode_pr	Yes	No
mode_machine	Yes	No
motor_cmd	Yes	Yes
reserve	Yes	No
crc	Yes	Yes
head	No	Yes
level_flag	No	Yes
gpio	No	Yes

Using the wrong variant will cause AttributeError at runtime. Always use unitree_hg_msg_dds__LowCmd_() for G1.

mode_machine Values [T1]

Value	Model	Hip Pitch Ratio	Hip Roll Ratio	Notes
2	g1_29dof (old)	14.3	14.5	Pre-rev-1.0
5	g1_29dof_rev_1_0	14.3	22.5	Common for EDU units
11	g1_29dof_mode_11	22.5	22.5	Newer — both hips upgraded
12	g1_29dof_mode_12	22.5	22.5	Newer variant
13-16	g1_29dof_mode_13-16	varies	22.5	5010 wrist motor variants

Important: Always read mode_machine from rt/lowstate rather than hardcoding. The firmware uses this value to interpret joint commands with the correct gear ratios.

5. Development Workflow

1. Simulation first: Test with unitree_mujoco (same DDS interface, switch domain ID)
2. Network setup: Connect to robot's WiFi or Ethernet (192.168.123.0/24)
3. Verify connection: Subscribe to rt/lowstate to confirm data flow
4. Start simple: Begin with high-level sport mode commands before low-level control
5. Deploy to Jetson: Cross-compile or develop directly on the onboard Jetson Orin NX

6. Code Examples

See examples/ for worked examples. Key patterns:

• Subscriber pattern: Create DDS subscriber for rt/lowstate, read joint states in callback
• Publisher pattern: Create DDS publisher for rt/lowcmd, send motor commands at 500 Hz
• High-level pattern: Use sport mode request/response API for walking, standing, etc.

Key Relationships

• Controls: joint-configuration (joint-level commands via MotorCmd_)
• Reads from: sensors-perception (IMU, encoder data via LowState_)
• Integrates with: ros2-integration (same DDS layer)
• Communicates via: networking-comms (CycloneDDS transport)