Core Scripts for Saaki - Unitree G1

English | Español

Example	Example

📖 Description

Repository for developing control scripts for the Unitree G1 robot in the Saaki project. This project unifies program development with its SDK in Python and C++.

The main objective of this repository is to create small programs for the robot and understand the SDK through practical use cases.

It will continue to grow as we advance with the robot and explore more possibilities.

---

📂 Repository Structure

└── saaki-core/                 ← core (Python | C++) (This repository)
    │
    ├── python/                 # Control scripts and logic (Python SDK)
    │   ├── high/    
    │   │   └── ___.py          
    │   └── low/
    │       └── ___.py
    │
    ├── cpp/                    # High-performance code (C++ SDK)
    │   ├── high/
    │   │   ├── ___.cpp 
    │   │   ├── ...
    │   │   └── CMakeLists.txt
    │   │
    │   └── low/
    │       ├── ___.cpp 
    │       ├── ...
    │       └── CMakeLists.txt
    │
    ├── media/                  # Videos, gifs, images...
    ├── .gitignore              # Includes what we don't want to upload to github
    ├── requirements.txt        # Python project dependencies
    ├── LICENSE.md              # License
    ├── README_es.md            # Repository information in Spanish
    └── README.md               # Repository information

                    
unitree_mujoco/               }
unitree_sdk2/                 } # Official Unitree repositories (Use BioAraba forks)
unitree_sdk2_python/          }

---

🐍 Installation and Configuration (Python)

Assumes you are working in an Ubuntu 22.04 environment.

1. Clone the repository

# Clone this repository
git clone https://github.com/UAI-BIOARABA/saaki-core.git

2. External Dependencies (Forks)

This project depends on official Unitree repositories. We use our own forks in the organization to ensure stability.

cd ~

# Clone SDK (Use our Fork, not the official Unitree one directly)
git clone https://github.com/UAI-BIOARABA/unitree_sdk2_python.git
git clone https://github.com/UAI-BIOARABA/unitree_mujoco.git

3. Virtual Environment (Conda)

We use a single virtual environment for the entire workspace.

# Create environment
conda create --name saaki-core python=3.10.12

# Activate in each terminal
conda activate saaki-core

# Install SDK dependencies in editable mode
cd unitree_sdk2_python
# Install necessary compilation dependencies (just in case)
pip install setuptools wheel
pip install -e .

# Install our project dependencies
cd ~
cd saaki-core
pip install matplotlib pydot    # Install them now to avoid potential errors
pip install -r requirements.txt

4. Check for errors

If you enter from VS Code, it's very likely that it won't work at first because it can't find the installed SDK path. It's also likely that the editor itself will fix it if we choose 'quick fix', but if not, we'll do it manually.

• In VS Code itself, create a folder in the workspace root called '.vscode'.
• Create a file inside called 'settings.json'.
• Inside, write the following:

{
    "python-envs.defaultEnvManager": "ms-python.python:conda",
    "python-envs.defaultPackageManager": "ms-python.python:conda",
    "python-envs.pythonProjects": [],
    "python.analysis.extraPaths": [
        "~/unitree_sdk2_python" 
    ],
    "python.autoComplete.extraPaths": [
        "~/unitree_sdk2_python"
    ]
}

• While we're here, let's do the same for C++ which we'll configure in a moment.
• In the same '.vscode' folder create another file called 'c_cpp_properties.json'
• Inside, write the following (replace YOUR_USERNAME with your username):

{
    "configurations": [
        {
            "name": "Linux",
            "includePath": [
                "${workspaceFolder}/**",
                "/home/YOUR_USERNAME/unitree_sdk2/include",
                "/usr/local/include/ddscxx"
            ],
            "defines": [],
            "compilerPath": "/usr/bin/gcc",
            "cStandard": "c17",
            "cppStandard": "gnu++17",
            "intelliSenseMode": "linux-gcc-x64"
        }
    ],
    "version": 4
}

And the error should now be fixed.

5. Usage and Workflow

Simulation (Sim-to-Real) Always validate in MuJoCo before testing on the physical robot.

Terminal 1: Launch simulator from g1_workspace (with the environment activated)

cd unitree_mujoco/simulate_python
python3 unitree_mujoco.py

Terminal 2: Execute our scripts (with the environment activated)

cd saaki-core/python/low
python3 low_example_sim.py

---

©️ Installation and Configuration (C++)

Assumes that the workspace and Python installation have already been configured.

1. Clone and compile the SDK

cd ~
git clone https://github.com/UAI-BIOARABA/unitree_sdk2.git
cd unitree_sdk2
# Create build folder
mkdir build
cd build

