Per programmare l'Unitree G1 servono tre cose: la versione EDU, un PC Ubuntu collegato alla rete interna del robot e l'SDK ufficiale unitree_sdk2. Se il robot è appena arrivato, parti da accensione, telecomando e prima messa in piedi.
Quale G1 si può programmare
Nella scheda ufficiale del G1 lo sviluppo software proprio è previsto solo sul G1 EDU; il G1 base ha 23 gradi di libertà e niente modulo di calcolo per lo sviluppo. Le versioni EDU vanno da 23 a 43 DoF, con modulo di calcolo opzionale (Unitree cita schede Orin) e mani Dex3-1 opzionali. A listino il G1 Air costa 19.809 € e il G1-U1 EDU (23 DoF, dock di calcolo 100 TOPS) 38.005 €, IVA esclusa, spedizione e dazio inclusi. Per scegliere tra U1, U2 e le versioni con mani c'è la guida quale versione del G1 scegliere.
Architettura: dove gira il tuo codice
Il G1 EDU ha un computer di controllo del moto, gestito da Unitree, e un computer di sviluppo (PC2) per il codice utente. I repository Unitree, per esempio xr_teleoperate, indicano PC2 all'indirizzo 192.168.123.164 con utente unitree. La password iniziale la fornisce Unitree; la FAQ sviluppatori e la guida LeRobot per il G1 riportano 123. Cambiala appena il robot entra in una rete condivisa.
Hai due opzioni:
- Codice sul laptop: il PC parla con il robot via DDS sul cavo Ethernet. È la scelta più comoda per sviluppare e fare debug.
- Codice su PC2: lanci il programma via SSH sul robot. Serve per l'autonomia senza cavo e per ridurre la latenza.
ssh unitree@192.168.123.164Configurare la rete del PC
- Collega il PC al robot con un cavo Ethernet.
- Imposta l'interfaccia in IPv4 manuale: indirizzo
192.168.123.99(quello suggerito da Unitree), maschera255.255.255.0. Non usare indirizzi già presenti sul robot, come.164. - Con
ip aoifconfigannota il nome dell'interfaccia (enp3s0,eth0...): tutti gli esempi SDK lo chiedono come argomento. - Verifica con
ping 192.168.123.164. Se non risponde, il problema è di rete: inutile aprire l'IDE.
Una porta Ethernet dedicata (anche un adattatore USB) evita conflitti con la rete del laboratorio.
Installare unitree_sdk2 (C++)
Il README di unitree_sdk2 indica come ambiente di riferimento Ubuntu 20.04, gcc 9.4.0, CPU x86_64 o aarch64 e CMake 3.10 o superiore. Windows non è tra gli ambienti indicati.
sudo apt-get update
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 .. -DCMAKE_INSTALL_PREFIX=/opt/unitree_robotics
make
sudo make installIl make compila anche gli esempi, che finiscono in build/bin/. L'installazione in /opt/unitree_robotics è quella consigliata anche dal simulatore unitree_mujoco.
Oppure Python: unitree_sdk2_python
Il wrapper Python richiede Python 3.8 o superiore e cyclonedds 0.10.2:
git clone https://github.com/unitreerobotics/unitree_sdk2_python.git
cd unitree_sdk2_python
pip3 install -e .Se l'installazione si ferma con "Could not locate cyclonedds", il README spiega come compilare CycloneDDS dal ramo releases/0.10.x e impostare CYCLONEDDS_HOME. Gli esempi per il G1 sono in example/g1/. Nota utile dal README degli esempi: G1 e H1-2 usano i messaggi unitree_hg, mentre Go2, B2 e H1 usano unitree_go.
Debug mode: prima di ogni test low-level
All'accensione il G1 avvia il proprio controllo di moto, che continua a inviare comandi ai motori. Se in parallelo pubblichi su rt/lowcmd, i due flussi di comandi entrano in conflitto. La procedura documentata nella guida di deploy di unitree_rl_gym è:
- accendi il robot appeso all'imbracatura e attendi la modalità a coppia zero;
- premi L2+R2 sul telecomando: il robot entra in debug mode con i giunti in smorzamento;
- solo ora lancia il programma low-level.
In debug mode il robot non tiene l'equilibrio da solo: va lasciato appeso finché il tuo controllore non lo regge.
Primo test: muovere le caviglie
L'esempio g1_ankle_swing_example (sorgente in example/g1/low_level/) legge rt/lowstate, scrive rt/lowcmd e fa oscillare le caviglie. Dalla cartella build:
./bin/g1_ankle_swing_example enp3s0Sostituisci enp3s0 con la tua interfaccia. Se il terminale stampa "CRC Error", il messaggio ricevuto è corrotto o non corrisponde al tipo atteso: controlla cavo, interfaccia e versione dell'SDK.
Per comandi di alto livello (stare in piedi, camminare con velocità impostate) c'è g1_loco_client, che usa il controllo di moto integrato e quindi va lanciato fuori dal debug mode:
./bin/g1_loco_client --network_interface=enp3s0 --get_fsm_idTopic principali
| Topic DDS | Contenuto | Fonte |
|---|---|---|
rt/lowstate | Stato motori, IMU, batteria | esempio ankle swing |
rt/lowcmd | Comandi di posizione, velocità, coppia e guadagni kp/kd | esempio ankle swing |
rt/secondary_imu | IMU del torso | esempio ankle swing, unitree_mujoco |
rt/dex3/left/cmd, rt/dex3/right/cmd | Comandi mano Dex3-1 | esempio g1_dex3_example |
rt/lf/dex3/left/state, rt/lf/dex3/right/state | Stato mano Dex3-1 | esempio g1_dex3_example |
Le mani Dex3-1 hanno topic separati da quelli dei giunti del corpo.
Simulare prima: unitree_mujoco
unitree_mujoco è un simulatore basato su MuJoCo che espone gli stessi messaggi (LowCmd, LowState, SportModeState, IMU del torso per il G1). Un programma scritto con unitree_sdk2, unitree_sdk2_python o unitree_ros2 gira prima in simulazione e poi sul robot. Il simulatore supporta solo lo sviluppo low-level. Per passare al robot si cambiano interfaccia di rete e DDS domain id: il README consiglia 1 in simulazione, mentre sul robot il valore predefinito è 0. Per il reinforcement learning, unitree_rl_gym copre il ciclo train, play, sim2sim (MuJoCo) e sim2real per G1, H1, H1-2 e Go2.
Quando aggiungere ROS 2
L'SDK diretto è la via più corta per motori e test isolati. ROS 2 serve quando devi integrare Nav2, MoveIt, pipeline di visione standard, registrazione con rosbag o più robot nello stesso laboratorio. Il pacchetto unitree_ros2 contiene i messaggi unitree_hg e un esempio low-level per il G1 (g1/lowlevel/g1_low_level_example); Unitree lo ha testato su Ubuntu 22.04 con Humble (consigliato) e su Ubuntu 20.04 con Foxy. Installazione, rete e primo topic sono nella guida ROS 2 su robot Unitree.
Checklist di sicurezza per il laboratorio
- Primi test sempre con robot appeso e area libera intorno.
- Guadagni kp/kd bassi e limiti di coppia conservativi nel primo ciclo di controllo.
- Una persona al telecomando, pronta a portare il robot in smorzamento.
- Stessa versione dell'SDK sul PC e sul robot; dopo un aggiornamento OTA ricontrolla gli esempi.
Abra Robotics offre formazione e sviluppo software sopra l'SDK come servizi separati dall'hardware: dettagli su Software e Università e Ricerca.
Domande frequenti
Si può programmare il G1 base (non EDU)?
No. La scheda Unitree prevede lo sviluppo software proprio solo sul G1 EDU: il G1 base non ha il computer di sviluppo né l'accesso all'SDK.
Che sistema operativo serve sul PC di sviluppo?
Ubuntu. Per l'SDK l'ambiente di riferimento è Ubuntu 20.04; per ROS 2 Unitree consiglia Ubuntu 22.04 con Humble.
Qual è l'indirizzo del computer di sviluppo del G1?
Il PC2 del G1 EDU risponde su 192.168.123.164, utente unitree. Il tuo PC va su un indirizzo libero della stessa subnet.
Perché serve il debug mode prima di un test low-level?
Perché il controllo di moto integrato continua a mandare comandi ai motori. Con L2+R2, a robot appeso, lo fermi e solo allora pubblichi su rt/lowcmd.
Meglio partire dalla simulazione o dall'hardware?
Dalla simulazione. Con unitree_mujoco lo stesso programma passa al G1 cambiando interfaccia di rete e DDS domain id (1 in simulazione, 0 sul robot).
Fonti
- Unitree, scheda prodotto G1 (versioni, DoF, sviluppo con SDK): unitree.com/g1
- Unitree, unitree_sdk2, README ed esempi G1: github.com/unitreerobotics/unitree_sdk2 · example/g1
- Unitree, unitree_sdk2_python: github.com/unitreerobotics/unitree_sdk2_python
- Unitree, unitree_ros2: github.com/unitreerobotics/unitree_ros2
- Unitree, unitree_mujoco: github.com/unitreerobotics/unitree_mujoco
- Unitree, unitree_rl_gym, guida al deploy su robot reale (debug mode L2+R2): deploy_real/README.md
- Unitree, xr_teleoperate (PC2 su 192.168.123.164): github.com/unitreerobotics/xr_teleoperate
- Unitree Document Center, sezione sviluppatori G1: support.unitree.com/home/en/G1_developer
- Hugging Face, documentazione LeRobot per Unitree G1: huggingface.co/docs/lerobot/en/unitree_g1