Unitree G1 ile ROS 2: unitree_ros2, CycloneDDS ve Topic Yapısı

Üniversite ve Ar-Ge ekiplerinden en sık gelen soru şu: "G1 EDU geldi, ROS 2 ile nasıl konuşacağız?" Cevap, Unitree'nin resmi unitree_ros2 deposunda. Bu yazıda kurulumu, DDS ayarını, temel topic yapısını ve robota dokunmadan önce simülasyonda nasıl çalışılacağını adım adım anlatıyoruz. Komutların tamamı deponun README dosyasından alınmıştır; sürüm güncellendikçe resmi README'yi esas alın.

Neden ayrı bir sürücü yok? DDS mantığı

Unitree SDK2, CycloneDDS tabanlı bir haberleşme altyapısı kullanır. ROS 2 de altta DDS kullandığı için iki dünya aynı dili konuşur: ROS 2'nin RMW katmanını rmw_cyclonedds_cpp olarak ayarladığınızda robotun yayınladığı veriler ROS 2 topic'i olarak görünür. Bu yüzden unitree_ros2 bir "köprü düğümü" değil; robotun DDS mesaj tiplerini ROS 2 paketleri olarak (unitree_go, unitree_hg, unitree_api) tanımlayan bir çalışma alanıdır.

Mesaj ailesi robot modeline göre değişir. Go2, B2 ve H1 gibi robotlar unitree_go, Unitree G1 ve H1-2 ise unitree_hg mesajlarını kullanır. G1 ile çalışırken örnekleri seçerken bu ayrıma dikkat etmek gerekir.

Sistem gereksinimi ve kurulum

README'de test edilen kombinasyonlar Ubuntu 20.04 + ROS 2 Foxy ve Ubuntu 22.04 + ROS 2 Humble'dır; önerilen Humble'dır. Depo ayrıca .devcontainer klasöründe Docker geliştirme ortamı tanımları içerir; laboratuvarda çok sayıda öğrenci makinesi varsa ortak bir konteyner imajı kurulum farklarını azaltır.

Önce depoyu klonlayın:

git clone https://github.com/unitreerobotics/unitree_ros2

Bağımlılıklar README'de Foxy örneğiyle verilir ve başka bir sürüm için "foxy" yerine kendi dağıtımınızın adını yazmanız istenir. Humble için:

sudo apt install ros-humble-rmw-cyclonedds-cpp
sudo apt install ros-humble-rosidl-generator-dds-idl
sudo apt install libyaml-cpp-dev

README'ye göre Humble kullanıyorsanız CycloneDDS'i kaynaktan derleme adımı atlanabilir (robot tarafındaki CycloneDDS sürümü 0.10.2'dir; Foxy'de bu sürüm ayrıca derlenir). Ardından ROS 2 ortamını yükleyip çalışma alanını derleyin:

source /opt/ros/humble/setup.bash
colcon build

Ağ ayarı: robotla aynı alt ağda olmak

Robot ile bilgisayar Ethernet kablosuyla bağlanır. README, robotun bağlı olduğu arayüzde IPv4 adresini elle 192.168.123.99, maskeyi 255.255.255.0 yapmayı tarif eder. Ardından depodaki setup.sh dosyasında iki şey düzenlenir: ROS 2 dağıtımınızın setup dosyası ve CYCLONEDDS_URI içindeki ağ arayüzü adı (örnekteki "enp3s0" yerine kendi arayüzünüz). Dosyadaki "foxy" satırını Humble kullanıyorsanız güncellemeyi unutmayın.

source ~/unitree_ros2/setup.sh
ros2 topic list

Topic listesi geliyorsa bağlantı kurulmuştur. Laboratuvar pratiği olarak her öğrenci makinesinde arayüz adını ve IP'yi bir kontrol listesine yazmak, "topic görünmüyor" sorunlarının çoğunu baştan çözer.

Temel topic yapısı

• sportmodestate / lf/sportmodestate: Konum, hız, ayak konumu ve yürüyüş tipi gibi yüksek seviye hareket durumu ("lf" düşük frekanslı yayını ifade eder). Örnek program read_motion_state Go2/B2 içindir.
• lowstate / lf/lowstate: Motor durumları, IMU ve batarya bilgisi. G1 için read_low_state_hg örneği kullanılır.
• /wirelesscontroller: Kumanda joystick ve tuş durumları.
• /api/sport/request: Yüksek seviye hareket komutları istek/yanıt mantığıyla bu topic'e unitree_api Request mesajı olarak gönderilir.
• /lowcmd: Motor seviyesinde pozisyon, hız ve tork komutları. En riskli arayüzdür; ilk haftalarda kullanılmamalıdır.

