Programmare il Unitree G1 non significa solo installare un SDK. Bisogna scegliere a quale livello lavorare (comandi di alto livello, controllo diretto dei motori, ROS 2, policy di reinforcement learning), dove far girare il codice e come provarlo senza rischiare il robot. Questa guida mette in ordine gli strumenti ufficiali di Unitree e propone un percorso di lavoro che usiamo nei progetti di sviluppo CALIGO.
Se non hai ancora collegato il robot al PC, parti dalla guida operativa G1: rete, indirizzi IP e modalità debug sono prerequisiti per tutto ciò che segue.
Gli strumenti ufficiali
| Repository | A cosa serve |
|---|---|
| unitree_sdk2 | SDK C++ ufficiale basato su CycloneDDS, con esempi per G1, H2, R1, Go2, B2, AS2 e altri modelli. |
| unitree_sdk2_python | Interfaccia Python dello stesso SDK, utile per prototipi e integrazione con strumenti di machine learning. |
| unitree_ros2 | Messaggi e esempi per comunicare con il robot direttamente da ROS 2. |
| unitree_mujoco | Simulatore MuJoCo che parla lo stesso protocollo dell'SDK: lo stesso codice gira in simulazione e sul robot. |
| unitree_rl_gym | Pipeline di reinforcement learning (Isaac Gym e MuJoCo) con deploy sul robot reale. |
| xr_teleoperate | Teleoperazione con visori XR e raccolta dati per imitation learning. |
Preparare l'ambiente di sviluppo
SDK C++
Il README di unitree_sdk2 indica come piattaforma di riferimento Ubuntu 20.04 LTS su architetture x86_64 e aarch64, con GCC 9.4 e CMake 3.10 o superiore. Le dipendenze e la compilazione sono quelle classiche di un progetto CMake:
sudo apt-get install -y cmake g++ build-essential libyaml-cpp-dev \
libeigen3-dev libboost-all-dev libfmt-dev
git clone https://github.com/unitreerobotics/unitree_sdk2.git
cd unitree_sdk2 && mkdir build && cd build
cmake ..
makePer installarlo a livello di sistema si usa sudo make install, oppure un prefisso dedicato con -DCMAKE_INSTALL_PREFIX. Molti team lavorano su Ubuntu 22.04, ma non è la piattaforma indicata nel README: in caso di errori di compilazione il primo passo è verificare le versioni dei pacchetti.
SDK Python
unitree_sdk2_python richiede Python 3.8 o superiore e CycloneDDS 0.10.2. L'installazione è da sorgente:
git clone https://github.com/unitreerobotics/unitree_sdk2_python.git
cd unitree_sdk2_python
pip3 install -e .Gli esempi si lanciano passando il nome dell'interfaccia di rete collegata al robot, ad esempio python3 ./example/...script.py enp3s0. Dimenticare o sbagliare questo argomento è l'errore più frequente in assoluto.
Dove far girare il codice
- PC esterno via Ethernet — il modo più comodo per sviluppare e fare debug, con IP statico nella subnet
192.168.123.x. - Computer di sviluppo a bordo (
192.168.123.164, Jetson Orin NX sulle EDU) — necessario quando il robot deve funzionare senza cavo o quando la latenza di rete conta. - Mai sul computer di locomozione (
.161), riservato al controllo motorio di Unitree.
Una strategia pratica: sviluppa e testa sul PC, poi sposta sul computer di bordo solo il codice stabile.
Alto livello o basso livello?
Il G1 espone due modi molto diversi di controllo:
- Alto livello: chiedi al servizio di locomozione di Unitree di camminare, fermarsi o cambiare postura. Il bilanciamento resta a carico del firmware. È il punto di partenza giusto per applicazioni, demo e integrazione con percezione e navigazione.
- Basso livello: invii direttamente comandi ai motori (posizione, velocità, coppia, guadagni) e leggi lo stato di giunti, IMU e batteria. Serve per controllori propri e policy di RL. Richiede la modalità debug, che disattiva il servizio di locomozione, e il robot sospeso.
Il G1 usa la famiglia di messaggi unitree_hg, condivisa con H1-2 e AS2, mentre Go2, B2 e H1 usano unitree_go. Quando adatti esempi pensati per un altro robot, controlla di usare i tipi di messaggio giusti.
Simulazione prima del robot
unitree_mujoco è il passaggio che consigliamo sempre prima di toccare l'hardware. Il simulatore è costruito sopra l'SDK: se non specifichi un'interfaccia di rete usa l'interfaccia locale e un domain ID dedicato alla simulazione (1), mentre sul robot reale si usa il domain ID 0 e l'interfaccia collegata. In pratica lo stesso programma passa dalla simulazione al robot cambiando solo la configurazione di rete.
Per la locomozione appresa, unitree_rl_gym segue il flusso Train → Play → Sim2Sim → Sim2Real: addestramento in Isaac Gym, verifica, test incrociato in MuJoCo e infine deploy con deploy_real.py, sempre con il robot in modalità debug. Per ambienti di simulazione più recenti vedi la nostra guida su NVIDIA Isaac e Omniverse.
Teleoperazione e raccolta dati
Per progetti di manipolazione e imitation learning, xr_teleoperate permette di guidare il G1 (versioni 23 e 29 DoF) con Apple Vision Pro, PICO 4 Ultra Enterprise o Meta Quest 3, con mani Dex3-1, Dex1-1, Inspire o BrainCo, e di registrare episodi compatibili con unitree_IL_lerobot. Anche il progetto LeRobot di Hugging Face supporta ufficialmente il G1.
Un percorso di lavoro in 7 passi
- Rete stabile: ping verso .161 e .164, SSH sul computer di sviluppo.
- SDK compilato e primo esempio di sola lettura dello stato (nessun comando inviato).
- Simulazione in unitree_mujoco con lo stesso codice.
- Alto livello sul robot reale, in area sicura.
- Basso livello solo con robot sospeso, guadagni bassi e transizioni graduali.
- ROS 2 se serve integrare navigazione e sensori: vedi ROS 2 su Unitree.
- Deploy a bordo e test di durata, annotando versioni di firmware e SDK.
Errori frequenti
- Nessun dato dall'SDK: interfaccia di rete sbagliata o CycloneDDS di versione diversa dalla 0.10.x.
- Comandi di alto livello ignorati: il robot è in modalità debug.
- Conflitti con ROS 2: più installazioni di CycloneDDS sul sistema o variabili d'ambiente di ROS caricate quando non servono.
- Tipi di messaggio errati: esempi Go2 (
unitree_go) usati sul G1 (unitree_hg). - Codice di basso livello testato a terra: è il modo più rapido per danneggiare il robot.
Domande frequenti
Posso programmare il G1 in Python?
Sì, con unitree_sdk2_python (Python 3.8 o superiore). Per controllori ad alta frequenza molti team preferiscono comunque il C++ dell'SDK ufficiale.
Serve ROS 2 per programmare il G1?
No. L'SDK basta per controllare il robot. ROS 2 è utile quando vuoi riusare pacchetti esistenti di navigazione, percezione o visualizzazione.
Il G1 base si può programmare?
Lo sviluppo secondario è pensato per le versioni EDU, che includono anche il computer di sviluppo a bordo. Prima di acquistare verifica con il venditore cosa è abilitato sulla configurazione esatta.
Quanto tempo serve per arrivare al primo programma funzionante?
Con rete e ambiente già configurati, eseguire un esempio ufficiale è questione di poco. Il tempo vero si spende su rete, versioni delle dipendenze e sicurezza dei test: è lì che un supporto esperto fa risparmiare di più.
Vuoi accelerare lo sviluppo?
CALIGO configura l'ambiente, imposta la simulazione e sviluppa con te le prime applicazioni sul G1, formando il team lungo il percorso. Parliamo del tuo progetto.
Panoramica commerciale e catalogo: Abra Robotics.