Unitree Go2 ve G1 WebRTC Bağlantısı —
Jailbreak Yok, Firmware Değişikliği Yok.
unitree_webrtc_connect, Unitree Go2 ve G1 robotlarını resmi Unitree Go / Unitree Explore mobil uygulamalarının kullandığı AYNI WebRTC protokolüyle Python'dan kontrol eden MIT lisanslı açık kaynak sürücüdür. Veri kanalı (pub/sub, RPC), sport/kol kontrolü ve video akışı her iki modelde; ses, LiDAR nokta bulutu, VUI, AudioHub, engelden kaçınma API'si ve multicast keşif ise şu an yalnızca Go2'de desteklenir.
Not: Bu kütüphane resmi bir Unitree ürünü değildir; topluluk kaynaklı, tersine mühendislik temelli bir açık kaynak projedir (RoboLegion / legion1581). GitHub'da 349 yıldız, 114 fork — 2 Temmuz 2026 itibarıyla. Güncel PyPI sürümü: 2.1.2 (17 Mayıs 2026).
unitree_webrtc_connect Nedir?
Resmi Unitree mobil uygulamaları (Unitree Go / Unitree Explore), robota WebRTC üzerinden bağlanır: sinyalleşme LAN'da veya Unitree bulutu üzerinden yapılır, komutlar bir data channel'dan (pub/sub + RPC), görüntü ise WebRTC video track'inden akar. unitree_webrtc_connect bu protokolü Python'a taşır — robotta hiçbir değişiklik yapmadan, jailbreak veya firmware modifikasyonu olmadan, mobil uygulamanın yapabildiği her şeyi koddan yapmanızı sağlar.
Bu yaklaşımın pratik değeri şudur: resmi Unitree SDK'sı (DDS tabanlı) robotun dahili ağına doğrudan erişim gerektirirken, WebRTC sürücüsü standart WiFi bağlantısı üzerinden çalışır ve Unitree'nin TURN rölesi sayesinde internet üzerinden uzaktan kontrole de imkân verir. Desteklenen modeller: Go2 (AIR / PRO / EDU) ve G1 (AIR / EDU).
Firmware ve Kimlik Doğrulama Matrisi
Bağlantı kimlik doğrulaması, robotun LAN sinyalleşme el sıkışmasında (con_notify) döndürdüğü data2 alanına göre iki nesle ayrılır: data2=2 (statik GCM anahtarı, kütüphane otomatik halleder) ve data2=3 (cihaza özel AES-128 anahtarı, sizin sağlamanız gerekir).
| Robot | Firmware | Kimlik Doğrulama | Anahtar |
|---|---|---|---|
| Go2 | 1.0.19 – 1.0.25 | data2=2 | Statik GCM (otomatik) |
| Go2 | 1.1.1 – 1.1.14 | data2=2 | Statik GCM (otomatik) |
| Go2 | 1.1.15+ | data2=3 | Cihaza özel AES-128 (sizden) |
| G1 | 1.2.0 – 1.4.5 | data2=2 | Statik GCM (otomatik) |
| G1 | 1.5.1+ | data2=3 | Cihaza özel AES-128 (sizden) |
Kaynak proje, listelenen aralıkların dışında kalan ara firmware sürümleri (örn. Go2 1.0.26–1.1.0, G1 1.4.6–1.5.0) için hangi data2 değerinin döndüğünü belgelememiştir. Bu aralıktaki bir cihazla çalışıyorsanız data2 değerini bağlantı denemesinde gözlemleyin veya firmware'i listelenen bir sürüme güncelleyin.
Özellik Matrisi: Go2 vs G1
Kütüphanenin güncel sürümünde Go2 desteği belirgin şekilde daha geniştir. Model seçimi yaparken bu tabloyu dikkate alın:
| Özellik | Go2 | G1 |
|---|---|---|
| Data channel (pub/sub, RPC) | ||
| Sport / kol-aksiyon kontrolü | ||
| Video akışı (alma) | ||
| Ses akışı (gönderme/alma) | ||
| LiDAR nokta bulutu çözümleme | ||
| VUI (LED, parlaklık, ses) | ||
| AudioHub (ses dosyası yönetimi) | ||
| Engelden kaçınma API'si | ||
| Multicast cihaz keşfi (seri no ile) | ||
| data2=3 cihaza özel anahtar doğrulama |
Kurulum
Debian/Ubuntu tabanlı sistemlerde pip ve ses işleme bağımlılığı (portaudio19-dev) gereklidir. PyPI paketi önerilen yoldur:
sudo apt update
sudo apt install -y python3-pip portaudio19-dev
pip install unitree_webrtc_connect
# veya kaynak koddan:
git clone https://github.com/legion1581/unitree_webrtc_connect.git
cd unitree_webrtc_connect
pip install -e .Hızlı Başlangıç: İlk Bağlantı
Eski (data2=2) firmware'de yalnızca IP yeterlidir; V3 (data2=3) firmware'de ayrıca 32 hex karakterlik cihaza özel AES-128 anahtarı gerekir:
from unitree_webrtc_connect import UnitreeWebRTCConnection, WebRTCConnectionMethod
# Eski firmware (Go2 < 1.1.15, G1 < 1.5.1)
conn = UnitreeWebRTCConnection(WebRTCConnectionMethod.LocalSTA, ip="192.168.123.18")
await conn.connect()
# V3 firmware — cihaza özel AES-128 anahtarı gerekir
conn = UnitreeWebRTCConnection(
WebRTCConnectionMethod.LocalSTA,
ip="192.168.10.225",
aes_128_key="<32-hex-chars>",
)
await conn.connect()connect() bir coroutine'dir (async def) — tüm bağlantı çağrıları asyncio tabanlıdır ve kodunuzun bir event loop içinde (örn. asyncio.run(main())) çalışması gerekir. Quick-start örneğindeki await anahtar kelimesi bunun göstergesidir; ilk denemede en sık takılılan pratik detay budur.
Üç Bağlantı Yöntemi
Kütüphane, robotun ağ durumuna göre üç bağlantı yöntemi sunar. Hepsi aynı UnitreeWebRTCConnection sınıfıyla, WebRTCConnectionMethod enum'u üzerinden seçilir:
AP Modu
Robot kendi WiFi'sindeRobot henüz bir ağa bağlanmamışken kendi erişim noktasını yayınlar; istemci doğrudan robotun WiFi'sine bağlanır. data2=3 firmware'lerde AP modunda da aes_128_key verilmelidir.
UnitreeWebRTCConnection(WebRTCConnectionMethod.LocalAP)
# V3 firmware (G1 >= 1.5.1, Go2 >= 1.1.15)
UnitreeWebRTCConnection(
WebRTCConnectionMethod.LocalAP,
aes_128_key="<32-hex-karakter>",
)STA-L Modu
Aynı yerel ağ (LAN)Robot ve istemci aynı LAN'dadır. IP ile bağlanılır; Go2'de ayrıca seri numarası verilerek multicast keşifle robot otomatik bulunabilir (G1 bu yöntemde IP gerektirir).
# IP ile
UnitreeWebRTCConnection(WebRTCConnectionMethod.LocalSTA, ip="192.168.8.181")
# Seri numarasıyla (multicast keşif — sadece Go2)
UnitreeWebRTCConnection(WebRTCConnectionMethod.LocalSTA, serialNumber="B42D2000XXXXXXXX")STA-T Modu
Uzaktan (Unitree bulutu)Unitree'nin kendi TURN sunucusu/bulut rölesi üzerinden çalışır; Unitree hesabı (kullanıcı adı/şifre) gerektirir ve herhangi bir ağdan bağlanmayı sağlar. region='global' (varsayılan) veya Çin'de kayıtlı hesaplar için 'cn'; device_type 'Go2' veya 'G1' — her ikisi de global-robot-api.unitree.com adresine sırasıyla AppName: Go2 / AppName: G1 başlığıyla istek atar.
UnitreeWebRTCConnection(
WebRTCConnectionMethod.Remote,
serialNumber="B42D2000XXXXXXXX",
username="email@ornek.com",
password="...",
# region="cn", device_type="G1" # Çin hesabı + G1 için
)AES-128 Anahtarı ve data2=3 — En Kritik Teknik Detay
G1 firmware 1.5.1'den (Go2'ye 1.1.15 ile geri portlandı) itibaren LAN sinyalleşme el sıkışması (con_notify) data2=3 döndürür: gömülü RSA açık anahtarı artık cihaza özel bir AES-128-GCM anahtarı altında sarmalanmıştır. Bu anahtar olmadan WebRTC el sıkışması açık anahtarı çözemez ve bağlantı hiç başlamaz. Eski firmware'lerdeki (data2=2) statik anahtar ise kütüphane tarafından otomatik halledilir.
CLI ile Anahtar Çekme
pip kurulumundan sonra unitree-fetch-aes-key konsol aracı gelir (PATH'te yoksa python -m unitree_webrtc_connect._cli ile de çalışır). Varsayılan: region=global, cihaz ailesi=G1.
# Varsayılan: region=global, cihaz ailesi=G1
unitree-fetch-aes-key --email you@example.com --password '...'
# Go2 (>= 1.1.15):
unitree-fetch-aes-key --email you@example.com --password '...' --device-type Go2
# Çin bölgesi:
unitree-fetch-aes-key --email you@example.com --password '...' --region cn
# Tek seri no, script dostu (stdout'a ham anahtar):
KEY=$(unitree-fetch-aes-key --email ... --sn E21D6000XXXXXXXX --quiet)
# Mevcut access token ile (girişi atla):
unitree-fetch-aes-key --token <accessToken> --sn E21D6000XXXXXXXXPython ile Programatik Anahtar Çekme
Tek seferlik fetch_aes_key() fonksiyonu veya hesabınızdaki tüm robotları (seri no, takma ad, anahtar) listelemek için UnitreeCloud sınıfı:
from unitree_webrtc_connect import UnitreeCloud, fetch_aes_key
# Tek seferlik
key = fetch_aes_key("you@example.com", "...",
sn="E21D6000XXXXXXXX",
region="global", device_type="G1")
# Veya hesaptaki tüm robotları listele
cloud = UnitreeCloud(region="global", device_type="G1")
cloud.login_email("you@example.com", "...")
for d in cloud.list_devices():
print(d.sn, d.alias, d.key)Tipli Hata Sınıfları: Neden Fırlatılır, Nasıl Çözülür
Kütüphane, stack trace okumak yerine yakalayabileceğiniz 6 tipli exception sunar. Her biri belirli bir arıza noktasına işaret eder:
AesKeyRequiredErrorNe zaman: data2=3 dönen bir robota anahtar verilmeden ulaşıldığında
Çözüm: aes_128_key parametresini ekleyin; anahtarı unitree-fetch-aes-key veya fetch_aes_key() ile çekin
AesKeyRejectedErrorNe zaman: GCM tag kontrolü başarısız — anahtar yanlış veya başka robota ait
Çözüm: Anahtarı robotun tam seri numarasına karşı doğrulayın: unitree-fetch-aes-key --sn <seri> --quiet
LocalSignalingPortErrorNe zaman: Verilen IP'de ne 9991 ne de 8081 sinyalleşme portu erişilebilir
Çözüm: IP'yi, robotun gücünü, WiFi ağını ve güvenlik duvarını kontrol edin
RobotBusyErrorNe zaman: Robot SDP teklifini reddetti — başka bir WebRTC istemcisi (örn. resmi mobil uygulama) zaten bağlı
Çözüm: Aynı anda tek istemci bağlanabilir; diğer istemciyi kapatıp tekrar deneyin
NoSdpAnswerErrorNe zaman: Sinyalleşme HTTP düzeyinde başarılı ama robot boş/bozuk SDP yanıtı döndürdü
Çözüm: Robotun açık, WiFi'nin stabil olduğunu ve başka bir istemcinin el sıkışma ortasında olmadığını kontrol edin
DataChannelTimeoutErrorNe zaman: Data channel zamanında doğrulanmış/açık duruma ulaşamadı
Çözüm: Alt duruma göre üç kök neden ayrımı yapılır (aşağıya bakın)
DataChannelTimeoutError, kaynak kodda peer/ICE/channel alt-durumlarına göre üç ayrı kök neden raporlar: (1) peer hiç 'connected' olmadıysa ICE/DTLS başarısızlığıdır — başka bir istemci slotu tutuyor, ağ dengesiz veya eski bir peer henüz bırakılmamış olabilir; 10-20 sn sonra tekrar deneyin ya da diğer istemciyi kapatın. (2) Peer bağlandı ama channel açılmadıysa geçici bir transport sorunudur; tekrar deneyin. (3) Channel açıldı ama doğrulama tamamlanmadıysa AES-128 anahtarınız yanlış olabilir veya robotun doğrulayıcısı takılmıştır; yeniden bağlanın.
Repo İçindeki Hazır Örnekler
Tüm örnekler /examples klasöründe robot modeline göre organize edilmiştir ve varsayılan olarak ip="192.168.8.181" kullanır:
Kaynağı düzenlemeden robotunuza yönlendirmek için UNITREE_ROBOT_IP ortam değişkenini, V3 firmware'de ayrıca UNITREE_AES_128_KEY değişkenini set edin.
Go2 Örnekleri
data_channel/sportmode/Sport modu hareket komutlarıdata_channel/sportmode_mcf/İnteraktif MCF sport menüsü (firmware ≥ 1.1.7)data_channel/sportmodestate/Sport modu durumuna abonelikdata_channel/lowstate/Düşük seviye durum (IMU, motorlar)data_channel/multiplestate/Birden fazla durum topic'ine abonelikdata_channel/vui/VUI kontrolü (LED, ses, parlaklık)data_channel/obstacles_avoid/Engelden kaçınma aç/kapa + WASD sürüşdata_channel/lidar/lidar_stream.pyLiDAR nokta bulutu aboneliğidata_channel/lidar/plot_lidar_stream.pyLiDAR 3D görselleştirme (Three.js)audio/live_audio/Canlı ses almaaudio/save_audio/Sesi dosyaya kaydetmeaudio/mp3_player/Robot hoparlöründen MP3 çalmaaudio/internet_radio/İnternet radyosu akışıvideo/camera_stream/Kamera görüntüsünü izlemeG1 Örnekleri
data_channel/sport_mode/Sport modu hareket komutlarıvideo/camera_stream/Kamera görüntüsünü izlemeexport UNITREE_ROBOT_IP=192.168.8.181
# V3 firmware:
export UNITREE_AES_128_KEY=<32-hex-chars>
python examples/go2/data_channel/sportmode/sportmode.pyGenel API Referansı (Public Exports)
Tüm genel sınıf, yardımcı ve hata tipleri paket kökünden import edilir:
Çekirdek Sürücü
UnitreeWebRTCConnectionWebRTCConnectionMethodWebRTCDataChannelWebRTCDataChannelPubSubDATA_CHANNEL_TYPERTC_TOPICSPORT_CMDSPORT_CMD_MCFOBSTACLES_AVOID_APIBulut Yardımcıları
UnitreeCloudUnitreeCloudErrorRobotDevicefetch_aes_keyTipli Hatalar
AesKeyRequiredErrorAesKeyRejectedErrorDataChannelTimeoutErrorLocalSignalingPortErrorNoSdpAnswerErrorRobotBusyErrorWebRTCDataChannel, RTCDataChannel'ı oluşturan ve heartbeat/doğrulama/ağ-durumu yönetimini üstlenen yüksek seviye kanal yöneticisidir; WebRTCDataChannelPubSub ise onun içeride kullandığı topic bazlı publish/subscribe katmanıdır ve ayrıca doğrudan da dışa aktarılır.
README'nin Imports bölümünde yazmasa da, kurulu paketin __init__.py __all__ listesinde iki ek sabit daha dışa aktarılır: SPORT_CMD_MCF ve OBSTACLES_AVOID_API — sırasıyla sportmode_mcf ve obstacles_avoid örneklerinin dayandığı sabitler (paket kaynağından doğrulanmıştır).
Kurumsal Ağ, Güvenlik ve Veri Yönlendirmesi Notları
Port gereksinimleri (STA-L / AP)
Yerel sinyalleşme için 9991 ve 8081 portlarının istemci ile robot arasında (LAN/VLAN, güvenlik duvarı) erişilebilir olması gerekir. Kurumsal ağ planlamasında bu iki portu dikkate alın.
STA-T'de trafik nereden akar?
Uzaktan bağlantıda video/ses/komut trafiği Unitree'nin kendi TURN sunucusu/bulut rölesi üzerinden geçer — Robotlar.org altyapısından değil. Kurumsal güvenlik değerlendirmesinde bu mimari bilinmelidir.
region='cn' ve veri politikası
Çin'de kayıtlı hesaplar için region='cn' seçildiğinde hesap/oturum trafiği Çin merkezli uç noktalar üzerinden işlenir. Kurumsal veri politikası/KVKK değerlendirmesi gerektirebilir.
Filo ölçeğinde anahtar yönetimi
AES-128 anahtarı cihaza özeldir; birden fazla robottan oluşan filolarda anahtarların güvenli saklanması ve yönetimi operasyonel bir sorumluluktur. Robotlar.org bu konuda entegrasyon danışmanlığı sunar.
Resmi olmayan katman
Bu kütüphane topluluk kaynaklı bir projedir, Unitree tarafından resmi olarak desteklenmez. Üretim veya güvenlik-kritik dağıtımlarda bu kapsam netleştirilmeli, kritik senaryolar için resmi SDK yolu da değerlendirilmelidir.
Bu Rehber Neyi Kapsamaz?
Bu sayfa düşük seviyeli WebRTC protokol sürücüsünü konu alır. Apple Vision Pro / PICO / Quest ile XR teleoperasyon (xr_teleoperate) ayrı bir mimaridir ve G1 Teleoperasyon rehberinde anlatılır. Genel Unitree SDK (Python/C++/ROS2/simülasyon) için SDK Rehberi'ne, Isaac Gym pekiştirmeli öğrenme için RL Gym Rehberi'ne, diğer topluluk projeleri için Açık Kaynak sayfasına bakın.
Proje Kökeni, Katkılar ve Lisans
MIT lisanslı. Geliştirici: legion1581 (RoboLegion topluluğu — robolegion.com). Proje, tfoldi/go2-webrtc'nin orijinal WebRTC tersine mühendislik çalışması üzerine inşa edilmiştir; LiDAR desteği abizovnuralem, LiDAR görselleştirme örneği MrRobotoW, altyapıdaki aiortc kütüphanesi için gerekli monkey patch ise oulianov (Nico) katkısıdır. Yani bu, soyağacı bilinen ve yaygın kullanılan bir kod tabanıdır — belirsiz bir hobi projesi değil.
Sıkça Sorulan Sorular
Unitree Go2 veya G1'i jailbreak yapmadan Python ile kontrol edebilir miyim?
Evet. unitree_webrtc_connect, robotun resmi mobil uygulamalarının kullandığı aynı WebRTC protokolünü kullanır; jailbreak veya firmware değişikliği gerektirmez. MIT lisanslı açık kaynak bir topluluk projesidir — resmi Unitree ürünü değildir.
AesKeyRequiredError hatası alıyorum, ne yapmalıyım?
Robotunuzun firmware'i data2=3 döndürüyor (Go2 ≥ 1.1.15, G1 ≥ 1.5.1) ve koda aes_128_key vermemişsiniz. Anahtarı unitree-fetch-aes-key CLI'si veya fetch_aes_key() ile Unitree hesabınızdan çekin ve bağlantıya parametre olarak geçin.
data2=3 tam olarak ne anlama geliyor?
con_notify el sıkışma yanıtındaki data2 alanı kimlik doğrulama neslini gösterir: data2=2 statik AES-GCM anahtarı (otomatik), data2=3 cihaza özel AES-128-GCM anahtarı (sizin sağlamanız gerekir). data2=3'te anahtar olmadan RSA açık anahtarı çözülemez ve bağlantı hiç başlamaz.
Robotumu güncelledikten sonra çalışan kodum neden bozuldu?
Firmware güncellemesi robotu data2=2'den data2=3'e taşımış olabilir (G1 1.5.1, Go2 1.1.15 eşiği). Koda aes_128_key ekleyip anahtarı hesabınızdan çekmeniz gerekir. Filo yönetiminde bu adımı güncelleme ÖNCESİNDE planlamak operasyonel kesintiyi önler.
RobotBusyError ne zaman alınır?
Robot SDP teklifini reddettiğinde — genellikle resmi mobil uygulama gibi başka bir WebRTC istemcisi zaten bağlıyken. Aynı anda tek istemci bağlanabilir; diğerini kapatıp tekrar deneyin.
Go2 ve G1 arasında hangi özellikler farklı?
Data channel, sport/kol kontrolü ve video her ikisinde de var. Ses akışı, LiDAR, VUI, AudioHub, engelden kaçınma API'si ve multicast keşif şu an sadece Go2'de. data2=3 anahtar doğrulaması her ikisinde de destekleniyor.
Yerel ağ dışından (uzaktan) bağlanabilir miyim?
Evet — STA-T modu Unitree'nin TURN rölesi üzerinden herhangi bir ağdan çalışır. Unitree hesap bilgileri, region (global/cn) ve device_type (Go2/G1) parametreleri gerekir.
LiDAR nokta bulutunu Python'dan nasıl okurum?
data_channel/lidar/lidar_stream.py örneği aboneliği, plot_lidar_stream.py ise Three.js ile 3D görselleştirmeyi gösterir. LiDAR çözümleme yalnızca Go2'de desteklenir.
Bu kütüphane resmi Unitree SDK'sının yerini mi alıyor?
Hayır — farklı katmanlar. Resmi SDK (DDS tabanlı) robotun dahili ağından düşük seviye kontrol sunar; WebRTC sürücüsü ise mobil uygulama protokolüyle standart WiFi/internet üzerinden çalışır. Senaryonuza göre doğru katmanı seçmek gerekir — bu konuda danışmanlık veriyoruz.
Türkiye'de bu entegrasyon için destek alabilir miyim?
Evet. Robotlar.org olarak AES anahtarı çıkarma, firmware uyumluluk kontrolü, bağlantı sorun giderme ve kurumsal ağ/güvenlik duvarı planlaması konularında yerinde ve uzaktan teknik destek sunuyoruz.
Kaynaklar & Bağlantılar
unitree_webrtc_connect — GitHub
Resmi kaynak kod, örnekler ve sürüm notları (MIT lisansı).
PyPI: unitree-webrtc-connect
pip ile kurulabilir paket — güncel sürüm 2.1.2.
tfoldi/go2-webrtc
Projenin üzerine inşa edildiği orijinal WebRTC tersine mühendislik çalışması.
RoboLegion Topluluğu
Kütüphanenin geliştirici topluluğu — destek ve tartışma.
Unitree SDK Rehberi
Resmi SDK katmanı: Python, C++, ROS2 ve simülasyon ortamları.
G1 Teleoperasyon Rehberi
Apple Vision Pro / PICO / Quest ile XR teleoperasyon (xr_teleoperate).
WebRTC Entegrasyon Desteği
Türkiye'de.
AES anahtarı çıkarma, firmware uyumluluk kontrolü, bağlantı sorun giderme veya kurumsal ağ planlaması için Türkiye'deki Unitree teknik ekibimizden destek alın.