Örnekleri derleyip ilk okuma programını çalıştırmak için:

source ~/unitree_ros2/setup.sh
cd ~/unitree_ros2/example
colcon build

./install/unitree_ros2_example/bin/read_motion_state

G1 tarafında depoda g1_low_level_example, g1_loco_client_example ve g1_arm_action_example gibi hedefler bulunur. Bunları çalıştırmadan önce kaynak kodu okuyun: hangi topic'e ne yazdığını bilmeden bir kontrol örneği başlatmak insansı robotta düşme riskidir.

Görselleştirme için README, Go2'nin LiDAR bulutunu utlidar/cloud topic'inden RViz2'de göstermeyi örnekler. G1'de sensör topic'leri konfigürasyona göre farklılık gösterebilir; ros2 topic list çıktısını esas alın.

Önce simülasyon: robotsuz çalışma

Robot bağlı değilken iki seçenek var. Birincisi depodaki setup_local.sh: ağ arayüzü olarak yerel döngüyü (lo) kullanır, böylece aynı makinedeki simülatörle konuşabilirsiniz.

source ~/unitree_ros2/setup_local.sh

İkincisi Unitree'nin unitree_mujoco simülatörü. README'sine göre unitree_sdk2, unitree_ros2 ve unitree_sdk2_python ile yazılmış kontrol programları bu simülatöre bağlanabilir; mevcut sürüm düşük seviye geliştirmeyi (LowCmd, LowState, SportModeState) destekler ve sim2real doğrulaması için tasarlanmıştır. Önerimiz net: öğrenciler her yeni düğümü önce MuJoCo'da, sonra askı (gantry) altındaki gerçek robotta çalıştırmalı.

Laboratuvarda sık yapılan hatalar

• Birden fazla ROS ortamı: setup.sh içeriğini .bashrc'ye eklemek pratik ama aynı makinede farklı ROS kurulumları varsa çakışma yaratır. README de buna dikkat çeker.
• Yanlış mesaj ailesi: G1'e unitree_go tabanlı bir Go2 örneğiyle yaklaşmak çalışmaz; unitree_hg örneklerinden başlayın.
• Yerleşik hareket servisiyle çakışma: Düşük seviye kontrol, robotun kendi hareket kontrolcüsüyle aynı anda komut vermemelidir. Resmi dokümantasyondaki mod geçiş adımlarını izleyin.
• Paylaşımlı ağ: Aynı alt ağda birden fazla robot veya simülatör varsa DDS trafiği karışabilir. Her istasyona ayrı ağ veya ayrı arayüz planlayın.

Sonraki adımlar

ROS 2 bağlantısı kurulduktan sonra iki yol açılır: Python ile hızlı prototip için unitree_sdk2_python rehberimiz, öğrenme tabanlı hareket kontrolü için Isaac Lab ile pekiştirmeli öğrenme yazımız. Donanım tarafını G1 EDU laboratuvar yazımızda anlattık. Kagen Akademi öğrenme portalında Python ve ROS 2 (rclpy ile topic/service) modülleri bulunur; kurumsal gruplar için G1 ve Go2 üzerinde uygulamalı atölye planlanabilir. Teklifi etkileyen unsurlar için G1 EDU fiyat ve Go2 EDU fiyat sayfalarına göz atabilirsiniz.

Sık sorulan sorular

unitree_ros2 hangi ROS 2 sürümünü destekliyor?

README'de Ubuntu 20.04 + Foxy ve Ubuntu 22.04 + Humble test edilmiştir; önerilen Humble'dır.

unitree_ros2 neden CycloneDDS istiyor?

Unitree robotları CycloneDDS ile haberleşir. RMW katmanı rmw_cyclonedds_cpp olduğunda ROS 2 mesajlarıyla robot doğrudan dinlenip kontrol edilebilir.

G1 için hangi mesaj paketi kullanılır?

G1 ve H1-2 unitree_hg, Go2/B2/H1 unitree_go mesajlarını kullanır. G1 için read_low_state_hg ve g1_low_level_example örnekleri vardır.

Robot olmadan unitree_ros2 ile çalışabilir miyim?

Evet. setup_local.sh yerel döngü arayüzünü kullanır; unitree_mujoco simülatörü de unitree_ros2 programlarını çalıştırabilir.