# Compile configuring the recommended installation path
cmake .. -DCMAKE_INSTALL_PREFIX=/opt/unitree_robotics

# Install (requires sudo)
sudo make install

2. Install MuJoCo and unitree_mujoco

We need to download the official MuJoCo binaries.

Go to the MuJoCo releases page: https://github.com/google-deepmind/mujoco/releases.

Download version 3.3.6 corresponding to Linux (mujoco-3.3.6-linux-x86_64.tar.gz).

Extract the file to your home folder inside a hidden folder called .mujoco.

Quick commands:

mkdir ~/.mujoco
tar -xvf mujoco-3.3.6-linux-x86_64.tar.gz -C ~/.mujoco
# At the end you should have a valid path like: ~/.mujoco/mujoco-3.3.6

3. Configure unitree_mujoco

cd unitree_mujoco/simulate
# IMPORTANT: Create the symbolic link to your MuJoCo installation.
# Make sure the version matches the one you downloaded (mujoco-3.3.6).
ln -s ~/.mujoco/mujoco-3.3.6 mujoco

4. Compile the simulator (C++)

# Being inside unitree_mujoco/simulate
mkdir build
cd build
cmake ..
make -j4

If everything goes well, you'll have an executable called unitree_mujoco.

5. Usage and Workflow

Simulation (Sim-to-Real) Always validate in MuJoCo before testing on the physical robot.

Terminal 1: Start the Simulator We'll run the simulator loading the G1 robot (it should come up automatically but just in case we specify it).

cd ~/unitree_mujoco/simulate/build
./unitree_mujoco -r g1 -s scene.xml

Terminal 2: Execute a Control Example (C++)

# Go to the C++ examples folder, saaki-core/cpp
cd ~/saaki-core/cpp/low

# Compile the example:
mkdir build
cd build
cmake ..
make -j4

# Execute the control code
./tobillos

If everything is connected correctly, you'll see in the simulator window (Terminal 1) that the robot starts moving its ankles (or arms if you launch the other example).

---

🚨 Important Note

If you've already installed any ROS2 dependencies as indicated in the unitree_ros2 repository, you may encounter errors when executing C++ programs.

The problem is that the "ros-humble-rmw-cyclonedds-cpp" package generates conflicts with the Unitree SDK2 DDS, causing programs to find problems accessing the device's shared memory and eventually close.

The solution we've found is to create the following file that forces programs to use the correct versions of DDS instead of those from ROS.

Create the file "setup_unitree.sh" and write the following inside:

#!/bin/bash
echo "Setting up environment for Unitree SDK2..."
export LD_LIBRARY_PATH=$HOME/unitree_sdk2/thirdparty/lib/x86_64:$LD_LIBRARY_PATH
echo "Ready! You can now execute your saaki-core scripts."

In each terminal where you want to execute C++ code, do:

source setup_unitree.sh

---

🤖 Real G1 Robot

CAUTION: Make sure the robot is hanging or in a safe position before executing new code

Connect Ethernet cable to the robot.

Ensure connection with ping to the corresponding IP.

Execute the script just like in simulation.

---

☁️ SDK Updates

If Unitree updates their repositories, the person in charge or a developer with permissions must synchronize the organization's Forks using the "Sync Fork" button on GitHub and then notify the team to do git pull.

---

🧑‍💻 Authors

• Project Manager: Juan Fernández
• Lead Developer: Andoni González

---

Disclaimer

This software and the accompanying materials are provided “as is,” without warranties of any kind, either express or implied, including—but not limited to—warranties of merchantability, fitness for a particular purpose, or absence of errors.

The authors and Bioaraba – Health Research Institute assume no responsibility for the use, redistribution, or modification of this repository, nor for any direct or indirect damages arising from its use.

This project is intended exclusively for research and/or educational purposes. It is not intended for clinical, diagnostic, therapeutic, or healthcare use, nor does it replace certified tools or professional judgment in healthcare settings.

Notwithstanding the foregoing, use of the software and the robotic system shall be at the user’s own risk. The user must verify its suitability for the intended purpose and adopt all necessary safety, supervision, and control measures based on the environment and conditions of use.

The user shall be responsible for any consequences arising from improper, negligent, or non-compliant use, including any personal injury or property damage that may occur.

To the fullest extent permitted by applicable law, Bioaraba shall not be liable for any damages arising from the use of the software or robotic system when such damages result from defective implementation, insufficient supervision, inappropriate use decisions by the user, or failure to observe recommended safety measures.