ROS 2 su Unitree: da zero al primo topic in laboratorio

Usare ROS 2 con i robot Unitree è più semplice di quanto molti pensino, perché non serve un vero "bridge": l'SDK di Unitree comunica tramite DDS (CycloneDDS) e anche ROS 2 usa DDS come middleware. Con i messaggi giusti e la configurazione di rete corretta, un nodo ROS 2 può leggere lo stato del robot e inviare comandi direttamente. Questa guida porta da zero al primo topic in laboratorio, seguendo il repository ufficiale unitree_ros2.

Come funziona l'integrazione

Il README di unitree_ros2 spiega che, poiché robot e ROS 2 condividono DDS come meccanismo di comunicazione, i messaggi ROS 2 possono essere usati per comunicare e controllare il robot senza incapsulare l'interfaccia dell'SDK. Il repository fornisce:

• cyclonedds_ws — il workspace con i pacchetti di messaggi unitree_api, unitree_go (Go2, B2, H1) e unitree_hg (G1, H1-2 e altri modelli);
• example — esempi di lettura dello stato, controllo di alto livello per Go2 e controllo di basso livello, incluso un esempio dedicato al G1.

Il README cita esplicitamente il supporto a Go2, B2 e H1; gli esempi includono anche il G1 e l'H1-2. Per altri modelli verifica la documentazione specifica prima di partire.

Quale distribuzione ROS 2

Ubuntu	ROS 2	Note
20.04	Foxy	Testata dal repository, ma Foxy è ormai fuori supporto
22.04	Humble	Consigliata dal repository; LTS supportata fino a maggio 2027
24.04	Jazzy	LTS fino a maggio 2029, ma non elencata tra le combinazioni testate da unitree_ros2

Per un nuovo progetto in laboratorio oggi la scelta più prudente resta Ubuntu 22.04 + ROS 2 Humble. Se devi usare Jazzy, metti in conto tempo per compilare e verificare da solo la compatibilità.

Installazione passo per passo (Humble)

1. Installa ROS 2 Humble seguendo la documentazione ufficiale ROS.
2. Clona il repository:

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

3. Installa le dipendenze:

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

4. CycloneDDS: i robot usano la versione 0.10.2. Con Humble il passo di compilazione manuale di CycloneDDS si può saltare; con Foxy invece va compilato dal ramo releases/0.10.x, senza aver caricato l'ambiente ROS 2 nel terminale, altrimenti la compilazione fallisce.
5. Compila i pacchetti di messaggi:

   source /opt/ros/humble/setup.bash
   cd ~/unitree_ros2/cyclonedds_ws
   colcon build

Configurare la rete

1. Collega PC e robot con un cavo Ethernet e individua l'interfaccia (per esempio enp3s0).
2. Imposta l'IPv4 in manuale: indirizzo 192.168.123.99, maschera 255.255.255.0.
3. Modifica ~/unitree_ros2/setup.sh impostando la tua distribuzione (il README usa foxy come esempio) e inserendo il nome della tua interfaccia:

   source /opt/ros/humble/setup.bash
   source $HOME/unitree_ros2/cyclonedds_ws/install/setup.bash
   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. Carica l'ambiente con source ~/unitree_ros2/setup.sh. Il README consiglia un riavvio del PC prima del primo test.

Senza robot collegato puoi lavorare in locale con setup_local.sh, che usa l'interfaccia di loopback lo: utile insieme al simulatore unitree_mujoco.

Il primo topic

source ~/unitree_ros2/setup.sh
ros2 topic list
ros2 topic echo /sportmodestate

I topic principali documentati nel README:

Topic	Contenuto
/sportmodestate, /lf/sportmodestate	Stato di movimento: posizione, velocità, andatura (quadrupedi)
/lowstate, /lf/lowstate	Stato dei motori, IMU e batteria
/wirelesscontroller	Input del telecomando
/lowcmd	Comandi di basso livello ai motori
/api/sport/request	Richieste di controllo di alto livello

Il prefisso lf indica la versione a bassa frequenza del topic. Per compilare ed eseguire gli esempi:

cd ~/unitree_ros2/example
colcon build
./install/unitree_ros2_example/bin/read_motion_state

Sul G1 usa gli esempi per la famiglia unitree_hg, come la lettura dello stato a basso livello e l'esempio di controllo dedicato al G1. Ricorda che sul G1 il controllo di basso livello richiede la modalità debug e il robot sospeso: vedi la guida operativa G1.

Problemi comuni e soluzioni

• ros2 topic list non mostra i topic del robot — controlla che RMW_IMPLEMENTATION sia rmw_cyclonedds_cpp, che il nome dell'interfaccia in CYCLONEDDS_URI sia corretto e che il PC sia nella subnet 192.168.123.x.
• Errori di compilazione di CycloneDDS (Foxy) — l'ambiente ROS 2 era caricato nel terminale; commenta temporaneamente il source in ~/.bashrc.
• Più ambienti ROS sulla stessa macchina — evita di mettere setup.sh in ~/.bashrc se lavori anche su altri progetti: caricalo solo quando serve.
• I topic ci sono ma i comandi non hanno effetto — sul G1 verifica la modalità del robot: in modalità debug i comandi di alto livello vengono ignorati.
• Simulazione e robot reale si "vedono" a vicenda — usa domain ID e interfacce diverse: loopback per la simulazione, Ethernet per il robot.

Dopo il primo topic

Una volta che lo stato del robot arriva in ROS 2, puoi registrarlo con rosbag (c'è un esempio dedicato), visualizzarlo, integrare sensori aggiuntivi e costruire pipeline di navigazione e percezione. Per la parte di programmazione diretta con l'SDK vedi programmare il G1; per la simulazione su GPU vedi NVIDIA Isaac e Omniverse.

Domande frequenti

Serve un bridge tra ROS 2 e l'SDK Unitree?

No. Robot e ROS 2 usano entrambi DDS: con i pacchetti di messaggi di unitree_ros2 e CycloneDDS configurato, i nodi ROS 2 comunicano direttamente con il robot.

Posso usare ROS 2 Jazzy?

Il repository ufficiale indica come testate Foxy e Humble, con Humble consigliata. Jazzy non è nell'elenco: si può provare, ma la compatibilità va verificata sul tuo progetto.

Che IP devo dare al PC?

Il README indica 192.168.123.99 con maschera 255.255.255.0. Va bene qualsiasi indirizzo libero nella subnet 192.168.123.x che non sia già usato dal robot.

Posso lavorare senza il robot?

Sì: con setup_local.sh e il simulatore unitree_mujoco puoi sviluppare e testare in locale, poi passare al robot cambiando solo la configurazione di rete.

Serve una mano?

CALIGO configura ROS 2 su robot Unitree per università e reparti R&D, dalla rete al primo nodo funzionante, e forma il team. Richiedi supporto.

Panoramica commerciale e catalogo: Abra Robotics.