# Unitree G1

<video
  src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/lerobot/unitree_g1_passing_can.mp4"
  autoplay
  loop
  muted
  playsinline
  style={{ width: "100%" }}
/>

Humanoid Unitree G1 didukung di LeRobot. Anda dapat melakukan teleoperasi, melatih kebijakan locomanipulation, menguji dalam simulasi, dan lainnya. Kedua varian 29 dan 23 DoF didukung.

## Pemilihan Embodiment

Satu kelas `UnitreeG1` memilih definisi sendinya melalui `UnitreeG1Config.embodiment`. Nilai defaultnya adalah `g1_29`; oleh karena itu, konfigurasi yang ada tetap mempertahankan perilaku G1-29. Pilih tata letak 23-DoF dengan `--robot.embodiment=g1_23` atau di Python:

```python
from lerobot.robots.unitree_g1 import UnitreeG1Config

config = UnitreeG1Config(embodiment="g1_23", is_simulation=False)
```

| Kemampuan                                          | G1-29                         | G1-23                                        |
| --------------------------------------------------- | ----------------------------- | -------------------------------------------- |
| Konfigurasi sendi dan fitur aksi/observasi | 29 sendi tubuh, 14 sendi lengan | 23 sendi tubuh, 10 sendi lengan                |
| Tata letak perintah/umpan balik DDS                         | 29 slot aktif               | 29 slot dengan sendi yang tidak ada dibiarkan tidak aktif    |
| Simulasi MuJoCo                                   | Didukung                     | Belum didukung; model native direncanakan      |
| Kontroler lokomosi                              | GR00T dan Holosoma            | GR00T dan Holosoma                           |
| Kontroler seluruh tubuh SONIC                         | Didukung                     | Tidak didukung; kebijakan memerlukan 29 DoF    |
| Kompensasi gravitasi                                | Didukung, nonaktif secara default     | Belum didukung; kinematika native direncanakan |

Kedua varian menggunakan tata letak pesan DDS 29 slot yang sama. G1-29 menggunakan semua 29 slot, sedangkan G1-23 menggunakan 23 slot dan meninggalkan enam slot sendi yang tidak ada dalam keadaan tidak aktif. Oleh karena itu, vektor `kp`, `kd`, dan `default_positions` tetap memiliki panjang 29 elemen dan diindeks berdasarkan slot DDS. Slot lengan aktif G1-23 adalah `15..19` dan `22..26`. Slot `13, 14, 20, 21, 27, 28` tidak memiliki sendi aktif; nilai konfigurasinya harus nol. Slot ini dikecualikan dari fitur aksi/observasi, bukan diberi penomoran ulang. Entri perintah yang tidak aktif dan cadangan dibersihkan sebelum menerbitkan pesan G1-23. Override gain eksplisit harus bernilai hingga, tidak negatif, dan menggunakan tata letak sparse yang sama. Gain default dibagikan berdasarkan nama sendi di kedua varian, sehingga sendi fisik yang identik menggunakan gain yang identik, sementara slot G1-23 yang tidak ada tetap nol.

Simulasi MuJoCo native untuk G1-23 belum didukung. Memilih embodiment G1-23 dengan simulasi yang diaktifkan akan gagal sebelum inisialisasi transport. Model MuJoCo native untuk G1-23 direncanakan untuk versi mendatang.

---

## Bagian 1: Memulai

### Install SDK Unitree

