ROS 2 su robot Unitree: da zero al primo topic

ROS 2 sui robot Unitree funziona senza reverse engineering e senza nodi di traduzione: il robot pubblica i suoi dati su DDS (CycloneDDS), e ROS 2 usa DDS come strato di comunicazione. Il pacchetto ufficiale unitree_ros2 fornisce le definizioni dei messaggi e gli script di configurazione. I passaggi qui sotto seguono il README ufficiale.

Quali robot Unitree supportano ROS 2

Lo sviluppo software è previsto solo sulle versioni per sviluppatori. Per il Go2, la scheda ufficiale indica l'accesso all'SDK per lo sviluppo software proprio sulla versione EDU, non su Air e Pro; per il G1 vale lo stesso con il G1 EDU.

Per R1 e A2, a ottobre 2026 unitree_sdk2 contiene esempi C++ dedicati, ma unitree_ros2 non ha ancora esempi specifici. Prima di comprare per un progetto solo ROS 2 su questi modelli, verifica lo stato del repository.

Prodotti citati nell'articoloRobot EDU per la ricerca

Unitree Go2 EDU

SDK e ROS 2, batteria 15000 mAh

8.804 € IVA esclusa

Vedi schedaPreventivo

Unitree G1 EDU U1

SDK, 23 DoF, dock di calcolo

38.005 € IVA esclusa

Vedi schedaPreventivo

Unitree B2

Industriale pesante: oltre 40 kg, IP67

66.828 € IVA esclusa

Vedi schedaPreventivo

Requisiti: Ubuntu e versione di ROS 2

Il README di unitree_ros2 riporta due combinazioni testate:

• Ubuntu 22.04 + ROS 2 Humble, indicata come consigliata;
• Ubuntu 20.04 + ROS 2 Foxy.

Secondo la tabella delle release ROS 2, Foxy ha raggiunto la fine del supporto il 20 giugno 2023, mentre Humble è supportato fino a maggio 2027 e Jazzy fino a maggio 2029. Per un progetto che parte oggi la scelta pratica è Humble; Jazzy non compare tra le combinazioni testate da Unitree. ROS 2 Humble si installa da pacchetti Debian seguendo la guida ufficiale.

Installare unitree_ros2 passo per passo

1. Clona il repository e installa le dipendenze. I comandi sono per Humble; con Foxy sostituisci humble con foxy:

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. Solo con Foxy: compila CycloneDDS 0.10.x nella workspace cyclonedds_ws, in un terminale dove ROS 2 non è stato caricato. Il robot usa CycloneDDS 0.10.2; con Humble questo passaggio non serve.

3. Compila i pacchetti dei messaggi (unitree_go, unitree_hg, unitree_api):

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

Rete e CycloneDDS

Collega il PC al robot con un cavo Ethernet. Nelle impostazioni dell'interfaccia imposta IPv4 manuale, indirizzo 192.168.123.99, maschera 255.255.255.0, come indica il README. Con ifconfig o ip a trova il nome dell'interfaccia (per esempio enp3s0) e inseriscilo in ~/unitree_ros2/setup.sh:

#!/bin/bash
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>'

La riga decisiva è RMW_IMPLEMENTATION=rmw_cyclonedds_cpp: il middleware predefinito di Humble è un altro, e senza questa variabile il PC non vede il robot. La documentazione ROS 2 spiega come scegliere il middleware DDS. Senza robot collegato puoi usare setup_local.sh, che lavora sull'interfaccia di loopback.

Primo topic

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

Su Go2 e B2 /sportmodestate riporta posizione, velocità e andatura; /lowstate riporta motori, IMU e batteria. Per compilare ed eseguire gli esempi:

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

Il README mostra anche come visualizzare la nuvola di punti del LiDAR del Go2 in RViz2, sul topic utlidar/cloud con frame utlidar_lidar.

Controllo: alto livello e basso livello

• Alto livello (Go2, B2): richieste su /api/sport/request con messaggi unitree_api, generate dalla classe SportClient degli esempi. Il robot usa il proprio controllo di moto.
• Basso livello: comandi di posizione, velocità, coppia e guadagni su /lowcmd. Prima va disattivato il servizio di moto integrato, altrimenti i comandi si sovrappongono. Sugli umanoidi si entra in debug mode con L2+R2, robot appeso: la procedura completa è nella guida programmare il G1.

Simulare prima dell'hardware

unitree_mujoco è il simulatore ufficiale basato su MuJoCo: accetta programmi scritti con unitree_sdk2, unitree_sdk2_python e unitree_ros2, con gli stessi messaggi di basso livello del robot reale. Si sviluppa in simulazione sull'interfaccia di loopback, poi lo stesso codice gira sul robot cambiando solo l'interfaccia di rete. Per le policy di locomozione c'è unitree_rl_gym (Go2, G1, H1, H1-2).

Errori frequenti

• Nessun topic: RMW non impostato, interfaccia sbagliata in setup.sh o PC fuori subnet. Il README consiglia anche di riavviare il PC dopo la prima configurazione.
• Compilazione CycloneDDS fallita su Foxy: il terminale aveva già caricato /opt/ros/foxy/setup.bash; commenta la riga in ~/.bashrc e riapri il terminale.
• Più installazioni ROS sullo stesso PC: evita di mettere setup.sh in ~/.bashrc e caricalo a mano quando serve.

Per i laboratori universitari Abra Robotics, parte della filiera di distribuzione di Unitree Italia, fornisce i modelli EDU e offre formazione e sviluppo su SDK come servizi separati: vedi Università e Ricerca e Software.