# 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%" }}
/>

Unitree G1 insan benzeri robotu LeRobot tarafından desteklenmektedir. Uzaktan kontrol edebilir, locomanipulation politikaları eğitebilir, simülasyonda test edebilir ve daha fazlasını yapabilirsiniz. Hem 29 hem de 23 DoF varyantları desteklenmektedir.

## Vücut Seçimi

`UnitreeG1` sınıfı, eklem tanımlarını `UnitreeG1Config.embodiment` üzerinden seçer. Varsayılan değer `g1_29`'dir; bu nedenle mevcut yapılandırmalar G1-29 davranışını korur. 23-DoF yerleşimini `--robot.embodiment=g1_23` ile veya Python'da şu şekilde seçin:

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

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

| Yetenek                                          | G1-29                         | G1-23                                        |
| --------------------------------------------------- | ----------------------------- | -------------------------------------------- |
| Ortak yapılandırma ve eylem/gözlem özellikleri | 29 gövde eklemi, 14 kol eklemi | 23 gövde eklemi, 10 kol eklemi                |
| DDS komut/geri bildirim düzeni                         | 29 aktif slot               | 29 eklemi olmayan slot pasif bırakıldı    |
| MuJoCo simülasyonu                                   | Destekleniyor                     | Henüz desteklenmiyor; yerel model planlanıyor      |
| Hareket denetleyicileri                              | GR00T ve Holosoma            | GR00T ve Holosoma                           |
| SONIC tüm vücut denetleyicisi                         | Destekleniyor                     | Desteklenmiyor; politika 29 DoF gerektirir    |
| Ağırlık telafisi                                | Desteklenir, varsayılan olarak kapalı     | Henüz desteklenmiyor; yerel kinematik planlanıyor |

Her iki varyant da aynı 29 slotlu DDS mesaj düzenini kullanır. G1-29 tüm 29 slotu kullanırken G1-23 23 slotu kullanır ve altı mevcut olmayan eklem slotunu pasif bırakır. Bu nedenle `kp`, `kd` ve `default_positions` vektörleri 29 eleman uzunluğunda kalır ve DDS slotuna göre indekslenir. G1-23'ün aktif kol slotları `15..19` ve `22..26`'dır. `13, 14, 20, 21, 27, 28` slotlarında aktif eklem yoktur; yapılandırma değerleri sıfır olmalıdır. Bu slotlar eylem/gözlem özelliklerinden çıkarılır, yeniden numaralandırılmaz. Pasif ve ayrılmış komut girdileri, bir G1-23 mesajı yayımlanmadan önce temizlenir. Açık kazanç geçersiz kılma işlemleri sonlu, negatif olmayan ve aynı seyrek düzeni kullanmalıdır. Varsayılan kazançlar, her iki varyant arasında eklem adıyla paylaşıldığından, aynı fiziksel eklem aynı kazançları kullanırken G1-23'te olmayan slotlar sıfırda kalır.

Native G1-23 MuJoCo simülasyonu henüz desteklenmiyor. Simülasyon etkinleştirilmiş olarak G1-23 embodiment seçildiğinde, transport başlatılmasından önce hata oluşur. Native G1-23 MuJoCo modeli, gelecekteki bir sürümde planlanmaktadır.

---

## Bölüm 1: Başlangıç

### Unitree SDK'yi yükleyin

