SDK, ROS2 e
l'ecosistema GitHub Unitree
Dalla app al codice. SSH, rete, SDK C++ e Python, ROS2, MuJoCo, IsaacLab. Cheatsheet operativa + deposito commentato dei 17 repo ufficiali Unitree, ognuno con quickstart, struttura e comandi più usati. In italiano.
Setup ambiente di sviluppo
Ubuntu 20.04 o 22.04 (x86_64 o ARM64). Windows/macOS sono possibili con WSL2 o VM, ma aspettati 2x di tempo e qualche incompatibilità sui driver di rete real-time. Raccomandato: dual boot o laptop dedicato.
# dipendenze base sudo apt update && sudo apt install -y \ build-essential cmake git \ libeigen3-dev libboost-all-dev # network real-time (ethernet diretto al robot) sudo apt install -y iproute2 # Python tooling sudo apt install -y python3-pip python3-venv python3 -m venv ~/.venv/unitree source ~/.venv/unitree/bin/activate # CycloneDDS (prerequisito SDK2) git clone https://github.com/eclipse-cyclonedds/cyclonedds \ -b releases/0.10.x cd cyclonedds && mkdir build && cd build cmake -DCMAKE_INSTALL_PREFIX=../install .. make -j && make install
Rete, SSH e accesso al robot
Il primo muro contro cui sbattono tutti: "come entro nel robot via codice?". Ogni modello Unitree ha IP statici, porte, credenziali SSH e modi di connettersi diversi. Questa è la sezione che vorrai bookmarkare.
Topologia di rete Unitree
Ogni robot Unitree ha un Jetson (Nano su Go2, Orin NX su B2/G1/H1) che espone interfacce di rete multiple. Il developer si connette via Ethernet (low-latency, per low-level control) oppure via WiFi hotspot (comodo, ma ad alta latenza).
Ethernet (raccomandato)
- • Laptop IP:
192.168.123.99 - • Subnet:
255.255.255.0(/24) - • Robot IP (Jetson):
192.168.123.18 - • MCU motor control:
192.168.123.10 - • Latenza: < 1 ms · obbligatorio per low-level control
- • Porta robot: sotto lo sportellino batteria, pin-out RJ45 standard
WiFi (hotspot robot)
- • SSID:
Unitree_XXXX(4 cifre seriali) - • Password iniziale: sulla label sotto il robot (varia per unità)
- • Robot IP via hotspot:
10.42.0.1 - • Latenza: 5-20 ms · accettabile per sport mode, NO low-level
- • Utile per: test rapidi, diagnostica in campo, setup iniziale
- • WiFi 5 GHz consigliato (meno congestione)
Credenziali SSH di default per modello
Username sempre unitree. La password varia per modello e versione firmware. La prima cosa da fare dopo il primo accesso è cambiare la password.
| Modello | User | Password | IP Ethernet | Hardware onboard |
|---|---|---|---|---|
| Go2 (Air / Pro / EDU) | unitree | 123 | 192.168.123.18 | Jetson Orin Nano |
| B2 / B2-W | unitree | 123 Unitree0408 (se secondo NX) | 192.168.123.18 | 2× Jetson Orin NX |
| G1 | unitree | 123 | 192.168.123.164 | Jetson Orin NX |
| H1 / H1-2 | unitree | 123 | 192.168.123.162 | Jetson Orin NX / AGX |
| Go1 / A1 (legacy) | pi / unitree | raspberry / 123 | 192.168.123.13 · .14 · .15 | Raspberry Pi 4 + Jetson Nano |
.18), l'altro è dedicato al payload developer (.15 tipicamente). La password del secondo NX su alcune unità B2 è Unitree0408 invece di 123. Se la prima non funziona, prova la seconda.
123 è un problema di sicurezza serio. Dopo primo login: passwd, nuova password forte, documenta su password manager del team.
Primo SSH: step-by-step
# temporaneo via CLI sudo ip addr add 192.168.123.99/24 \ dev enp3s0 sudo ip link set enp3s0 up # permanente via netplan # /etc/netplan/01-unitree.yaml network: version: 2 ethernets: enp3s0: addresses: - 192.168.123.99/24 dhcp4: false sudo netplan apply
# test connessione ping -c 3 192.168.123.18 # SSH Go2/G1/H1 ssh unitree@192.168.123.18 # password: 123 # SSH B2 secondo NX ssh unitree@192.168.123.15 # password: Unitree0408 # info sistema dopo login uname -a lsb_release -a nvidia-smi # se Orin
enp3s0 con il nome della tua interfaccia Ethernet (ip link show per vedere le tue).
Hardening: chiavi SSH + porta custom
Dopo i primi test, passa a chiavi SSH e disabilita login con password. Ogni volta che fai ssh unitree@... senza chiave, lasci il robot attaccabile.
ssh-keygen -t ed25519 -C "bubbles-dev" # copia pubblica sul robot ssh-copy-id unitree@192.168.123.18 # test: non deve chiedere password ssh unitree@192.168.123.18
PasswordAuthentication no PermitRootLogin no Port 2200 # opzionale sudo systemctl restart ssh # poi dal laptop: ssh -p 2200 unitree@192.168.123.18
unitree_sdk2: il core di tutto
SDK ufficiale per Go2, B2, H1, G1, H2, R1, A2. Due livelli di controllo: high-level (sport mode: camminate, pose, andamenti già composti da Unitree) e low-level (comandi motore singolo a 500Hz, per applicazioni custom e RL). La maggioranza dei progetti usa high-level.
High-level · Sport mode
Chiami funzioni come Move(vx, vy, vyaw), StandUp(), Damp(). Il controller interno Unitree gestisce gait, bilanciamento, recupero da cadute.
- •
StandUp()·StandDown()·Damp() - •
Move(vx, vy, vyaw)·StopMove() - •
BalanceStand()·RecoveryStand() - •
Hello()·Stretch()·Pose() - •
SwitchGait(d)·Scrape() - •
SetVelocity()(0.5-5 m/s range)
Low-level · Motor control
12 motori (4 zampe × 3 giunti), comandi torque/posizione/velocità a 500Hz. Bypassa il controller interno — se sbagli a 500Hz puoi rompere giunti o far cadere il robot in 200ms.
- •
q: posizione target (rad) - •
dq: velocità target (rad/s) - •
tau: torque feedforward (Nm) - •
Kp: stiffness (0-100) - •
Kd: damping (0-10) - •
mode: 0x00=off / 0x0A=servo
// Stand up + cammina avanti 3 secondi + siediti #include <unitree/robot/go2/sport/sport_client.hpp> int main(int argc, char** argv) { unitree::robot::ChannelFactory::Instance()->Init(0, "eth0"); unitree::robot::go2::SportClient client; client.SetTimeout(10.0f); client.Init(); client.StandUp(); sleep(2); client.Move(0.3f, 0.0f, 0.0f); // avanti sleep(3); client.StopMove(); client.StandDown(); return 0; }
ROS2: il robot nel tuo stack
Se il tuo ecosistema è ROS2 (Nav2, MoveIt, computer vision pipeline), passa da unitree_ros2. Il bridge pubblica i topic standard, riceve comandi da qualsiasi nodo ROS2. Supporto ufficiale per Go2 e B2.
# 1. Clone + deps git clone https://github.com/unitreerobotics/unitree_ros2 sudo apt install ros-humble-rmw-cyclonedds-cpp sudo apt install ros-humble-rosidl-generator-dds-idl sudo apt install libyaml-cpp-dev # 2. Build cd unitree_ros2 source /opt/ros/humble/setup.bash colcon build source ~/unitree_ros2/setup.sh # 3. Export middleware + interface (in ~/.bashrc) export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp export CYCLONEDDS_URI='<CycloneDDS><Domain><General><Interfaces> <NetworkInterface name="enp3s0" priority="default" multicast="default" /> </Interfaces></General></Domain></CycloneDDS>' # 4. Test ros2 topic list ros2 topic echo /sportmodestate ros2 run rviz2 rviz2
Topic pubblicati dal robot
/sportmodestate
posa · velocità · gait
/lowstate
giunti 500Hz
/imu
sensor_msgs/Imu
/wirelesscontroller
input joystick
/utlidar/cloud
PointCloud2 L1
/frontvideostream
RGB camera
Topic subscribed (per comandare)
/api/sport/request
high-level API
/lowcmd
motor 12× · 500Hz
/cmd_vel
twist (Nav2 compat)
/api/vui/request
LED / audio
/api/motion_switcher
switch modalità
rmw_fastrtps (default di ROS2 Foxy) vedrai topic ma potresti non ricevere dati. Config RMW_IMPLEMENTATION=rmw_cyclonedds_cpp prima di ogni sessione (mettilo in .bashrc).
Simulazione: MuJoCo e IsaacLab
Tutto quello che fai sul robot vero puoi farlo prima in simulazione. Risparmi batterie, giunti, tempo. Unitree pubblica tre simulatori ufficiali, ognuno buono per cose diverse.
MuJoCo
Fisica realistica, leggero, stesso SDK2 del robot reale. Perfect per sviluppo e debug sim-to-real.
Isaac Gym (legacy)
Reinforcement learning ad alta parallelizzazione (4096 env su GPU). Per addestrare policy locomotion da zero.
Isaac Lab
Il successore ufficiale NVIDIA di Isaac Gym. Scene complesse, sensori realistici, photorealistic rendering.
Sim-to-real senza cambiare codice
Il punto di forza di unitree_mujoco è che espone le stesse API di SDK2. Il tuo codice di controllo punta allo stesso SportClient — basta cambiare il network interface tra sim e robot vero.
Quando sim funziona, hai >80% di probabilità che funzioni su robot vero. Le divergenze residue (attriti, latenza motori, rumore sensori) si limano in una giornata di field test.
Repo unitree_mujoco4D LiDAR L1 e SLAM con Point-LIO
Il 4D LiDAR Unitree L1/L2 (integrato o aggiuntivo) è un solid-state LiDAR che fornisce nuvole di punti a 10Hz. Unitree pubblica un repo ufficiale per SLAM in tempo reale basato su Point-LIO.
Specifiche 4D LiDAR L1
Point-LIO pipeline
- LiDAR + IMU sincronizzati via driver Unitree
- Point-LIO fonde IMU e LiDAR a rate alto (200Hz)
- Pose estimator genera odometria drift-compensated
- Build della mappa punti (
.pcd) + traiettoria (.txt) - Export per Nav2 o post-processing in CloudCompare
Cheatsheet comandi quotidiani
I comandi che userai tutti i giorni quando sviluppi su Unitree. Bookmarka questa sezione — fai Ctrl+F per trovare velocemente quello che cerchi.
# ping robot ping 192.168.123.18 # ssh rapido (senza chiave) ssh unitree@192.168.123.18 # ssh con chiave (config ~/.ssh/config) Host go2 HostName 192.168.123.18 User unitree # poi: ssh go2 # interfacce di rete sul robot ssh go2 "ip addr show" # scopri porta ethernet sul laptop ip link show | grep -i "eth\|enp"
# copia file al robot scp skill.py unitree@192.168.123.18:~/ # copia cartella bidirezionale rsync -avz ./code/ go2:~/code/ rsync -avz go2:~/logs/ ./logs/ # download bag ROS2 dal robot scp -r go2:~/rosbag2_2026_* ./rosbags/ # mount remoto (sshfs) sudo apt install sshfs mkdir ~/go2-fs sshfs unitree@192.168.123.18:/ ~/go2-fs
# lista tutti i topic ros2 topic list # rate dei topic (deve essere ~500Hz per lowstate) ros2 topic hz /lowstate ros2 topic hz /sportmodestate # dump di un messaggio ros2 topic echo /imu --once # info + schema di un topic ros2 topic info /sportmodestate ros2 interface show unitree_go/msg/SportModeState # verifica CycloneDDS echo $RMW_IMPLEMENTATION # grafo nodi ROS2 ros2 run rqt_graph rqt_graph
# visualizza LiDAR in RViz2 rviz2 -d $(ros2 pkg prefix unitree_ros2)\ /share/unitree_ros2/rviz/lidar.rviz # RGB camera stream ros2 run image_view image_view \ --ros-args -r image:=/frontvideostream # record bag per replay offline ros2 bag record /sportmodestate /imu \ /utlidar/cloud -o mission_$(date +%s) # replay bag ros2 bag play mission_1713366000
# log di sistema onboard ssh go2 "journalctl -u robot.service -n 200" # CPU/GPU usage live ssh go2 "htop" ssh go2 "nvidia-smi --loop=1" # temperatura motori (lowstate) ros2 topic echo /lowstate --once | \ grep -A1 "motor_state" | head -40 # dmesg per errori hw ssh go2 "dmesg | tail -50" # reset sport controller ssh go2 "sudo systemctl restart \ sport_mode.service"
# compila cross-platform (x86 → ARM64) # richiede docker + buildx docker buildx build \ --platform linux/arm64 \ -t my-skill:v1 . # deploy container sul robot docker save my-skill:v1 | \ ssh go2 "docker load" ssh go2 "docker run -d \ --network=host my-skill:v1" # systemd unit per skill auto-start # /etc/systemd/system/bubbles-skill.service ssh go2 "sudo systemctl \ enable bubbles-skill"
17 repo GitHub Unitree, tutti spiegati
Ogni repository ufficiale @unitreerobotics, espandi la card per vedere quickstart, struttura e comandi più usati. Usa la search per filtrare.
SDK core · inizia da qui
unitree_sdk2
C++ · Essential
SDK C++ ufficiale · core di tutto
Go2, B2, H1, G1, H2, R1, A2. High-level sport mode + low-level 500Hz. Base di tutto il resto dell'ecosistema.
SDK C++ ufficiale · core di tutto
Go2, B2, H1, G1, H2, R1, A2. High-level sport mode + low-level 500Hz. Base di tutto il resto dell'ecosistema.
git clone https://github.com/\
unitreerobotics/unitree_sdk2
cd unitree_sdk2 && mkdir build
cd build && cmake ..
make -j8
# test stand+walk
./example/go2/stand_example eth0
- •
include/unitree/robot/— headers - •
example/go2/— esempi sport mode - •
example/low_level/— motor 500Hz - •
example/helloworld/— DDS basic - •
thirdparty/cyclonedds/— middleware
unitree_sdk2_python
Python · Essential
Binding Python · prototipazione rapida
Wrapper Python di SDK2. Per notebook Jupyter, workflow ML/RL, scripting veloce. Stessa API del core C++.
Binding Python · prototipazione rapida
Wrapper Python di SDK2. Per notebook Jupyter, workflow ML/RL, scripting veloce. Stessa API del core C++.
git clone https://github.com/\
unitreerobotics/unitree_sdk2_python
cd unitree_sdk2_python
pip3 install -e .
# stand via python
python3 example/go2/high_level/\
go2_sport_client.py eth0
- • Prototipazione in Jupyter
- • Integrazione con PyTorch/TF
- • Data collection per training RL
- • Script CI/CD per test robot
unitree_ros2
ROS2 · Recommended
Bridge ROS2 Foxy/Humble
Espone topic ROS2 per Go2 e B2. Integrazione diretta con Nav2, MoveIt, computer vision pipeline.
Bridge ROS2 Foxy/Humble
Espone topic ROS2 per Go2 e B2. Integrazione diretta con Nav2, MoveIt, computer vision pipeline.
git clone https://github.com/\
unitreerobotics/unitree_ros2
sudo apt install \
ros-humble-rmw-cyclonedds-cpp
cd unitree_ros2
colcon build
source setup.sh
# test
ros2 topic echo /sportmodestate
export RMW_IMPLEMENTATION=\ rmw_cyclonedds_cpp export CYCLONEDDS_URI='<CycloneDDS>\ <Domain><General><Interfaces>\ <NetworkInterface name="enp3s0" \ priority="default" \ multicast="default"/>\ </Interfaces></General>\ </Domain></CycloneDDS>'
unitree_guide
Educational
Controller educational · come funziona dentro
Implementazione completa di un gait controller con Joint Space e Force Control. Didattico — non uso produzione ma ti fa capire cosa fa il controller Unitree.
Controller educational · come funziona dentro
Implementazione completa di un gait controller con Joint Space e Force Control. Didattico — non uso produzione ma ti fa capire cosa fa il controller Unitree.
- • Joint Space control: PD su ogni giunto con ref trajectory
- • Force control: computed torque dalle forze di contatto
- • FSM: state machine passive → fixed stand → free stand → trot
- • Gait scheduler: timing di appoggio/swing delle 4 zampe
- • Target: studenti robotica, ricercatori, curiosi che vogliono leggere il codice
Simulazione · prima del robot vero
unitree_mujoco
Recommended
MuJoCo sim-to-real · identico all'SDK reale
Fisica MuJoCo + SDK2 condiviso tra sim e robot. Il modo più rapido per testare codice senza rischiare hardware.
MuJoCo sim-to-real · identico all'SDK reale
Fisica MuJoCo + SDK2 condiviso tra sim e robot. Il modo più rapido per testare codice senza rischiare hardware.
pip install mujoco
git clone https://github.com/\
unitreerobotics/unitree_mujoco
cd unitree_mujoco/simulate
mkdir build && cd build
cmake .. && make -j4
# lancia simulatore
./unitree_mujoco
- •
unitree_robots/go2/ - •
unitree_robots/b2/ - •
unitree_robots/h1/ - •
unitree_robots/g1/ - • Config via
config.yaml
unitree_rl_gym
RL · Legacy
Isaac Gym RL · 4096+ env in parallelo
Reinforcement learning su GPU. Training policy locomotion da zero. Supporta Go2, H1, H1_2, G1.
Isaac Gym RL · 4096+ env in parallelo
Reinforcement learning su GPU. Training policy locomotion da zero. Supporta Go2, H1, H1_2, G1.
# training (richiede Isaac Gym) python legged_gym/scripts/train.py \ --task=go2 # visualizza policy addestrata python legged_gym/scripts/play.py \ --task=go2 # solo CPU (lento ma funziona) python train.py --task=h1 \ --sim_device=cpu --rl_device=cpu
- •
--task: go2, h1, h1_2, g1 - •
--headless: no render (training) - •
--resume: riprende checkpoint - •
--num_envs: default 4096 - •
--sim_device: cuda:0 / cpu
unitree_rl_lab.
unitree_rl_lab
RL · Modern
RL su IsaacLab · il successore
Porting ufficiale di unitree_rl_gym su NVIDIA IsaacLab. Usare questo al posto di Isaac Gym per nuovi progetti.
RL su IsaacLab · il successore
Porting ufficiale di unitree_rl_gym su NVIDIA IsaacLab. Usare questo al posto di Isaac Gym per nuovi progetti.
- • IsaacLab è attivamente sviluppato da NVIDIA (Isaac Gym no)
- • Scene più complesse (asset USD)
- • Sensori fotorealistici integrati
- • Stack PyTorch + Stable Baselines3 più pulito
- • Sim-to-real pipeline nativa con domain randomization
unitree_rl_mjlab
RL · CPU
RL su MuJoCo · no GPU richiesta
Alternativa a IsaacLab per chi non ha GPU NVIDIA. Stesso stack RL, fisica MuJoCo. Più lento ma cross-platform.
RL su MuJoCo · no GPU richiesta
Alternativa a IsaacLab per chi non ha GPU NVIDIA. Stesso stack RL, fisica MuJoCo. Più lento ma cross-platform.
- • Non hai GPU NVIDIA RTX (es. Mac, laptop integrata AMD)
- • Vuoi training parallelo ma multi-CPU invece che GPU
- • Preferisci stack MuJoCo (Eigen + Python) a PhysX
- • Progetto piccolo: 100-500 env paralleli bastano
unitree_sim_isaaclab
Photoreal
IsaacLab simulation platform
Setup IsaacLab high-fidelity con asset USD realistici, camere fotorealistiche, LiDAR simulato. Per vision-based RL e manipolazione.
IsaacLab simulation platform
Setup IsaacLab high-fidelity con asset USD realistici, camere fotorealistiche, LiDAR simulato. Per vision-based RL e manipolazione.
Use case tipici:
- • Training policy di manipolazione con visione
- • Generazione dataset sintetici per computer vision
- • Testing Nav2 su scene realistiche
- • Sim-to-real con domain randomization
Perception & SLAM
point_lio_unilidar
SLAM
SLAM Point-LIO per LiDAR L1/L2
Localization + mapping real-time. Fusion LiDAR + IMU a 200Hz. Output: point cloud + traiettoria per Nav2.
SLAM Point-LIO per LiDAR L1/L2
Localization + mapping real-time. Fusion LiDAR + IMU a 200Hz. Output: point cloud + traiettoria per Nav2.
# dipendenze ROS2 Humble sudo apt install ros-humble-pcl-ros git clone https://github.com/\ unitreerobotics/point_lio_unilidar cd point_lio_unilidar colcon build source install/setup.bash # lancia SLAM ros2 launch point_lio mapping.launch.py
- •
map.pcd: point cloud salvata - •
trajectory.txt: poses TUM format - • Topic
/cloud_registered: mappa live - • Topic
/odom: odometria drift-compensated - • Export: CloudCompare / Nav2 map_server
teleimager
Video
Image server multi-camera
Cattura video stream da camere multiple del robot e pubblica via rete. Usato per XR teleop e computer vision distribuita.
Image server multi-camera
Cattura video stream da camere multiple del robot e pubblica via rete. Usato per XR teleop e computer vision distribuita.
Use case: streaming low-latency delle camere del robot a un visore VR o a una workstation remota. Particolarmente utile per umanoidi con stereo camera frontale.
Embodied AI · frontiera 2026
unifolm-world-model-action
Research
UnifoLM-WMA-0 · world model + action
Architettura open-source di Unitree multi-embodiment (quadrupede + umanoide). Predice futuro stato del mondo e genera azioni. Stato dell'arte 2026.
UnifoLM-WMA-0 · world model + action
Architettura open-source di Unitree multi-embodiment (quadrupede + umanoide). Predice futuro stato del mondo e genera azioni. Stato dell'arte 2026.
unifolm-vla
Research · VLA
Vision-Language-Action model
Large VLA per manipolazione umanoide generale. Input: immagine + comando linguaggio naturale → output: azioni motorie.
Vision-Language-Action model
Large VLA per manipolazione umanoide generale. Input: immagine + comando linguaggio naturale → output: azioni motorie.
unitree_lerobot
End-to-end
Framework embodied AI con HuggingFace
Integra LeRobot di HuggingFace con Unitree. Data collection → training imitation learning → deploy sul robot.
Framework embodied AI con HuggingFace
Integra LeRobot di HuggingFace con Unitree. Data collection → training imitation learning → deploy sul robot.
Pipeline tipica:
- Teleoperation con XR → registra dataset
- Push dataset su HuggingFace Hub
- Training policy (ACT, Diffusion, VQ-BeT) su GPU
- Deploy policy sul robot tramite SDK2
xr_teleoperate
XR · VR
Teleoperation da visore VR/AR
Controlla G1, H1, H2 con Meta Quest o Apple Vision Pro. Registrazione dataset per imitation learning. Stream video al visore.
Teleoperation da visore VR/AR
Controlla G1, H1, H2 con Meta Quest o Apple Vision Pro. Registrazione dataset per imitation learning. Stream video al visore.
Device compatibili: Meta Quest 2/3/Pro, Apple Vision Pro. Mapping: hand tracking → giunti spalla/gomito/polso del robot. Pattern usato dai ricercatori per raccogliere demo di manipolazione umana.
Legacy · per robot pre-2024
unitree_legged_sdk
Legacy
SDK per robot pre-2024
Per Aliengo, A1, Go1, B1. API diversa da SDK2 (non usa DDS, usa UDP proprietario).
SDK per robot pre-2024
Per Aliengo, A1, Go1, B1. API diversa da SDK2 (non usa DDS, usa UDP proprietario).
Usa questo solo se hai un A1, Go1, B1 o Aliengo. Per Go2 in poi tutto è su unitree_sdk2. Non mescolare le due API.
unitree_ros
ROS1 · Legacy
ROS1 Noetic + URDF
Bridge ROS1 e file URDF per simulazione Gazebo. ROS1 è EOL — usa unitree_ros2 se puoi.
ROS1 Noetic + URDF
Bridge ROS1 e file URDF per simulazione Gazebo. ROS1 è EOL — usa unitree_ros2 se puoi.
unitree_sdk2 (o unitree_sdk2_python) + unitree_mujoco per testare. Poi unitree_ros2 se il tuo stack è ROS2. Tutto il resto arriva dopo, al bisogno.