Ikuti [panduan instalasi unitree_sdk2_python](https://github.com/unitreerobotics/unitree_sdk2_python#installation). Diuji dengan `unitree_sdk2py==1.0.1` dan `cyclonedds==0.10.2`:

```bash
conda create -y -n lerobot python=3.12
conda activate lerobot
git clone https://github.com/unitreerobotics/unitree_sdk2_python.git
cd unitree_sdk2_python
pip install -e .
cd ..
```

### Install LeRobot

```bash
conda install ffmpeg -c conda-forge
conda install -c conda-forge "pinocchio>=3.0.0,<4.0.0"
git clone https://github.com/huggingface/lerobot.git
cd lerobot
pip install -e '.[unitree_g1]'
```

  Untuk saat ini, pinocchio harus diinstal dari conda-forge (bukan pip) untuk menyertakan binding CasADi yang diperlukan untuk IK lengan.

### Uji Instalasi (Simulasi)

Lingkungan simulasi memiliki dependensi tersendiri. Periksa dependensi lingkungan simulasi: [Unitree G1 Mujoco EnvHub](https://huggingface.co/lerobot/unitree-g1-mujoco/tree/main).

```bash
pip install mujoco loguru msgpack msgpack-numpy
```

```bash
lerobot-teleoperate \
  --robot.type=unitree_g1 \
  --robot.is_simulation=true \
  --teleop.type=unitree_g1 \
  --teleop.id=wbc_unitree \
  --robot.cameras='{"global_view": {"type": "zmq", "server_address": "localhost", "port": 5555, "camera_name": "head_camera", "width": 640, "height": 480, "fps": 30, "warmup_s": 5}}' \
  --display_data=true \
  --robot.controller=GrootLocomotionController
```

Ini akan meluncurkan [instans simulasi MuJoCo](https://huggingface.co/lerobot/unitree-g1-mujoco/tree/main) untuk G1. Anda dapat menghubungkan gamepad ke mesin Anda sebelum meluncurkan untuk mengontrol lokomosi robot dalam simulasi. Kami mendukung [HolosomaLocomotionController](https://github.com/amazon-far/holosoma) dan [GrootLocomotionController](https://github.com/NVlabs/GR00T-WholeBodyControl) melalui `--robot.controller`.

- Tekan `9` untuk melepaskan robot
- Tekan `7` / `8` untuk meningkatkan / menurunkan tinggi pinggang

#### Memilih End Effector

`--robot.end_effector` menentukan apa yang dibawa oleh lengan: `dex1` untuk gripper paralel (default), `dex3` untuk tangan tiga jari, atau `dummy` untuk pergelangan tangan polos. Dalam simulasi, parameter ini memilih model MuJoCo, yang menentukan aktuator jari dan kamera apa saja yang dibawa oleh adegan — kamera pergelangan tangan dipasang pada end effector, sehingga `dummy` hanya memiliki `head_camera`.

```bash
lerobot-teleoperate \
  --robot.type=unitree_g1 \
  --robot.is_simulation=true \
  --robot.end_effector=dex3 \
  --teleop.id=wbc_unitree \
  --robot.controller=GrootLocomotionController
```

Sim menerbitkan kamera model melalui ZMQ di `--robot.sim_camera_port` (5555 secara default), yang merupakan tempat kamera `zmq` di `--robot.cameras` membacanya. Berikan `--robot.sim_publish_images=false` untuk membuka jendela interaktif MuJoCo sebagai gantinya: sim merender kamera atau jendelanya, tidak keduanya, karena konteks offscreen milik thread yang membuatnya, bukan milik viewer. `--robot.sim_onscreen` secara eksplisit menentukan pilihan tersebut alih-alih membiarkannya bergantung pada kamera, dan permintaan untuk keduanya akan ditolak; atur ini dan `--robot.sim_publish_images` keduanya false untuk tidak merender apa pun, yang merupakan hal yang dapat dilakukan oleh mesin tanpa display.

### Menghubungkan ke Robot Fisik

IP Ethernet G1 tetap pada `192.168.123.164`. Mesin Anda harus memiliki IP statis di subnet yang sama: `192.168.123.x` di mana `x ≠ 164`.

```bash
# Replace 'enp131s0' with your ethernet interface name (check with `ip a`)
sudo ip addr flush dev enp131s0
sudo ip addr add 192.168.123.200/24 dev enp131s0
sudo ip link set enp131s0 up
```

### SSH ke Robot

```bash
ssh unitree@192.168.123.164
# Password: 123
```

### Bagikan Internet melalui Ethernet

G1 memerlukan akses internet untuk mengkloning repositori dan menginstal paket. Bagikan koneksi laptop Anda melalui Ethernet:

**Di laptop Anda:**

```bash
sudo sysctl -w net.ipv4.ip_forward=1

# Replace wlp132s0f0 with your WiFi interface name
sudo iptables -t nat -A POSTROUTING -o wlp132s0f0 -s 192.168.123.0/24 -j MASQUERADE
sudo iptables -A FORWARD -i wlp132s0f0 -o enp131s0 -m state --state RELATED,ESTABLISHED -j ACCEPT
sudo iptables -A FORWARD -i enp131s0 -o wlp132s0f0 -j ACCEPT
```

**Di G1:**

```bash
sudo ip route del default 2>/dev/null || true
sudo ip route add default via 192.168.123.200 dev eth0
echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf

# Verify
ping -c 3 8.8.8.8
```

### Install SDK Unitree di G1

Ikuti [panduan instalasi unitree_sdk2_python](https://github.com/unitreerobotics/unitree_sdk2_python#installation):

```bash
conda create -y -n lerobot python=3.12
conda activate lerobot
git clone https://github.com/unitreerobotics/unitree_sdk2_python.git
cd unitree_sdk2_python
python -m pip install -e .
cd ..
```

### Install LeRobot di G1

```bash
git clone https://github.com/huggingface/lerobot.git
cd lerobot
conda install -c conda-forge "pinocchio>=3.0.0,<4.0.0"
python -m pip install -e '.[unitree_g1]'
```

  Untuk saat ini, pinocchio harus diinstal dari conda-forge (bukan pip) untuk menyertakan binding CasADi yang diperlukan untuk IK lengan.

### (Optional) Aktifkan WiFi pada Robot

Untuk akses SSH nirkabel, Anda dapat mengaktifkan WiFi pada G1 (secara default, WiFi diblokir):

```bash
sudo rfkill unblock all
sudo ip link set wlan0 up
sudo nmcli radio wifi on
sudo nmcli device set wlan0 managed yes
sudo systemctl restart NetworkManager
```

**Terhubung ke jaringan WiFi:**

```bash
nmcli device wifi list

sudo nmcli connection add type wifi ifname wlan0 con-name "YourNetwork" ssid "YourNetwork"
sudo nmcli connection modify "YourNetwork" wifi-sec.key-mgmt wpa-psk
sudo nmcli connection modify "YourNetwork" wifi-sec.psk "YourPassword"
sudo nmcli connection modify "YourNetwork" connection.autoconnect yes
sudo nmcli connection up "YourNetwork"

ip a show wlan0
```

Anda kemudian dapat SSH melalui WiFi alih-alih Ethernet:

```bash
ssh unitree@<ROBOT_WIFI_IP>
# Password: 123
```

---

## Bagian 2: Teleoperation & Locomotion

### Jalankan Robot Server

Di robot (dari `~/lerobot`):

```bash
cd ~/lerobot
python src/lerobot/robots/unitree_g1/run_g1_server.py --camera
```

### Jalankan Kebijakan Locomotion

Anda dapat menjalankan klien teleoperation dari laptop melalui Ethernet, melalui WiFi (eksperimental), atau langsung di robot itu sendiri. Perhatikan potensi latensi yang diperkenalkan oleh jaringan Anda.

**Dari laptop Anda:**

```bash
lerobot-teleoperate \
  --robot.type=unitree_g1 \
  --robot.is_simulation=false \
  --robot.robot_ip=<ROBOT_IP> \
  --teleop.type=unitree_g1 \
  --teleop.id=wbc_unitree \
  --robot.cameras='{"global_view": {"type": "zmq", "server_address": "<ROBOT_IP>", "port": 5555, "camera_name": "head_camera", "width": 640, "height": 480, "fps": 30}}' \
  --display_data=true \
  --robot.controller=HolosomaLocomotionController
```

Kami mendukung [GrootLocomotionController](https://github.com/NVlabs/GR00T-WholeBodyControl) dan [HolosomaLocomotionController](https://github.com/amazon-far/holosoma) melalui `--robot.controller`.

---

## Bagian 3: Loco-Manipulation dengan Eksoskeleton Homunculus

Kami menyediakan solusi loco-manipulation melalui Homunculus Exoskeleton — sebuah eksoskeleton 7 DoF open-source untuk kontrol seluruh tubuh. Lihat di [sini](https://github.com/nepyope/hmc_exo).

### Kalibrasi

```bash
lerobot-calibrate \
  --teleop.type=unitree_g1 \
  --teleop.left_arm_config.port=/dev/ttyACM1 \
  --teleop.right_arm_config.port=/dev/ttyACM0 \
  --teleop.id=exo
```

Selama kalibrasi, gerakkan setiap sendi melalui seluruh rentangnya. Setelah pemasangan, gerakkan sendi ke posisi netral dan tekan `n` untuk melanjutkan.

### Rekam Dataset

```bash
lerobot-record \
  --robot.type=unitree_g1 \
  --robot.is_simulation=true \
  --robot.cameras='{"global_view": {"type": "zmq", "server_address": "localhost", "port": 5555, "camera_name": "head_camera", "width": 640, "height": 480, "fps": 30}}' \
  --teleop.type=unitree_g1 \
  --teleop.left_arm_config.port=/dev/ttyACM1 \
  --teleop.right_arm_config.port=/dev/ttyACM0 \
  --teleop.id=exo \
  --dataset.repo_id=your-username/dataset-name \
  --dataset.single_task="Test" \
  --dataset.num_episodes=2 \
  --dataset.episode_time_s=5 \
  --dataset.reset_time_s=5 \
  --dataset.push_to_hub=true \
  --dataset.streaming_encoding=true \
  --dataset.encoder_threads=2
```

> **Catatan:** Abaikan `--teleop.left_arm_config.port` dan `--teleop.right_arm_config.port` jika Anda hanya menggunakan joystick.

Contoh dataset: [nepyope/unitree_box_move_blue_full](https://huggingface.co/datasets/nepyope/unitree_box_move_blue_full)

---

## Bagian 4: Pelatihan & Inferensi

### Latih

```bash
python src/lerobot/scripts/lerobot_train.py \
  --dataset.repo_id=your-username/dataset-name  \
  --policy.type=pi05 \
  --output_dir=./outputs/pi05_training \
  --job_name=pi05_training \
  --policy.repo_id=your-username/your-repo-id \
  --policy.pretrained_path=lerobot/pi05_base \
  --policy.compile_model=true \
  --policy.gradient_checkpointing=true \
  --trackio.enable=true \
  --policy.dtype=bfloat16 \
  --policy.freeze_vision_encoder=false \
  --policy.train_expert_only=false \
  --steps=3000 \
  --policy.device=cuda \
  --batch_size=32
```

### Inferensi dengan RTC

Kebijakan terlatih yang kompatibel dapat menggunakan RTC pada waktu inferensi lokal:

```bash
lerobot-rollout \
  --strategy.type=base \
  --policy.path=your-username/your-repo-id \
  --policy.device=cuda \
  --robot.type=unitree_g1 \
  --robot.is_simulation=false \
  --robot.controller=HolosomaLocomotionController \
  --robot.cameras='{"global_view": {"type": "zmq", "server_address": "<ROBOT_IP>", "port": 5555, "camera_name": "head_camera", "width": 640, "height": 480, "fps": 30}}' \
  --task="task_description" \
  --duration=1000 \
  --fps=30 \
  --inference.type=rtc
```

Kontroler lokomosi G1 tidak mendeklarasikan kontrak target-tertahan yang digunakan oleh menunggu yang dapat dipulihkan dari rollout. Setelah gerakan dimulai, kehabisan buffer aksi mereka menyebabkan kegagalan terminal, bukan menunggu periode toleransi. Batas waktu permintaan dan batas usia observasi juga berlaku. Validasi bahwa chunk yang dapat digunakan oleh kebijakan mencakup latensi inferensi sebelum menggunakan resep ini; lihat [menunggu dan anggaran RTC lokal](./inference#inference-backends). SONIC memiliki kontrak token-tertahan terpisah yang dijelaskan di bawah.

---

## Bagian 5: SONIC Whole-Body Control (Kebijakan Latent-Token)

LeRobot kini memindahkan bagian **decoder** dari stack deploy whole-body [SONIC](https://nvlabs.github.io/GEAR-SONIC/) milik NVIDIA sebagai `SonicWholeBodyController`. Alih-alih memberi perintah pada sendi, kebijakan ini mengeluarkan **latent motion token** 64-D (`motion_token.{i}.pos`) pada setiap tick; decoder SONIC memetakan token tersebut beserta riwayat proprioception terbaru menjadi aksi residual yang kemudian diskalakan dan ditambahkan ke pose berdiri, menghasilkan target posisi sendi 50 Hz untuk seluruh 29 DoF.

Controller memuat decoder ONNX-nya dan semua konstanta deployment (gain PD, `default_angles`, `action_scale`, dan token netral) dari [`lerobot/sonic_decoder`](https://huggingface.co/lerobot/sonic_decoder). Repo juga menyertakan decoder low-latency yang telah didistilasi, yang dapat dipilih dengan argumen `policy_type="low_latency"` pada controller (default-nya adalah `"default"`).

### Uji dalam Simulasi

Setiap kebijakan keluaran token yang dilatih pada token gerak SONIC (misalnya [`nepyope/sonic_walk`](https://huggingface.co/nepyope/sonic_walk)) dapat menggerakkannya:

```bash
lerobot-rollout \
  --strategy.type=base \
  --policy.path=nepyope/sonic_walk \
  --policy.device=cuda \
  --robot.type=unitree_g1 \
  --robot.is_simulation=true \
  --robot.controller=SonicWholeBodyController \
  --robot.cameras='{"ego_view": {"type": "zmq", "server_address": "localhost", "port": 5555, "camera_name": "head_camera", "width": 640, "height": 480, "fps": 30, "warmup_s": 15}}'
```

### Jalankan pada Robot Fisik

Jalankan server kebijakan [remote inference](./remote_inference) pada mesin GPU dan pertahankan jembatan robot, decoder SONIC, dan klien rollout pada G1 Jetson. Hanya chunk token 64-D yang melintasi jaringan; decoder dan loop `rt/lowcmd` 50 Hz tetap berada di onboard.

Instal ekstra remote di kedua mesin. Pertahankan ekstra Unitree di G1:

```bash
# GPU machine
python -m pip install -e '.[remote]'

# G1 Jetson
python -m pip install -e '.[unitree_g1,remote]'
```

Pada mesin GPU, mulai server kebijakan dari akar repositori. Profil yang dipelihara cocok dengan `nepyope/sonic_walk`; salin dan perbarui checkpoint serta kontrak fiturnya secara bersamaan untuk kebijakan lain.

```bash
lerobot-policy-server \
  --config_path=examples/remote_inference/unitree_g1_sonic.yaml
```

Pada G1, biarkan bridge dan kamera tetap berjalan:

```bash
python src/lerobot/robots/unitree_g1/run_g1_server.py --camera
```

Lalu mulai klien rollout di terminal G1 kedua, dengan mengganti `<GPU_MACHINE_IP>`:

```bash
lerobot-rollout \
  --strategy.type=base \
  --inference.type=remote \
  --inference.endpoint=tcp/<GPU_MACHINE_IP>:7447 \
  --inference.deployment=g1-sonic \
  --inference.semantics=unitree-g1-sonic-motion-token-v1 \
  --inference.encoding=jpeg \
  --inference.action_starvation_grace_s=1.0 \
  --robot.type=unitree_g1 \
  --robot.is_simulation=false \
  --robot.robot_ip=127.0.0.1 \
  --robot.controller=SonicWholeBodyController \
  --robot.cameras='{"ego_view": {"type": "zmq", "server_address": "127.0.0.1", "port": 5555, "camera_name": "head_camera", "width": 640, "height": 480, "fps": 30, "warmup_s": 5}}' \
  --task='walk forward' \
  --fps=30 \
  --return_to_initial_position=false \
  --interactive=true
```

Ketik `/start` hanya setelah G1 siap bergerak. SONIC menyatakan dukungan menunggu karena pengiriman ulang token lengkap terakhir menjaga keseimbangan dekoder onboard. Sebelum hasil kebijakan pertama, rollout mengirim token netral dari dekoder. Jika buffer aksi habis, token yang diterapkan terakhir diulang selama maksimal `action_starvation_grace_s` (satu detik di atas); jika tidak ada prediksi baru yang tiba, rollout mengalami kegagalan dan mengikuti jalur shutdown/disconnect yang dikonfigurasi. Kontroler lokomosi G1 tetap tidak didukung karena kecepatan joystick-nya tidak dapat dipertahankan dengan cara ini.

Resep ini menonaktifkan pengembalian ke posisi awal: interpolasi melalui ruang token laten SONIC bukan lintasan homing fisik yang tervalidasi. Hindari `/reset` karena alasan yang sama, karena hal itu akan menggeser token kembali ke nilai saat koneksi. `/stop` tetap menutup sesi jarak jauh dan memutus koneksi robot melalui jalur shutdown pengontrol normal.

Dengan `SonicWholeBodyController`, status observasi adalah token echo 64-D, bukan 29 posisi sendi, sehingga checkpoint yang kompatibel harus dilatih terhadap status tersebut. Saat terhubung, robot meredakan sendi ke `default_angles` dari decoder sebelum controller mengambil alih.

---

## Sumber Daya Tambahan

- [Dokumentasi Unitree SDK](https://github.com/unitreerobotics/unitree_sdk2_python)
- [GR00T-WholeBodyControl](https://github.com/NVlabs/GR00T-WholeBodyControl)
- [Holosoma](https://github.com/amazon-far/holosoma)
- [Dokumentasi LeRobot](https://github.com/huggingface/lerobot)
- [Unitree IL LeRobot](https://github.com/unitreerobotics/unitree_IL_lerobot)

---

_Terakhir diperbarui: Juli 2026_