Robotlar
Unitree Bilgi Üssü
WebRTC Sürücü Rehberi
unitree_webrtc_connect GitHub starsunitree-webrtc-connect PyPI version

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

RobotFirmwareKimlik DoğrulamaAnahtar
Go21.0.19 – 1.0.25data2=2Statik GCM (otomatik)
Go21.1.1 – 1.1.14data2=2Statik GCM (otomatik)
Go21.1.15+data2=3Cihaza özel AES-128 (sizden)
G11.2.0 – 1.4.5data2=2Statik GCM (otomatik)
G11.5.1+data2=3Cihaza ö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:

ÖzellikGo2G1
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:

bash
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:

python
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'sinde

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

python
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).

python
# 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.

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

Anahtar cihaza özeldir ve yeniden eşleştirmelerde (re-pairing) sabit kalır
Robot üzerinde /unitree/etc/key/aes_key.bin yolunda RSA ile sarmalanmış olarak saklanır
Unitree bulutuna device/bind/list API yanıtında dev.key alanı olarak yansır
32 hex karakter formatındadır ve aes_128_key parametresiyle verilir

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.

bash
# 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 E21D6000XXXXXXXX

Python 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ı:

python
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:

AesKeyRequiredError

Ne 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

AesKeyRejectedError

Ne 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

LocalSignalingPortError

Ne 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

RobotBusyError

Ne 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

NoSdpAnswerError

Ne 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

DataChannelTimeoutError

Ne 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 abonelik
data_channel/lowstate/Düşük seviye durum (IMU, motorlar)
data_channel/multiplestate/Birden fazla durum topic'ine abonelik
data_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ği
data_channel/lidar/plot_lidar_stream.pyLiDAR 3D görselleştirme (Three.js)
audio/live_audio/Canlı ses alma
audio/save_audio/Sesi dosyaya kaydetme
audio/mp3_player/Robot hoparlöründen MP3 çalma
audio/internet_radio/İnternet radyosu akışı
video/camera_stream/Kamera görüntüsünü izleme

G1 Örnekleri

data_channel/sport_mode/Sport modu hareket komutları
video/camera_stream/Kamera görüntüsünü izleme
bash
export UNITREE_ROBOT_IP=192.168.8.181
# V3 firmware:
export UNITREE_AES_128_KEY=<32-hex-chars>
python examples/go2/data_channel/sportmode/sportmode.py

Genel 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_API

Bulut Yardımcıları

UnitreeCloudUnitreeCloudErrorRobotDevicefetch_aes_key

Tipli Hatalar

AesKeyRequiredErrorAesKeyRejectedErrorDataChannelTimeoutErrorLocalSignalingPortErrorNoSdpAnswerErrorRobotBusyError

WebRTCDataChannel, 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.

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.