[unitree_sdk2_python kurulum kılavuzunu](https://github.com/unitreerobotics/unitree_sdk2_python#installation) izleyin. `unitree_sdk2py==1.0.1` ve `cyclonedds==0.10.2` ile test edildi:

```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 ..
```

### LeRobot'u Yükle

```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]'
```

  Şimdilik, arm IK için gerekli olan CasADi bağlamalarını içerebilmesi için pinocchio, pip yerine conda-forge'dan kurulmalıdır.

### Kurulumu Test Et (Simülasyon)

Simülasyon ortamının kendi bağımlılıkları vardır. Simülasyon ortamı bağımlılıklarını kontrol edin: [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
```

Bu, G1 için bir [MuJoCo sim örneği](https://huggingface.co/lerobot/unitree-g1-mujoco/tree/main) başlatacaktır. Sim içinde robotun yürüyüşünü kontrol edebilmek için başlatmadan önce makinenize bir oyun kolu bağlayabilirsiniz. `--robot.controller` aracılığıyla hem [HolosomaLocomotionController](https://github.com/amazon-far/holosoma) hem de [GrootLocomotionController](https://github.com/NVlabs/GR00T-WholeBodyControl) desteklenmektedir.

- Robotu serbest bırakmak için `9` tuşuna basın
- Bel yüksekliğini artırmak / azaltmak için `7` / `8` tuşlarına basın

#### Son Etkileyiciyi Seçme

`--robot.end_effector`, kolların ne taşıdığını belirtir: paralel kavrayıcılar için (varsayılan) `dex1`, üç parmaklı eller için `dex3` veya çıplak bilekler için `dummy`. Simülasyonda MuJoCo modelini seçer; bu model parmak aktüatörlerini ve sahnenin hangi kameraları içerdiğini belirler — bilek kameraları uç efektere monte edildiğinden, `dummy` yalnızca `head_camera` içerir.

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

Sim, modelin kameralarını `--robot.sim_camera_port` (varsayılan olarak 5555) üzerinden ZMQ ile yayınlar; `--robot.cameras` içindeki `zmq` kameraları da görüntüleri buradan okur. Bunun yerine MuJoCo'nun etkileşimli penceresini açmak için `--robot.sim_publish_images=false` parametresini iletin: sim, ekran dışı bağlamlar oluşturuldukları izleyiciye değil, onları oluşturan iş parçacığına ait olduğu için yalnızca kameralarını ya da penceresini, asla ikisini birden render etmez. `--robot.sim_onscreen` bu seçimi kameralara bırakmak yerine açıkça belirtir ve ikisinin de istenmesi reddedilir; ikisini de render etmemek için bunu ve `--robot.sim_publish_images` parametresini de false olarak ayarlayın, bu da ekranı olmayan bir makinenin yapabileceği şeydir.

### Fiziksel Robotla Bağlantı Kurun

G1'in Ethernet IP'si `192.168.123.164` olarak sabittir. Makinenizin aynı alt ağda statik bir IP'si olmalıdır: `192.168.123.x` burada `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
```

### Robot'a SSH ile bağlanın

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

### Ethernet ile İnternet Paylaşımı

G1'in depoları klonlamak ve paketleri yüklemek için internet erişimine ihtiyacı vardır. Laptop bağlantınızı Ethernet üzerinden paylaşın:

**Laptop'unuzda:**

```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
```

**G1 üzerinde:**

```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
```

### G1 üzerinde Unitree SDK'sını yükleyin

[unitree_sdk2_python kurulum kılavuzunu](https://github.com/unitreerobotics/unitree_sdk2_python#installation) izleyin:

```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 ..
```

### G1 üzerinde LeRobot'ı yükleyin

```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]'
```

  Şimdilik, arm IK için gerekli olan CasADi bağlamalarını içerebilmesi için pinocchio, pip yerine conda-forge'dan kurulmalıdır.

### (İsteğe bağlı) Robotta WiFi'ı Etkinleştir

Kablosuz SSH erişimi için G1 üzerinde WiFi'yi etkinleştirebilirsiniz (varsayılan olarak engellenmiştir):

```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
```

**Bir WiFi ağına bağlanın:**

```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
```

Ardından Ethernet yerine WiFi üzerinden SSH bağlantısı kurabilirsiniz:

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

---

## Bölüm 2: Teleoperasyon & Locomotion

### Robot Sunucusunu Çalıştırın

Robot üzerinde (`~/lerobot` içinden):

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

### Locomotion Politikasını Çalıştırın

Teleoperasyon istemcisini, Ethernet üzerinden, WiFi üzerinden (deneysel) veya doğrudan robotun kendisinde, dizüstü bilgisayarınızdan çalıştırabilirsiniz. Ağınızın getirebileceği olası gecikmelere dikkat edin.

**Laptop'unuzdan:**

```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
```

[GrootLocomotionController](https://github.com/NVlabs/GR00T-WholeBodyControl) ve [HolosomaLocomotionController](https://github.com/amazon-far/holosoma) her ikisini de `--robot.controller` aracılığıyla destekliyoruz.

---

## Bölüm 3: Homunculus Ekzoskeleti ile Loco-Manipülasyon

Homunculus Ekzoskeleti aracılığıyla bir loco-manipulation çözümü sunuyoruz — tüm vücut kontrolü için açık kaynaklı 7 DoF bir ekzoskelet. [buradan](https://github.com/nepyope/hmc_exo) inceleyebilirsiniz.

### Kalibre

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

Kalibrasyon sırasında her eklemi tüm hareket aralığında gezdirin. Ayarlama tamamlandıktan sonra eklemi nötr konuma getirin ve ilerlemek için `n` tuşuna basın.

### Bir Veri Seti Kaydet

```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
```

> **Not:** Yalnızca joystick kullanıyorsanız `--teleop.left_arm_config.port` ve `--teleop.right_arm_config.port` parametrelerini atlayın.

Örnek veri seti: [nepyope/unitree_box_move_blue_full](https://huggingface.co/datasets/nepyope/unitree_box_move_blue_full)

---

## Bölüm 4: Eğitim & Çıkarım

### Eğit

```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
```

### RTC ile çıkarım

Uygun bir şekilde eğitilmiş bir politika, yerel çıkarım zamanı RTC'sini kullanabilir:

```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
```

G1 yürüyüş denetleyicileri, rollout'un kurtarılabilir bekleme mekanizmasının kullandığı saklanan hedef sözleşmesini beyan etmez. Hareket başladıktan sonra, eylem tamponunun tükenmesi bir kibarlık süresi bekleme yerine sonlu bir arızaya neden olur. İstek süre sınırları ve gözlem yaş sınırları da geçerlidir. Bu tarifi kullanmadan önce, politikanın kullanılabilir parçasının çıkarım gecikmesini kapsadığını doğrulayın; bkz. [yerel RTC bekleme ve bütçeleri](./inference#inference-backends). SONIC'nin aşağıda açıklanan ayrı bir saklanan jeton sözleşmesi vardır.

---

## Bölüm 5: SONIC Tüm Vücut Kontrolü (Latent-Token Politikaları)

LeRobot artık NVIDIA'nın [SONIC](https://nvlabs.github.io/GEAR-SONIC/) tüm vücut dağıtım yığınının **decoder** yarısını `SonicWholeBodyController` olarak taşır. Artık eklemlere komut vermek yerine, politika her tik'te 64 boyutlu bir **latent hareket token'ı** (`motion_token.{i}.pos`) üretir; SONIC decoder'ı bu token'ı ve son zamanlardaki propriosepsiyon geçmişini, duruş pozuna ölçeklenerek eklenen bir kalan eyleme dönüştürür ve tüm 29 DoF için 50 Hz eklemler konum hedefleri oluşturur.

Kontrolcü, ONNX çözücüsünü ve tüm dağıtım sabitlerini (PD kazançları, `default_angles`, `action_scale` ve nötr token) [`lerobot/sonic_decoder`](https://huggingface.co/lerobot/sonic_decoder) konumundan yükler. Depo, ayrıca kontrolcünün `policy_type="low_latency"` argümanı ile seçilebilen damıtılmış düşük gecikmeli bir çözücü de içerir (varsayılan değer `"default"`'tir).

### Simülasyonda Test

SONIC hareket token'ları üzerinde eğitilmiş herhangi bir token-çıktı politikası (ör. [`nepyope/sonic_walk`](https://huggingface.co/nepyope/sonic_walk)) onu sürdürebilir:

```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}}'
```

### Fiziksel Robotta Çalıştır

[remote inference](./remote_inference) politikası sunucusunu GPU makinesinde çalıştırın ve robot köprüsünü, SONIC kodlayıcısını ve rollout istemcisini G1 Jetson üzerinde tutun. Ağ üzerinden yalnızca 64 boyutlu token parçaları geçer; kodlayıcı ve 50 Hz `rt/lowcmd` döngüsü cihaz üzerinde kalır.

Her iki makinede de uzak ekini kurun. G1'de Unitree ekini koruyun:

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

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

GPU makinesinde, politika sunucusunu depo kök dizininden başlatın. Bakımı yapılan profil `nepyope/sonic_walk` ile eşleşir; başka bir politika için kontrol noktasını ve özellik sözleşmesini birlikte kopyalayın ve güncelleyin.

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

G1'de köprü ve kamerayı çalışır durumda tutun:

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

Ardından `<GPU_MACHINE_IP>` değerini değiştirerek ikinci bir G1 terminalinde rollout istemcisini başlatın:

```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
```

G1 hareket için hazır olduğundan emin olduktan sonra yalnızca `/start` yazın. SONIC, son tam token'ın yeniden gönderilmesinin araç üzerindeki çözücü dengelemesini koruduğu için bekleme desteğini bildirir. İlk politika sonucu gelmeden önce, rollout çözücünün nötr token'ını gönderir. Eylem tamponu boşalırsa, son uygulanan token en fazla `action_starvation_grace_s` (yukarıda bir saniye) boyunca tekrarlanır; taze bir tahmin gelmezse rollout hataya düşer ve yapılandırılmış kapatma/ayrılma yolunu izler. Joystick hızlarının bu şekilde korunamaması nedeniyle G1 yürüme denetleyicileri desteklenmez.

Tarif, başlangıç konumuna dönüşü devre dışı bırakır: SONIC'in gizli token uzayında interpolasyon, doğrulanmış fiziksel bir ev konumu yörüngesi değildir. Aynı nedenle `/reset` komutundan kaçının, çünkü bu komut token'ı bağlantı anındaki değerine geri sardıracaktır. `/stop` komutu, uzak oturumu kapatmaya ve robotu normal denetleyici kapatma yolu üzerinden bağlantısını kesmeye devam eder.

`SonicWholeBodyController` ile gözlem durumu, 29 eklem konumu yerine 64 boyutlu token yankısıdır; bu nedenle uyumlu bir checkpoint, bu duruma karşı eğitilmiş olmalıdır. Bağlantı sırasında robot, denetleyici devralmadan önce eklemleri kodlayıcının `default_angles` değerlerine yumuşak bir şekilde getirir.

---

## Ek Kaynaklar

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

---

_Son güncelleme: Temmuz 2026_