Unitree SDK &
Yazılım Rehberi.
Unitree'nin resmi unitree_sdk2 kütüphanesiyle Go2, B2, G1, H1/H2 ve R1 robotlarını C++ ve Python'dan programlama kılavuzu: kurulum ve derleme, DDS haberleşme mimarisi, SportClient/LocoClient API'leri, sürüm uyumluluğu ve saha deneyimiyle yazılmış sorun giderme tablosu.
Hızlı Başlangıç — 4 Adımda Unitree Geliştirme
Bağlantı kurulumu
Robotu kablolu Ethernet ile geliştirme bilgisayarınıza bağlayın. Robot 192.168.123.161 sabit IP'sindedir; PC'nize aynı alt ağda statik IP verin.
SDK2 kurulumu
Python: pip install unitree-sdk2py veya C++: CMake ile unitree_sdk2 deposunu derleyin. CycloneDDS otomatik yapılandırılır.
İlk komut
high_level örneğini çalıştırarak robotu ayağa kaldırın ve temel yürüme komutu gönderin. SDK örnekleri tüm modeller için hazırdır.
ROS2 ekosistemi (opsiyonel)
unitree_ros2 paketlerini workspace'inize klonlayın, colcon build ile derleyin ve Rviz'de robotu görselleştirin.
Unitree SDK2 (Python / C++)
Unitree'nin resmi ikinci nesil SDK'sı unitree_sdk2, Go2'den H2'ye tüm yeni platform serisini destekler. CycloneDDS tabanlı yayınla/abone ol haberleşme katmanı üzerinden yüksek seviye kontrol, sensör okuma ve eklem seviyesi komut gönderimi mümkündür; ROS kurulumu gerektirmez.
ÖNE ÇIKAN ÖZELLİKLER
- 1Python & C++ API: Yürüme, koşma, zıplama ve özel hareketler için yüksek seviye fonksiyonlar
- 2Low-level kontrol: Eklem pozisyon, hız ve tork modu ile doğrudan motor kontrolü
- 3Sensör okuma: IMU, LiDAR, kamera ve ayak temas sensörlerinden gerçek zamanlı veri akışı
- 4Çoklu robot: Tek ağ üzerinde birden fazla Unitree robotu eşzamanlı kontrol
ROS2 Entegrasyonu
Unitree robotları Ubuntu + ROS2 (Humble / Iron) ekosistemiyle sorunsuz çalışır. EDU varyantları doğrudan ROS2 düğümleri olarak başlatılabilir; araştırma ve otonom navigasyon pipeline'ları için idealdir.
ÖNE ÇIKAN ÖZELLİKLER
- 1unitree_ros2 paketleri: URDF modelleri, Rviz görselleştirme ve topic yayını
- 2Nav2 uyumluluğu: SLAM Toolbox ve Nav2 ile otonom haritalama ve navigasyon
- 3Özel mesaj tipleri: Unitreeye özgü eklem durumu ve komut mesajları
- 4sim-to-real: Simülasyon ortamında eğitilen politikaları doğrudan robota aktarma
NVIDIA Isaac Gym & Sim Ortamları
Unitree quadruped modelleri, NVIDIA Isaac Gym (Orbit), MuJoCo ve Gazebo gibi önde gelen simülasyon ortamlarında desteklenir. GPU hızlandırmalı paralel simülasyon ile binlerce ortamda policy eğitimi yapılabilir.
ÖNE ÇIKAN ÖZELLİKLER
- 1Isaac Gym / Orbit: GPU paralel RL eğitimi ile quadruped locomotion politikası
- 2MuJoCo: Hassas fizik simülasyonu ve contact-rich manipülasyon deneyleri
- 3Gazebo Classic & Ignition: ROS2 entegre tam simülasyon ortamı
- 4sim-to-real transfer: Simülasyonda eğitilen modellerin gerçek robotta doğrulanması
Jetson & Edge AI Geliştirme
Unitree'nin üst düzey modelleri NVIDIA Jetson platformları (Orin, AGX Thor) ile donatılmıştır. Yerel LLM çalıştırma, 3D algılama ve semantic SLAM gibi gelişmiş AI görevleri edge cihazda gerçekleştirilebilir.
ÖNE ÇIKAN ÖZELLİKLER
- 1Jetson Orin (100 TOPS): G1 üzerinde 3D semantic perception ve nesne tanıma
- 2Jetson AGX Thor (2070 TOPS): H2 EDU üzerinde büyük dil modeli (LLM) çalıştırma
- 3TensorRT & CUDA: DNN modellerinin edge optimizasyonu ve gerçek zamanlı inferans
- 4Isaac ROS: NVIDIA'nın hazır algılama ve navigasyon pipeline'ları
unitree_sdk2 (C++) — Kurulum, Derleme ve İlk Program
C++ SDK, gerçek zamanlı kontrol ve Jetson üzerinde gömülü dağıtım için tercih edilen yoldur. Çekirdek kütüphane x86_64 ve aarch64 için önceden derlenmiş statik kütüphane olarak gelir; resmi test ortamı Ubuntu 20.04 LTS, GCC 9.4, CMake ≥ 3.10'dur. Kurulum öneki olarak /opt/unitree_robotics kullanmak, unitree_ros2 ve unitree_mujoco gibi ekosistem paketlerinin SDK'yı otomatik bulmasını sağlar.
1 — Sistem Bağımlılıkları
2 — Derleme & Kurulum
3 — Kendi Projenize Bağlama
# CMakeLists.txt — kendi projeniz cmake_minimum_required(VERSION 3.10) project(ilk_sdk2_uygulamam) # /opt/unitree_robotics'e kurduysaniz: list(APPEND CMAKE_PREFIX_PATH "/opt/unitree_robotics") find_package(unitree_sdk2 REQUIRED) add_executable(go2_yuru main.cpp) target_link_libraries(go2_yuru unitree_sdk2)
4 — İlk Program: SportClient ile Yürüyüş
// main.cpp — Go2'yi dengeli durusta 0.3 m/s ileri yurutur
#include <unistd.h>
#include <unitree/robot/channel/channel_factory.hpp>
#include <unitree/robot/go2/sport/sport_client.hpp>
int main(int argc, char** argv) {
// argv[1]: robota kablolu bagli ag arayuzu (or. enp2s0)
unitree::robot::ChannelFactory::Instance()->Init(0, argv[1]);
unitree::robot::go2::SportClient sport;
sport.SetTimeout(10.0f);
sport.Init();
// DIKKAT: StandUp() eklem-kilitli durustur, Move() bu modda calismaz.
// Hiz komutlari dengeli durus (BalanceStand) modunda calisir;
// sport servisi acilista robotu zaten bu modda baslatir.
sport.BalanceStand(); // dengeli durus — surulebilir mod
sleep(1);
sport.Move(0.3f, 0.0f, 0.0f); // vx, vy, vyaw
sleep(2);
sport.StopMove(); // dur
sport.StandDown(); // cok
return 0;
}Depodaki example/ klasöründe her robot için hazır örnekler bulunur: go2 (sport, low-level, video, VUI), g1 (loco, audio, dex3 el), h1, h2, b2, go2w, a2 ve r1. example/cmake_sample klasörü, kurulu SDK'yı tüketen referans projedir.
DDS Mimarisi — ChannelFactory, Topic'ler ve IDL
SDK2'nin temelinde Eclipse CycloneDDS yayınla/abone ol katmanı yatar. Programınız ChannelFactory::Instance()->Init(0, "enp2s0") çağrısıyla DDS'i robota kablolu bağlı ağ arayüzüne bağlar; sonrasında tüm veri akışı adlandırılmış topic'ler üzerinden gerçekleşir. Mesaj tipleri IDL ile tanımlıdır: dört ayaklılar unitree_go, insansılar unitree_hg ad alanını kullanır. ROS 2 uyumlu tip tanımları sayesinde CycloneDDS RMW kullanan bir ROS 2 düğümü, robotun native topic'lerine köprü yazılımı olmadan doğrudan abone olabilir.
| Topic | Yön | İçerik |
|---|---|---|
| rt/lowstate | Robottan | Eklem pozisyon/hız/tork verileri, IMU, batarya durumu ve kablosuz kumanda baytları — tüm düşük seviye durum |
| rt/lowcmd | Robota | Düşük seviye eklem komutları (q, dq, tau, kp, kd). CRC damgası zorunlu, yüksek frekansta sürekli yayınlanır |
| rt/sportmodestate | Robottan | Yüksek seviye hareket durumu: mod, gövde pozu, hız (Go2/B2 ailesi) |
| rt/wirelesscontroller | Robottan | El kumandasının buton ve joystick verileri |
| rt/api/… | Çift yönlü | Servis istemcilerinin (SportClient, LocoClient…) istek/yanıt kanalları |
| rt/arm_sdk | Robota | G1'de lokomosyon sürerken kol eklemlerinin doğrudan kontrolü |
Ağ modeli: Robotun kontrol kartı, dahili anahtar ağında 192.168.123.161 sabit IP'sindedir. Geliştirme bilgisayarınıza aynı alt ağda statik bir IP verin (ör. 192.168.123.99) ve kablolu Ethernet kullanın — Wi-Fi üzerinden DDS keşfi desteklenen yol değildir.
Yüksek Seviye API — Servis İstemcileri
SDK2, DDS üzerine kurulu istek/yanıt tarzı servis istemcileri sunar. Hangi istemcinin hangi robotta hangi işi yaptığını bilmek, doğru API'yi seçmenin en kısa yoludur:
| İstemci | Robotlar | Görev |
|---|---|---|
| SportClient | Go2/Go2-W · B2/B2-W | Yüksek seviye lokomosyon: StandUp, Move(vx, vy, vyaw), BalanceStand, Euler poz kontrolü, yörünge takibi ve özel hareketler |
| LocoClient | G1 · H1 · H2 | İnsansı yürüme FSM'i: damp, ayağa kalkma, dengede durma, yürüme hız komutları ve duruş/yükseklik ayarı |
| MotionSwitcherClient | Go2/B2 ailesi | Aktif hareket servisini sorgulama, seçme ve bırakma — low-level kontrol öncesi ReleaseMode zorunlu adımdır |
| RobotStateClient | Go2 · B2 | Robot üzerindeki servisleri listeleme, durum sorgulama, başlatma/durdurma (ör. sport_mode'u kapatmak) |
| VideoClient | Go2 · B2 | Dahili kameradan SDK API'siyle görüntü alma (ayrı GStreamer hattı kurmadan) |
| ObstaclesAvoidClient | Go2 | Yerleşik engelden kaçınma modunu açma/kapatma ve kaçınma katmanından geçen hareket komutları |
| VuiClient | Go2 | Kafa LED'i renk/parlaklık ve hoparlör ses seviyesi kontrolü |
| AudioClient | G1 | TTS ses sentezi, ses seviyesi ve RGB LED kontrolü |
| arm_sdk / Dex3 | G1 (+ Dex3-1 eller) | Hazır kol jestleri, lokomosyon sürerken doğrudan kol eklem kontrolü ve üç parmaklı hassas el kontrolü |
Python SDK — Kurulum & Örnek Komutlar
unitree_sdk2_python paketi, C++ SDK2 ile tam uyumlu bir Python arayüzü sunar. DDS topic haberleşmesinden düşük seviye motor kontrolüne, kamera erişiminden engel kaçınmaya kadar tüm özellikler Python'dan kullanılabilir. Bağımlılıklar: Python ≥ 3.8, cyclonedds 0.10.2, numpy, opencv-python.
Kaynak Kurulum
CycloneDDS Path Hatası Çözümü
Kullanım Örnekleri — enp2s0 yerine robotun bağlı olduğu ağ arayüzünü yazın
python3 ./example/helloworld/publisher.pypython3 ./example/helloworld/subscriber.pypython3 ./example/high_level/read_highstate.py enp2s0python3 ./example/high_level/sportmode_test.py enp2s0python3 ./example/low_level/low_state.py enp2s0python3 ./example/low_level/lowlevel_control.py enp2s0python3 ./example/wireless_controller/wireless_controller.py enp2s0python3 ./example/front_camera/camera_opencv.py enp2s0python3 ./example/obstacles_avoid_switch/obstacles_avoid_switch.py enp2s0python3 ./example/vui_client/vui_client_example.py enp2s0Ağ bağlantısı kurulumu ve robot IP yapılandırması için Unitree Hızlı Başlangıç Kılavuzu'nu inceleyin. Sportmode test örneğinde test.StandUpDown(), test.VelocityMove() ve test.TrajectoryFollow() metodlarından birini yorumdan çıkararak çalıştırabilirsiniz.
Sürüm & Firmware Uyumluluğu
unitree_sdk2'de en kritik kural: SDK majör sürümü, robotunuzun hareket kontrol firmware nesliyle eşleşmelidir. Yanlış nesil SDK ile yüksek seviye API çağrıları hata döndürür.
B2 için Euler gövde-poz arayüzü eklendi. Entegre hareket servisi firmware'li tüm robotlar için güncel sürüm.
Entegre hareket kontrol firmware'i çalıştıran Go2 desteği; HandStand çağrısı hatası düzeltildi.
Eski (entegre olmayan) hareket kontrol servisiyle gelen robotlar için. Yeni firmware'de v2.x kullanılmalıdır.
A2, AS2, H2 ve R1 dahil en yeni robot klasörleri; sürüm etiketlerinden sonra eklenen örnekler burada.
Hangi Arayüzü Seçmeliyim?
Aynı robota dört farklı yoldan bağlanabilirsiniz; doğru seçim projenizin gereksinimine bağlıdır. Reinforcement learning policy'lerini sahaya taşımak içinse RL Gym rehberimize bakın.
unitree_sdk2 (C++)
En uygun olduğu yer
Gerçek zamanlı düşük seviye kontrol, Jetson üzerinde gömülü dağıtım, ürünleşmiş saha projeleri
Önceden derlenmiş statik kütüphane (x86_64 / aarch64), en düşük gecikme, CRC'li LowCmd erişimi. Resmi test ortamı Ubuntu 20.04 + GCC 9.4.
GitHub deposuunitree_sdk2_python
En uygun olduğu yer
Hızlı prototipleme, araştırma, eğitim ve veri toplama scriptleri
Saf Python + cyclonedds 0.10.2. C++ ile aynı istemcileri sunar; bu sayfadaki kurulum bölümüyle 10 dakikada çalışır hale gelir.
GitHub deposuunitree_ros2
En uygun olduğu yer
Nav2 / SLAM yığını, mevcut ROS 2 altyapısına entegrasyon
CycloneDDS RMW ile robotun native DDS topic'lerine köprüsüz abone olursunuz; URDF, Rviz ve Nav2 ekosistemi hazır gelir.
GitHub deposuWebRTC bağlantısı
En uygun olduğu yer
SDK gerektirmeyen uzak bağlantı; standart (EDU olmayan) modellerde erişim
Resmi uygulamanın WebRTC protokolü üzerinden Go2/G1 bağlantısı. Ayrıntılı kurulum için WebRTC rehberimize bakın.
WebRTC RehberiSık Karşılaşılan Hatalar ve Çözümleri
Aşağıdaki tablo, ekibimizin kurulumlarda ve müşteri projelerinde en sık karşılaştığı SDK2 sorunlarını ve doğrulanmış çözümlerini özetler:
| Belirti | Olası Neden | Çözüm |
|---|---|---|
| channel factory init error | ChannelFactory'ye yanlış ağ arayüzü adı verildi veya IP yapılandırması eksik | Robota fiziksel bağlı NIC adını verin (ip a ile kontrol edin); PC'ye 192.168.123.0/24 içinde statik IP atayın |
| DDS keşfi yok, hiç veri gelmiyor | Wi-Fi üzerinden bağlanma denemesi | Kablolu Ethernet kullanın — DDS keşfi için desteklenen yol budur; robot 192.168.123.161 adresindedir |
| pip cyclonedds kurulumu başarısız (özellikle Jetson/aarch64) | Hazır cyclonedds paketi platformunuz için native kütüphaneyi bulamıyor | CycloneDDS'i releases/0.10.x dalından kaynak derleyin, CYCLONEDDS_HOME'u ihraç edip pip kurulumunu tekrarlayın |
| ROS 2 kurulu makinede Python SDK bozuluyor | SDK cyclonedds==0.10.2'ye sabitli; ROS 2 dağıtımları 0.10.5+ taşır | SDK'yı ayrı bir sanal ortamda kurun ve derleme/çalıştırma terminalinde ROS 2 ortamını source etmeyin |
| Low-level komutlar yok sayılıyor | Yerleşik sport/AI hareket servisi hâlâ aktif ve komutlarınızla çakışıyor | Önce MotionSwitcherClient.ReleaseMode çağırın veya RobotStateClient ile sport_mode servisini durdurun |
| Robot low-level komutta titriyor / sarsılıyor | Agresif kp/kd kazançları veya CRC damgası eksik LowCmd | kp≈10, kd≈1 ile başlayın; her komut döngüsünde CRC hesaplayın ve komutu kesintisiz yayınlayın |
| Yüksek seviye API çağrıları hata döndürüyor | SDK sürümü robot firmware nesliyle uyumsuz (v1.0.0 ↔ v2.x) | Firmware'inize uygun SDK sürümüne geçin; sürüm tablosuna bakın veya bize danışın |
Güvenlik notu: Düşük seviye eklem kontrolü, robotun tüm yerleşik korumalarını devre dışı bırakır. İlk testleri robotu askıya alarak veya geniş, boş bir alanda yapın; muhafazakâr kazançlarla başlayın (kp≈10, kd≈1), acil durdurmayı elinizin altında tutun ve komut döngünüz kesildiğinde robotun damping moduna düşeceğinden emin olun. Kurumsal kurulumlarda bu güvenlik katmanlarını müşterilerimiz için biz yapılandırıyoruz.
Bu rehber, unitree_sdk2'yi sahada kullanan ekip tarafından yazıldı.
Robotlar.org mühendislik ekibi; müşteri projelerinde unitree_sdk2 üzerinden dört ayaklı platformlarda otonom navigasyon ve uzaktan komuta sistemleri, insansı robotlarda kol ve el kontrolü geliştirip sahaya kuruyor. Bu sayfadaki sorun giderme tablosu ve güvenlik pratikleri, o kurulumlardan damıtılmış gerçek deneyimdir.
Sıkça Sorulan Sorular
unitree_sdk2 hangi robotları destekler?
unitree_sdk2, Unitree'nin yeni nesil platformlarının tamamını destekler: Go2 ve Go2-W (tekerlekli), B2 ve B2-W, A2, AS2 dört ayaklılar ile G1, H1, H2 ve R1 insansı robotlar. Depoda her model için ayrı örnek klasörü bulunur; dört ayaklılar unitree_go, insansılar unitree_hg IDL mesaj ailesini kullanır. Eski nesil robotlar (Go1, Aliengo, B1) ise önceki unitree_legged_sdk ile programlanır.
unitree_sdk2 (C++) ile unitree_sdk2_python arasındaki fark nedir?
İkisi de aynı DDS arayüzünü ve aynı servis istemcilerini (SportClient, LocoClient, MotionSwitcherClient...) sunar. C++ SDK, x86_64 ve aarch64 için önceden derlenmiş statik kütüphaneyle gelir; gerçek zamanlı düşük seviye kontrol, Jetson üzerinde gömülü dağıtım ve ürünleşmiş projeler için tercih edilir. Python SDK ise saf Python + cyclonedds bindingi ile hızlı prototipleme, araştırma ve eğitim için idealdir. Aynı robotta ikisini birlikte de kullanabilirsiniz.
SDK2 kullanmak için ROS kurulumu gerekli mi?
Hayır. unitree_sdk2 doğrudan DDS (CycloneDDS) üzerinden robotla haberleşir; ROS'suz bağımsız çalışır. ROS 2 yığını kullanmak isterseniz unitree_ros2 paketleri, CycloneDDS RMW ile robotun native topic'lerine doğrudan abone olmanızı sağlar. Dikkat: aynı makinede ROS 2 kuruluysa CycloneDDS sürüm çakışması yaşanabilir — Python SDK cyclonedds 0.10.2'ye sabitlenmiştir, ROS 2 dağıtımları ise 0.10.5+ taşır.
Robota bağlanamıyorum, 'channel factory init error' ne anlama geliyor?
Bu hata neredeyse her zaman yanlış ağ arayüzü adının verilmesinden veya IP yapılandırmasından kaynaklanır. Robotun kontrol kartı 192.168.123.161 sabit IP'sindedir; bilgisayarınıza aynı alt ağda statik bir IP (ör. 192.168.123.99) tanımlayıp robota kablolu Ethernet ile bağlanmalı ve ChannelFactory'ye robota fiziksel olarak bağlı arayüzün adını (ör. enp2s0) vermelisiniz. Wi-Fi üzerinden DDS keşfi desteklenen yol değildir.
Düşük seviye (low-level) eklem kontrolünde nelere dikkat etmeliyim?
Önce robottaki yerleşik yüksek seviye hareket servisini bırakmanız gerekir (MotionSwitcherClient.ReleaseMode veya RobotStateClient ile sport_mode servisini durdurmak); aksi halde yerleşik denetleyici sizin komutlarınızla çakışır. LowCmd mesajları her döngüde CRC ile damgalanmalı ve sürekli yayınlanmalıdır. İlk testlerde muhafazakâr kazançlarla başlayın (kp≈10, kd≈1), robotu askıya alın veya boş ve güvenli bir alanda çalışın, acil durdurmayı hazır tutun.
unitree_sdk2 kodum simülasyonda çalışır mı?
Evet. unitree_mujoco simülatörü, gerçek robotla aynı DDS arayüzünü sunar; SDK2 ile yazdığınız program tek satır değişmeden hem simülasyonda hem gerçek robotta çalışır. Isaac Lab tabanlı unitree_sim_isaaclab da benzer bir akış sağlar. Algoritmanızı önce simülasyonda doğrulayıp sonra sahaya çıkmak, hem güvenli hem hızlı bir geliştirme döngüsüdür.
SDK sürümü ile robot firmware'i arasındaki uyum neden önemli?
unitree_sdk2'nin v1.0.0 sürümü eski (entegre olmayan) hareket kontrol firmware'ini, v2.x sürümleri ise yeni entegre hareket servisi firmware'ini hedefler. Yanlış nesil SDK ile yüksek seviye API çağrıları hata döndürür. Robotunuzun firmware sürümüne uygun SDK sürümünü kullanın; emin değilseniz teslimat sırasında ekibimiz doğru eşleşmeyi yapılandırıyor.
Türkiye'de unitree_sdk2 kurulum ve geliştirme desteğini kim veriyor?
Robotlar.org mühendislik ekibi, Türkiye'deki Unitree kullanıcılarına SDK kurulumu, ağ yapılandırması, örneklerin çalıştırılması, ROS 2 entegrasyonu ve özel uygulama geliştirme desteği sağlar. Ekibimiz müşteri projelerinde unitree_sdk2 ile otonom navigasyon, teleoperasyon ve komuta/görev planlama panelleri geliştirip sahaya kuruyor. Eğitim kurumları için atölye ve müfredat desteği de sunuyoruz.
Resmi Kaynaklar & Topluluk
unitree_sdk2 (GitHub)
Resmi C++ SDK deposu: örnekler, IDL tanımları ve sürüm notları.
Unitree Docs
Resmi SDK dokümantasyonu, API referansı ve kurulum kılavuzları.
GitHub — Türkiye Partneri
Unitree Türkiye Yetkili Distribütörü & PUDU Resmi Partneri: H2 konfigürasyonu, kurulum kılavuzları ve yerel entegrasyon örnekleri.
Unitree Community
Resmi geliştirici forumu: soru-cevap, paylaşım ve duyurular.
robotlar.org Destek
Türkiye'de SDK kurulumu, entegrasyon ve teknik danışmanlık.
Unitree Geliştirme Desteği
Türkiye'de.
SDK kurulumu, ROS2 entegrasyonu veya özel uygulama geliştirme için Türkiye'deki Unitree teknik ekibimizden destek alın.