Unitree SDK2 Python ile İlk Adımlar: Kurulum, Örnekler, Güvenlik

ROS 2 kurmadan, birkaç satır Python ile robottan veri okumak ve basit hareket komutları göndermek istiyorsanız başlangıç noktası unitree_sdk2_python. Bu yazı, deponun README'sini ve örnek klasörlerini temel alarak ilk haftanın yol haritasını çıkarıyor. Ağırlık kurulumda değil, güvenli çalışma alışkanlığında.

Ne işe yarar, ne işe yaramaz?

unitree_sdk2_python, C++ tabanlı unitree_sdk2 ile aynı arayüz mantığını Python'a taşır: robot durumu topic aboneliğiyle okunur, kontrol istek/yanıt (request-response) veya topic yayınıyla yapılır. Yani ROS 2'deki gibi aynı DDS mesajlarıyla çalışırsınız ama ROS kurulumu gerekmez. Bu, ders laboratuvarlarında ve kısa projelerde büyük kolaylık sağlar.

Sınırı da bilmek gerekir: navigasyon yığını, RViz görselleştirmesi ve çok düğümlü bir sistem kuracaksanız unitree_ros2 daha doğru araçtır. Python SDK ise betik yazma, veri kaydı ve öğrenilmiş politikaların gerçek robota aktarılması (örneğin unitree_rl_gym'in fiziksel dağıtım adımı) için tercih edilir.

Kurulum

README'deki bağımlılıklar: Python 3.8 veya üzeri, cyclonedds 0.10.2, numpy ve opencv-python. Kaynaktan kurulum:

cd ~
sudo apt install python3-pip
git clone https://github.com/unitreerobotics/unitree_sdk2_python.git
cd unitree_sdk2_python
pip3 install -e .

En sık görülen hata, kurulum sırasında Could not locate cyclonedds mesajıdır. README'deki çözüm, CycloneDDS'in releases/0.10.x dalını kaynaktan derleyip kurmak ve ardından kurulum yolunu göstermektir:

cd ~/unitree_sdk2_python
export CYCLONEDDS_HOME=~/cyclonedds/install
pip3 install -e .

Laboratuvar önerisi: Her öğrenciye ayrı bir sanal ortam (venv veya conda) açtırın. Aynı makinede LeRobot veya Isaac Lab gibi farklı Python sürümü isteyen projeler olacaksa ortamları baştan ayırmak sonradan saatler kazandırır.

İlk test: robotsuz DDS haberleşmesi

Robotu bağlamadan önce DDS'in çalıştığını aynı makinede iki terminalle doğrulayın:

python3 ./example/helloworld/publisher.py

python3 ./example/helloworld/subscriber.py

Aktarılan veri yapısı user_data.py dosyasında tanımlıdır; öğrencilerin kendi mesaj yapılarını tanımlamayı burada denemesi, DDS kavramını somutlaştırmak için iyi bir ilk ödevdir.

Robota bağlanmak ve model bazlı örnekler

Robotla çalışmadan önce ağ bağlantısını Unitree'nin resmi geliştirici dokümantasyonundaki hızlı başlangıç adımlarına göre yapılandırın. Örnek programlar argüman olarak robotun bağlı olduğu ağ arayüzünün adını alır (README'deki örnekte enp2s0). Kod tarafında bu, ChannelFactoryInitialize çağrısına arayüz adının verilmesiyle olur.

Depodaki example klasörü artık robot modeline göre ayrılmış durumda: go2, g1, b2, b2w, go2w, h1, h1_2, h2, r1, a2 ve as2 alt klasörleri var. Örneğin Go2 için example/go2/high_level/go2_sport_client.py, G1 için example/g1/high_level/g1_loco_client_example.py bulunur. README'nin bazı bölümlerinde eski klasör yolları geçebilir; çalıştırmadan önce depodaki güncel yolu kontrol edin.

G1 örnek klasöründeki not önemli: unitree_go IDL'i Go2/B2/H1/B2w/Go2w için, unitree_hg IDL'i G1/H1-2 için kullanılır. G1 loco örneği, sönümleme (damp), çömelmeden ayağa kalkma, ileri ve yanal hareket, el sallama gibi test seçeneklerini terminalden seçtirir ve başlarken robotun etrafında engel olmaması gerektiği uyarısını basar.

Robota bağımlı olmayan, düşük riskli bir başlangıç örneği kumanda durumunu okumaktır:

python3 ./example/wireless_controller/wireless_controller.py enp2s0

Güvenlik: yüksek seviye ile düşük seviye arasındaki çizgi

SDK iki katmanda çalışır ve risk seviyeleri çok farklıdır:

• Yüksek seviye (sport/loco client): Robotun kendi denge ve yürüme kontrolcüsü çalışır; siz hız veya duruş komutu verirsiniz. İlk dönem bu katmanda kalın.
• Düşük seviye (lowcmd): Motorlara doğrudan pozisyon, hız, tork ve kazanç (kp, kd) komutu verilir. README'ye göre bu modda önce uygulamadan yüksek seviye hareket servisi kapatılmalıdır; aksi halde komutlar çakışır. README'deki düşük seviye örnekte güvenlik için kp=10, kd=1 gibi düşük kazançlar seçildiği özellikle belirtilir.

Laboratuvar kuralı olarak önerdiğimiz minimum set:

1. Her yeni betik önce unitree_mujoco simülasyonunda çalıştırılır (simülatörün Python sürümü simulate_python klasöründedir).
2. İnsansı robotta düşük seviye testler askı (gantry) altında yapılır; robot zemine ancak politika askıda doğrulandıktan sonra indirilir.
3. Kumanda ve acil durdurma yetkisi her zaman betiği çalıştırandan farklı bir kişidedir.
4. Komut gönderen her betikte hız ve açı limitleri kodun en başında sabit olarak tanımlanır.

Dört haftalık ders planı önerisi

• 1. hafta: Kurulum, sanal ortam, helloworld ile DDS kavramı.
• 2. hafta: Robot durumunu okuma ve kaydetme (IMU, eklem açıları, batarya), veriyi CSV'ye yazma.
• 3. hafta: Yüksek seviye hareket: ayağa kalkma, hız komutu, basit rota.
• 4. hafta: Simülasyonda düşük seviye kontrol, tek eklem pozisyon tutma; gerçek robotta sadece eğitmen gözetiminde.

Kagen Akademi öğrenme portalındaki Python ve ROS 2 kursları bu plana zemin hazırlar; kurumsal gruplar için Go2 EDU ve G1 EDU üzerinde uygulamalı atölye düzenlenebilir. EDU sürümünün teklifini neyin belirlediğini Go2 EDU fiyat ve G1 EDU fiyat sayfalarında özetledik.

Sık sorulan sorular

unitree_sdk2_python hangi Python sürümünü gerektirir?

Python 3.8 veya üzeri; bağımlılıklar cyclonedds 0.10.2, numpy ve opencv-python.

Could not locate cyclonedds hatası nasıl çözülür?

CycloneDDS 0.10.x kaynaktan derlenip kurulur, CYCLONEDDS_HOME kurulum klasörüne ayarlanır ve pip3 install -e . tekrar çalıştırılır.

Python SDK ile ROS 2 arasında nasıl seçim yapmalı?

Hızlı prototip ve veri betikleri için Python SDK; navigasyon, RViz ve çok düğümlü sistemler için ROS 2.

Düşük seviye kontrol örneklerini doğrudan çalıştırmak güvenli mi?

Hayır. Hareket servisi kapatılmalı, robot askıda olmalı ve kod önce simülasyonda denenmelidir.