SDK Development

This section summarises how to set up and develop applications for the Unitree R1 using the official SDKs. It is based on Unitree’s R1 Developer Guide and the public Unitree repositories. Always treat the official guide as the authoritative reference for your firmware version.

Overview

The R1 is controlled through Unitree’s CycloneDDS-based communication stack, which operates with or without ROS 2 while remaining ROS 2 compatible. Three primary SDKs are available:

  • unitree_sdk2 — the C++ SDK for high- and low-level control, state subscription, and sensor access. Repository: unitree_sdk2.

  • unitree_sdk2_python — the Python interface (pybind11 wrapper) for rapid prototyping. Repository: unitree_sdk2_python.

  • unitree_ros2 — ROS 2 packages that bridge the same DDS interface into ROS 2 topics and messages. Repository: unitree_ros2.

All Unitree open-source SDKs are published under the Unitree Robotics GitHub organisation.

Requirements

Item

Requirement

Operating System

Ubuntu 20.04 LTS

Compiler

GCC 9.4.0 (C++17)

Build System

CMake 3.10+

Architecture

x86_64 or aarch64

Transport

DDS (CycloneDDS)

Python (optional)

Python 3.8+

Installing Dependencies

Install the build toolchain and required libraries:

sudo apt update
sudo apt install -y cmake g++ build-essential \
    libyaml-cpp-dev libeigen3-dev libboost-all-dev \
    libspdlog-dev libfmt-dev

Building and Installing unitree_sdk2

Clone and build the C++ SDK:

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

To install the SDK system-wide (recommended for use in your own CMake projects):

cd unitree_sdk2/build
cmake .. -DCMAKE_INSTALL_PREFIX=/opt/unitree_robotics
sudo make install

Installing the Python Interface

For Python development, install unitree_sdk2_python:

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

Network Configuration

The R1 communicates with a development PC over Gigabit Ethernet using CycloneDDS. Connect the robot and your computer with an Ethernet cable, then identify the interface that links to the robot:

# List network interfaces and find the one connected to the R1
ifconfig

Unitree robots use the 192.168.123.x subnet by convention. Ensure your development machine is on the same subnet as the robot’s onboard computer. The R1-EDU development computing unit is preconfigured at 192.168.123.164 (default login unitree / 123 — change after first access). Configure your PC’s wired interface to a static address on the same subnet:

# Example: set a static IP on the wired interface (replace eth0 with your NIC)
sudo ip addr add 192.168.123.222/24 dev eth0
sudo ip link set eth0 up

# Confirm the robot is reachable
ping 192.168.123.164

Important

The exact network setup and any robot-specific addresses are documented in the official R1 Developer Guide. Confirm the values for your unit before configuring your PC.

Specifying the Network Interface

unitree_sdk2 examples and applications must be told which network interface is connected to the robot. The interface name (for example eth0) is passed as a command-line argument when launching an example:

# Run a built example, passing the network interface name
./example_program eth0

In C++, the interface is supplied when initialising the DDS channel factory:

#include <unitree/robot/channel/channel_factory.hpp>

int main(int argc, char** argv)
{
    // argv[1] is the network interface connected to the R1 (e.g. "eth0")
    unitree::robot::ChannelFactory::Instance()->Init(0, argv[1]);
    // ... create publishers / subscribers and control the robot ...
    return 0;
}

The equivalent in Python:

import sys
from unitree_sdk2py.core.channel import ChannelFactoryInitialize

# sys.argv[1] is the network interface connected to the R1 (e.g. "eth0")
ChannelFactoryInitialize(0, sys.argv[1])
# ... create publishers / subscribers and control the robot ...

Control Interfaces

The SDK exposes both high-level and low-level control:

  • High-level control issues task-space commands (locomotion modes, posture, velocity) and is the safe default for most applications.

  • Low-level control commands individual joint targets (position, velocity, torque, stiffness, and damping). Low-level commands bypass built-in balancing safeguards and must remain within the documented joint limits.

The R1 joint indices, names, and motion limits used by the low-level interface are listed in the About R1 page under Joint Motors → Joint Indexing and Motion Limits. Always validate commanded joint motions against those limits before sending them.

Warning

Custom low-level control code can command the robot into unsafe states. Test new control software with the R1 safely supported or in a clear, open area, keep the emergency stop within reach, and validate joint commands against the documented limits before deployment.

Further Resources