Guida al montaggio di LeFranX
Estensione di LeRobot per il braccio robotico Franka con XHand e teleoperazione in VR
Licenza
Apache-2.0
Guida al montaggio
1. Leggi prima questo: solo software, niente da costruire a mano
LeFranX è un software da aggiungere a un checkout di LeRobot. La fonte originale non pubblica alcun montaggio meccanico, quindi devi già possedere il robot, la mano, i computer e il visore.
1.1 Cos'è questo progetto e cosa non è
Un'estensione di LeRobot con un server Franka, un pacchetto teleoperatore e le classi Robot e Teleoperator, non un kit.
- LeFranX è un'estensione di LeRobot per il robot Franka FER e la XHand. Il suo README ne indica tre parti: franka_server, franka_xhand_teleoperator e le implementazioni delle classi aggiunte in src/lerobot.
- Questo progetto non prevede hardware da costruire. I suoi documenti non elencano telaio, parti stampate da realizzare né cablaggi da eseguire, né un percorso passo per passo per montare la mano sul braccio.
- L'unico elemento meccanico a cui rimanda il progetto originale è un repository separato di file CAD per un accoppiamento tra la XHand e il Franka (vedere la sezione sull'accoppiamento). Non contiene istruzioni di assemblaggio.
- Il README dice che è stato testato sul commit di LeRobot ce3b9f627e55223d6d1c449d348c6b351b35d082, con Ubuntu 24.04 e Python 3.12. I documenti del progetto originale non trattano altri commit di LeRobot.
- Il README dice anche che non è stata sviluppata alcuna interfaccia per la pinza Franka Hand, perché l'autore non la usava.
1.2 Cosa devi già possedere
Un robot Franka FER con la sua interfaccia di controllo, una XHand, due computer, un visore Meta Quest e un cavo dati USB-C.
- Braccio robotico Franka FER. Il server Franka del README richiede libfranka, e la versione di libfranka deve corrispondere alla versione del firmware del vostro robot.
- RobotEra XHand. L'articolo indica come hardware un robot Franka FER dotato di una mano robotica ad alta destrezza RobotEra XHand. Le impostazioni predefinite del codice sono per una mano destra.
- Un PC real-time (RTPC) che controlla il robot. Il README dice che il server Franka deve essere compilato e distribuito sulla macchina real-time, oppure eseguito in un secondo terminale se si tratta dello stesso PC. L'articolo dice che la Franka Control Interface e libfranka richiedono un kernel Linux real-time, e che gli autori lo eseguivano su un computer separato rispetto al PC principale usato per la VR e l'inferenza delle policy.
- Un PC principale per LeRobot, il collegamento VR e il lavoro sulle policy. Il progetto originale ha testato con Ubuntu 24.04 e Python 3.12.
- Un visore Meta Quest per la teleoperazione in VR. L'articolo cita il Meta Quest 3 e il README di franka-vr-teleop indica il Quest 3s.
- Un cavo USB-C che trasporti dati, per collegare il visore tramite adb. Il README dell'app per Quest richiede un cavo USB-C abilitato ai dati.
- Opzionale: telecamere per la registrazione. L'articolo usava tre telecamere Intel RealSense D435 (dall'alto, in terza persona e montata sul polso) a 320x240 pixel e 30 fps. Lo script di registrazione di esempio usa una telecamera OpenCV e la segnala con un commento che indica RealSense come alternativa.
- Una scheda grafica per l'addestramento. Lo script di addestramento ACT usa --policy.device=cuda. Il progetto originale non indica una scheda minima.
- L'accesso al centro documentazione di RobotEra, per scaricare il wheel Python della XHand. Il README vi rimanda.
1.3 Sicurezza: cosa dice il progetto originale e cosa tralascia
Le avvertenze del progetto originale per il lato robot sono poche; tienile presenti prima di qualsiasi passaggio che muove il braccio.
- Il README del progetto originale dice di avviare franka_server sull'RTPC prima di usare qualsiasi utility di LeRobot per muovere il braccio.
- libfranka deve corrispondere alla versione del firmware del vostro robot.
- Il README di franka-vr-teleop dice: il sistema di riferimento del mondo VR ha un'origine, e attraversarla mentre l'app è aperta fa sì che le coordinate vengano specchiate. Reimpostate il sistema di riferimento del mondo tenendo premuto il pulsante del menu Meta (avvicinando pollice e indice mentre il pulsante del menu è attivo). Quella nota si trova nel changelog della versione 1.2 di quel repository, scritta per l'app per Quest dell'epoca.
- Lo stesso README dice che, quando il suo argomento bidexhand è true, il risolutore IK limita il campo del giunto J7 per evitare di danneggiare l'attacco del manicotto del servo. Questo riguarda una mano diversa (BiDexHand). L'impostazione del teleoperatore di LeFranX use_bidexhand_limits è False per impostazione predefinita, e i suoi limiti di q7 per il braccio sono più e meno 2.8973.
- Le impostazioni della XHand in xhand_config.py riportano il commento 'Updated to prevent mechanical clogging' accanto ai limiti dei giunti, e impostano un limite di corrente di coppia di 400 mA (default_tor_max) e max_torque 300.0.
- I documenti del progetto originale non forniscono istruzioni su arresto di emergenza, sgombero dell'area di lavoro o dispositivo di attivazione esterno. Questi aspetti sono trattati nei documenti di Franka per il robot, che non sono stati letti per questa guida.
2. L'accoppiamento della XHand (solo file CAD)
La fonte originale rimanda a file CAD per montare la XHand sul Franka. Non pubblica impostazioni di stampa, numero di elementi di fissaggio, valori di coppia di serraggio né ordine di montaggio.
2.1 Scarica i file dell'accoppiamento
Scarica i file dell'accoppiamento e del supporto della telecamera dal repository xhand-coupling; non sono accompagnati da istruzioni.
- L'intestazione del README di LeFranX rimanda a 'XHand Coupling CAD'. Il README di xhand-coupling dice solo: accoppiamento ad angolo retto per XHand e Franka. File sorgente con SW2023+.
- Il repository contiene questi file STL nella cartella _stl: Vertical Coupling.STL, Vertical Coupling T.STL, cam_support.STL e cam_support D435.STL.
- Contiene anche file di parti SolidWorks: right_angle_coupling.SLDPRT, cam_support.SLDPRT, XHAND-RIGHT.SLDPRT, RealSense_D405.SLDPRT, RealSense_D435.SLDPRT, e due modelli di viti chiamati 91290A121_Alloy Steel Socket Head Screw.SLDPRT e 91290A323_Alloy Steel Socket Head Screw.SLDPRT.
- Il progetto originale non dice quale file STL corrisponda a quale file SolidWorks, quale usare, con quale materiale stampare, quante viti usare né in quali fori. I nomi dei file fanno pensare a una staffa per la telecamera D405 e una per la D435, ma il README non lo dice.
- Il repository non ha un file di licenza. Verificate con l'autore prima di fare affidamento sui file.
3. PC real-time: compila ed esegui franka_server
Il server Franka è un programma C++ compilato sulla macchina che controlla il robot, poi avviato prima che qualsiasi comando LeRobot muova il braccio.
3.1 Installa ciò che serve a franka_server
libfranka corrispondente al tuo firmware, ruckig e pinocchio quando libfranka è più recente della 0.14.0.
- Il README elenca tre dipendenze per franka_server: ruckig, libfranka (deve corrispondere alla versione del firmware del vostro robot) e pinocchio (necessario se libfranka è più recente della 0.14.0).
- Il CMakeLists.txt del server cerca anche Eigen3 e Threads, e imposta come percorso di installazione predefinito di libfranka la cartella ws/franka/install nella vostra home directory.
- I documenti di LeFranX non descrivono come installare un kernel real-time, libfranka o ruckig. Rimandano solo ai progetti libfranka e ruckig.
3.2 Compila franka_server
Esegui build.sh dalla cartella franka_server.
- Sul PC real-time, nella cartella LeFranX: cd franka_server, poi bash build.sh
- Se libfranka è installato altrove, build.sh accetta il percorso di installazione come primo argomento; lo passa a CMake come FRANKA_INSTALL_PATH.
- build.sh crea una cartella build, configura con CMAKE_BUILD_TYPE=Release, compila con make -j$(nproc) e indica ./build/franka_server <robot_ip> come eseguibile.
3.3 Avvia franka_server prima di qualsiasi altra cosa
Avvia il server con l'indirizzo IP del robot; ogni comando LeRobot che muove il braccio richiede che sia in esecuzione.
- Eseguite: ./franka_server [YOUR_FRANKA_ROBOT_IP]
- Il README dice che dovete eseguirlo sull'RTPC per avviare il server prima di usare qualsiasi utility di LeRobot per muovere il braccio.
- Il server è in ascolto sulla porta TCP 5000 (la costante PORT in franka_server.cpp). Il lato LeRobot usa per impostazione predefinita server_port 5000 e server_ip 192.168.18.1, che è l'indirizzo dell'autore; gli script di esempio lo segnalano con un commento che vi dice di inserire l'indirizzo del vostro RTPC.
- Il progetto originale non documenta i limiti integrati del server. In franka_server.cpp imposta velocità massime dei giunti di {1.5, 1.5, 1.8, 1.8, 2.0, 2.0, 2.0}, accelerazioni di {4.0, 4.0, 4.0, 4.0, 6.0, 6.0, 6.0} e jerk di {8.0, 8.0, 8.0, 8.0, 12.0, 12.0, 12.0}, e imposta le soglie di collisione e l'impedenza dei giunti al momento della connessione.
4. PC principale: aggiungi LeFranX a LeRobot
LeFranX non si installa da PyPI; copi i suoi file sopra un checkout di LeRobot e installi due pacchetti Python e la wheel della XHand.
4.1 Copia i file LeFranX in LeRobot
Unisci questo repository sopra un checkout di LeRobot al commit testato.
- Fate il checkout di LeRobot al commit ce3b9f627e55223d6d1c449d348c6b351b35d082, il commit su cui il README dice che è stato testato.
- Il README dice: copiate e incollate tutto il contenuto del repo nella vostra directory di LeRobot. La sua sezione 3, LeRobot classes, lo ripete per la cartella src: copiatela per unirla ai file nella directory src di LeRobot. In questo modo si aggiungono le nuove classi Robot e Teleoperator (franka_fer, xhand, franka_fer_xhand e i teleoperatori VR) usate dal resto del framework.
- Il repository contiene anche copie di alcuni file di LeRobot (ad esempio src/lerobot/scripts/train.py e eval.py), quindi l'unione li sovrascriverà. Il progetto originale non dice cosa fare se il vostro LeRobot è di una versione diversa.
- Nel repository non c'è un requirements.txt, e in queste istruzioni LeRobot non si installa con pip install lerobot.
4.2 Installa il pacchetto teleoperatore Franka
Installa franka_xhand_teleoperator nel tuo ambiente.
- Nella cartella LeFranX: cd franka_xhand_teleoperator, poi [uv] pip install -e .
- [uv] significa che potete usare pip oppure uv pip.
- Il suo setup.py compila due moduli pybind11, weighted_ik_bridge e vr_message_router, da sorgenti C++, e cerca gli header di Eigen3 tramite pkg-config o nelle consuete cartelle include.
4.3 Installa il pacchetto di retargeting della mano
Scarica il sottomodulo vr-dex-retargeting e installalo.
- Dalla cartella LeFranX eseguite: git submodule update --init --recursive
- Poi: cd vr-dex-retargeting, poi [uv] pip install -e .
- Il README dice che si tratta di un repository modificato a partire dal lavoro dex-retargeting di Yuzhe Qin, usato per mappare il movimento della mano umana sulla mano robotica. Il suo pyproject.toml richiede Python precedente alla 3.13.
4.4 Installa la wheel XHand di RobotEra
Scarica la wheel Python di RobotEra e installala per la tua versione di Python.
- Il README dice che dovrete anche installare l'API Python di RobotEra per controllare il robot XHand, e rimanda al centro documentazione di RobotEra per il wheel.
- Il file indicato è xhand_controller-1.1.7-cp312-cp312-linux_x86_64.whl. Il comando indicato è: [uv] pip install xhand_controller-1.1.7-cp312-cp312-linux_x86_64.whl, con la nota 'usate la versione di Python corrispondente'.
- Se questo wheel manca, la classe xhand nel codice registra 'XHand SDK not available - using stub implementation' e prosegue senza una mano reale, quindi verificate che quel messaggio non compaia.
- La pagina di download è sul sito di RobotEra e non fa parte di LeFranX; i documenti del progetto originale non ne indicano i termini di licenza.
4.5 Imposta le impostazioni di connessione della XHand
Controlla la porta seriale e le altre impostazioni della XHand nello script che eseguirai.
- La classe XHand è fornita con protocol RS485, serial_port /dev/ttyUSB0, baud_rate 3000000 e hand_id 0. Lo script di registrazione segnala la porta seriale con il commento YOUR XHAND SERIAL PORT, quindi modificatela in base al vostro computer.
- EtherCAT è elencato come protocollo, ma per esso il codice solleva NotImplementedError, quindi usate RS485.
- Il progetto originale non pubblica istruzioni di cablaggio, alimentazione o adattatori per la XHand. Non c'è nemmeno una procedura di calibrazione da eseguire: il metodo calibrate della XHand nel codice è un segnaposto (TODO) che si limita a registrare 'XHand calibration completed'.
5. Visore Quest e app di tracciamento delle mani
La parte VR è un'app Quest separata in un altro repository; la versione che installi deve inviare il formato di messaggio che LeFranX si aspetta.
5.1 Trova l'app per Quest
Il README rimanda a franka-vr-teleop, che a sua volta rimanda al repository dell'app per Quest.
- Il README di LeFranX dice: inoltre, dovrete anche configurare la Meta Quest VR App dal repository franka-vr-teleop.
- Quel repository non è l'app. Il suo README dice che la Meta Quest VR App si trova nel repository quest-wrist-tracker. Contiene anche un pacchetto ROS 2 e un client robot C++ di un precedente metodo, separato, per comandare il Franka. LeFranX non usa quel percorso ROS 2.
- Il repository quest-wrist-tracker è ora l'app Hand Tracking Streamer (versione 1.1.0 del 11 marzo 2026), disponibile su Meta Quest Store o SideQuest, oppure come APK da caricare con adb.
- Il README di vr-dex-retargeting rimanda a un branch di quest-wrist-tracker chiamato dex-retargeter. Quel branch non esiste più con quel nome; il branch con lo stesso lavoro si chiama ora obsolete/dex-retargeter-TCP.
5.2 Scegli una build dell'app che corrisponda al formato dei messaggi di LeFranX
LeFranX legge una determinata riga di testo dal visore; l'attuale release sullo store ne documenta una diversa.
- Il vr_message_router.cpp di LeFranX è in ascolto sulla porta TCP 8000 e riconosce righe nella forma: Right wrist:, x, y, z, qx, qy, qz, qw, leftFist: state, e righe che iniziano con Right landmarks:. Riconosce solo la mano destra.
- Il branch più vecchio obsolete/dex-retargeter-TCP (HandTrackingTCP.cs) invia a remotePort 8000 e aggiunge leftFist: alla riga del polso. Il suo README dice che trasmette via TCP tramite adb i dati dei giunti della mano destra e i vettori del polso, più lo stato del pugno della mano sinistra. Contiene un dexRetargeterTCP.apk precompilato di circa 65 MB.
- La pagina CONNECTIONS dell'app attuale documenta la riga del polso con soli sette numeri (x, y, z, qx, qy, qz, qw) e dice che il TCP via cavo usa per impostazione predefinita localhost:8000. Non menziona un campo leftFist.
- Il progetto originale non dice quale build dell'app abbiano usato gli autori di LeFranX. A giudicare dai file, il branch più vecchio corrisponde allo schema di LeFranX e la release attuale sembra di no; non è stato provato su un robot.
- Il README del branch più vecchio dice di usare l'altro repository (vr-hand-tracking) per i dettagli di distribuzione e compilazione. Quel repository dice di compilare il progetto Unity con Android come piattaforma di build e Meta Quest 3/3s come target, poi Build and Run.
5.3 Metti il visore in modalità sviluppatore e collega adb
Usa un cavo dati, abilita la connessione USB e inoltra la porta 8000.
- Prima di caricare direttamente un'app, mettete il visore in modalità sviluppatore e consentite la connessione USB. Il README dell'app dice che è stata compilata e testata su Unity 6000.0.65f1.
- Verificate che adb veda il visore: adb devices
- Inoltrate la porta: adb reverse tcp:8000 tcp:8000. Verificate con: adb reverse --list
- Nelle impostazioni del teleoperatore di LeFranX setup_adb è True per impostazione predefinita, e questo esegue adb reverse per voi tramite adb_setup.py. Serve che adb sia nel vostro path; se non viene trovato, il codice avvisa con 'Please install Android SDK platform-tools'.
- Il teleoperatore del braccio usa la porta TCP 8000. Il teleoperatore della sola mano (xhand_vr) usa per impostazione predefinita la porta 8001, con un commento che dice che evita un conflitto con il teleoperatore del braccio. Il teleoperatore combinato Franka e XHand usa un'unica porta condivisa, la 8000.
5.4 Tieni conto dell'avvertenza sulla rete
Il TCP cablato è il collegamento più stabile; l'UDP wireless può raggruppare i messaggi.
- La pagina CONNECTIONS dell'app dice che lo streaming UDP via Wi-Fi dipende molto dalla rete, e che le reti Wi-Fi con intervalli DTIM elevati possono causare il raggruppamento dei messaggi (picchi di latenza). Per prestazioni più affidabili consiglia la connessione TCP via cavo o wireless.
- Dice anche che il TCP via USB offre in genere le prestazioni più costanti, arrivando al massimo a circa 70 Hz di tracciamento della mano del Quest.
- Gli script di LeFranX usano il percorso TCP tramite adb. L'articolo afferma che il sistema emette comandi a 30 Hz.
6. Teleopera, registra e riproduci
Gli script in scripts/dual_robot comandano insieme il braccio e la mano; impostazioni come l'IP del robot sono scritte dentro gli script, quindi modificale prima.
6.1 Modifica gli script per la tua configurazione
Inserisci il tuo indirizzo IP, la porta seriale, il dispositivo della telecamera e i percorsi nello script che eseguirai.
- Il README degli script del progetto originale dice solo di consultare gli script per i dettagli, e il README principale dice di chiamare direttamente i metodi di utilità nel proprio script Python quando si combinano i robot. Quindi aprite lo script prima di eseguirlo.
- dual_vr_teleoperator.py ha server_ip=192.168.18.1 con il commento 'Update with your Franka IP', e server_port=5000.
- dual_vr_record.py segnala server_ip con il commento YOUR FRANKA RTPC IP, la serial_port della XHand con YOUR XHAND SERIAL PORT, e una telecamera in /dev/video18 con il commento USE YOUR VIDEO STREAM. Costruisce inoltre il percorso del dataset a partire da /home/zkweng/lerobot, che è la cartella dell'autore.
- L'avvertenza del README: combinare i robot (Franka più XHand) provoca chiamate di import circolari con Draccus, che l'autore aggira costruendo direttamente gli script di addestramento e di distribuzione. Per il robot combinato, usate gli script Python in scripts/dual_robot, non i file .sh per il singolo robot.
6.2 Prova il teleoperatore VR
Esegui lo script del doppio teleoperatore con il server e il visore pronti.
- Con franka_server in esecuzione sull'RTPC, il visore collegato e l'app avviata, esegui: python scripts/dual_robot/dual_vr_teleoperator.py
- La descrizione dello script stesso è 'Test script for the dual VR teleoperator (FrankaFER + XHand)'. Si collega ai robot reali e chiama reset_to_home, che porta braccio e mano nella posizione di riposo. La posizione di riposo del braccio è [0, -0.785, 0, -2.356, 0, 1.571, -0.9], che il codice commenta come modificata per la XHand. Tenete libera l'area di lavoro prima di avviarlo.
6.3 Registra le dimostrazioni
Esegui lo script di registrazione; richiede un nome del dataset, un numero di episodi e una durata degli episodi.
- Eseguite: python scripts/dual_robot/dual_vr_record.py
- Le sue opzioni sono --dataset-name (predefinito dual_robot), --num-episodes (predefinito 100), --episode-time (predefinito 60 secondi), --task, --fps (predefinito 30) e --resume.
- Durante la registrazione lo script stampa: Press 's' to stop recording, 'r' to re-record current episode. Prima di ogni episodio chiede una conferma manuale e riporta il robot in posizione di riposo.
- L'articolo ha registrato azioni a 19 dimensioni (7 per il braccio e 12 per la mano) con le telecamere a 30 Hz, e ha raccolto 100 episodi di dimostrazione per ciascuno dei tre compiti.
6.4 Riproduci un episodio registrato
Riproduci un episodio sul robot, eventualmente più lentamente.
- Eseguite: python scripts/dual_robot/dual_robot_replay.py /path/to/dataset --episode 2 --speed 0.5 --robot-ip [YOUR FRANKA ROBOT IP]
- Lo script chiede una conferma prima di partire; --no-confirm la salta. La velocità predefinita è 1.0 e l'episodio predefinito è 0.
7. Addestra ed esegui una policy
Gli script di addestramento originali sono per ACT e Diffusion Policy tramite LeRobot, non per un modello Vision-Language-Action.
7.1 Addestra una policy ACT o Diffusion Policy
Compila i segnaposto nello script di addestramento a doppio robot ed eseguilo.
- Eseguite uno dei due: python scripts/dual_robot/train_act_policy.py oppure python scripts/dual_robot/train_dp_policy.py
- Lo script ACT ha dei segnaposto da sostituire: [YOUR_DATASET_REPO_PATH] (un percorso locale assoluto), [REPO_ID_ACT], [YOUR_WANDB_PROJECT], [YOUR_OUTPUT_DIR] e [YOUR_JOB_NAME]. Imposta chunk_size=8, n_action_steps=8, batch_size=16, steps=100000, e attiva il logging su Weights and Biases.
- Per un singolo robot, gli script shell in scripts/franka_fer e scripts/xhand chiamano python -m lerobot.scripts.train. Quello ACT usa --steps=100000, --batch_size=32 e --policy.device=cuda; quello diffusion usa --steps 50000 e --batch_size 32. Se combinate i due robot vale l'avvertenza del README.
7.2 Esegui una policy addestrata sul robot
Usa lo script di deployment per il tipo di policy che hai addestrato.
- Eseguite uno dei due: python scripts/dual_robot/dual_robot_deploy_act.py oppure python scripts/dual_robot/dual_robot_deploy_dp.py
- Lo script di distribuzione ACT ha dei segnaposto da sostituire: [YOUR_FRANKA_IP], un dispositivo telecamera (commento: USE YOUR VIDEO DEVICE) e [YOUR_POLICY_PATH], la cartella che contiene i checkpoint. Carica la cartella di checkpoint con il numero più alto.
- L'articolo ha eseguito l'inferenza delle policy su un server remoto con una GPU NVIDIA RTX 6000 Ada Generation tramite il policy server di LeRobot basato su gRPC, con una workstation locale che gestiva il controllo del robot. Riporta che Diffusion Policy era più sensibile alla latenza di inferenza rispetto ad ACT, in particolare su una workstation locale con GPU RTX 4060.
- I dataset pubblici del progetto sono su Hugging Face in una raccolta di tre: toaster, orange_cube_pnp_with_force e box_pnp.