Open Source Robotics

精選高品質的開源機器人專案、工具與軟體,推動機器人社群向前發展。

LeFranX 組裝指南

適用於搭配 XHand 之 Franka 機器手臂與 VR 遠端操作的 LeRobot 擴充套件

授權條款

Apache-2.0

組裝指南

1. 請先閱讀:僅有軟體,沒有需要動手組裝的部分

LeFranX 是加到 LeRobot 程式碼副本中的軟體。原專案沒有公開任何機構組裝內容,因此你必須已經擁有機器人、機器手、電腦與頭戴裝置。

1.1 這個專案是什麼、不是什麼

一個 LeRobot 擴充套件,包含 Franka 伺服器、一個遠端操作套件,以及 Robot 與 Teleoperator 類別,而不是一套套件組。

  1. LeFranX 是適用於 Franka FER 機器人與 XHand 的 LeRobot 擴充套件。其 README 列出三個部分:franka_server、franka_xhand_teleoperator,以及 src/lerobot 下新增的類別實作。
  2. 這個專案沒有需要自行製作的硬體。它的文件沒有列出機架、需要製作的列印零件或要做的接線,也沒有把手裝到手臂上的逐步流程。
  3. 原專案唯一提到的機構件,是另一個儲存庫中用於連接 XHand 與 Franka 的聯結器 CAD 檔(見聯結器一節)。它沒有組裝說明。
  4. README 表示它在 LeRobot commit ce3b9f627e55223d6d1c449d348c6b351b35d082、Ubuntu 24.04 與 Python 3.12 上測試過。原專案文件未涵蓋任何其他 LeRobot commit。
  5. README 也表示,由於作者沒有使用 Franka Hand 夾爪,因此沒有為它開發介面。

1.2 你必須已經擁有的設備

一台附控制介面的 Franka FER 機器人、一隻 XHand、兩台電腦、一副 Meta Quest 頭戴裝置,以及一條 USB-C 資料線。

  1. Franka FER 機器手臂。README 中的 Franka 伺服器需要 libfranka,且 libfranka 版本必須與你的機器人韌體版本相符。
  2. RobotEra XHand。論文所述的硬體是一台裝有 RobotEra XHand 靈巧手的 Franka FER 機器人。程式碼中的預設設定是針對右手。
  3. 一台控制機器人的即時 PC(RTPC)。README 表示,Franka 伺服器必須在即時機器上建置與部署,若是同一台 PC,則在第二個終端機中執行。論文指出 Franka Control Interface 與 libfranka 需要即時 Linux 核心,且作者是在一台與主 PC(用於 VR 與策略推論)分開的電腦上執行。
  4. 一台主 PC,用於 LeRobot、VR 連線與策略相關工作。原專案以 Ubuntu 24.04 與 Python 3.12 測試。
  5. 一副用於 VR 遠端操作的 Meta Quest 頭戴裝置。論文引用的是 Meta Quest 3,而 franka-vr-teleop 的 README 提到的是 Quest 3s。
  6. 一條可傳輸資料的 USB-C 纜線,用於以 adb 連接頭戴裝置。Quest 應用程式本身的 README 要求使用可傳輸資料的 USB-C 纜線。
  7. 選配:用於錄製的相機。論文使用三台 Intel RealSense D435 相機(俯視、第三人稱與手腕安裝),解析度 320x240 像素、30 fps。範例錄製腳本使用 OpenCV 相機,並以註解標示 RealSense 是替代選項。
  8. 一張用於訓練的顯示卡。ACT 訓練腳本使用 --policy.device=cuda。原專案未提供最低顯示卡需求。
  9. 可存取 RobotEra 的文件中心,以下載 XHand Python wheel。README 中有連結。

1.3 安全:原專案說了什麼、遺漏了什麼

原專案針對機器人端的警告很少;在任何會讓手臂移動的步驟之前,請記住這些警告。

  1. 原專案的 README 表示,在使用任何 LeRobot 工具移動手臂之前,要先在 RTPC 上啟動 franka_server。
  2. libfranka 必須與你的機器人韌體版本相符。
  3. franka-vr-teleop 的 README 寫道:VR 世界座標系有一個原點,在應用程式開啟時越過原點會導致座標鏡像。按住 Meta 選單按鈕即可重設世界座標系(在叫出選單按鈕時捏合拇指與食指)。這段說明位於該儲存庫 1.2 版的變更紀錄中,是針對當時的 Quest 應用程式撰寫的。
  4. 同一份 README 表示,當其 bidexhand 參數為 true 時,逆向運動學求解器會限制 J7 的關節範圍,以避免損壞伺服機套筒的連接件。那是針對另一隻手(BiDexHand)。LeFranX 自己的遠端操作器設定 use_bidexhand_limits 預設為 False,其手臂的 q7 限制為正負 2.8973。
  5. xhand_config.py 中的 XHand 設定在關節限制旁附有註解 'Updated to prevent mechanical clogging',並將扭矩電流限制設為 400 mA(default_tor_max),max_torque 設為 300.0。
  6. 原專案文件沒有提供緊急停止、工作空間淨空或外部啟動裝置的相關說明。Franka 自己的機器人文件涵蓋了這些內容,但本指南並未參閱。

2. XHand 連接件(僅有 CAD 檔)

原專案提供將 XHand 安裝到 Franka 上的 CAD 檔連結。它沒有公開列印設定、扣件數量、鎖緊扭矩值或組裝順序。

2.1 取得連接件檔案

從 xhand-coupling 儲存庫下載連接件與攝影機支架檔案;檔案沒有附任何說明。

  1. LeFranX README 的標頭連結到「XHand Coupling CAD」。xhand-coupling 的 README 只寫了:XHand 與 Franka 的直角聯結器。原始檔需 SW2023+。
  2. 該儲存庫的 _stl 資料夾中有以下 STL 檔:Vertical Coupling.STL、Vertical Coupling T.STL、cam_support.STL 與 cam_support D435.STL。
  3. 其中也有 SolidWorks 零件檔:right_angle_coupling.SLDPRT、cam_support.SLDPRT、XHAND-RIGHT.SLDPRT、RealSense_D405.SLDPRT、RealSense_D435.SLDPRT,以及兩個螺絲模型,分別名為 91290A121_Alloy Steel Socket Head Screw.SLDPRT 與 91290A323_Alloy Steel Socket Head Screw.SLDPRT。
  4. 原專案並未說明哪個 STL 檔對應哪個 SolidWorks 檔、該用哪一個、要用什麼材料列印、要用幾支螺絲或鎖在哪些孔。從檔名看來,一個是 D405 用的相機支架、一個是 D435 用的,但 README 並未這麼說。
  5. 該儲存庫沒有授權檔案。在依賴這些檔案之前,請先向作者確認。

3. 即時 PC:建置並執行 franka_server

Franka 伺服器是一支 C++ 程式,在控制機器人的那台電腦上建置,並在任何 LeRobot 指令移動手臂之前先啟動。

3.1 安裝 franka_server 所需的套件

與你的韌體相符的 libfranka、ruckig,以及在 libfranka 版本高於 0.14.0 時需要的 pinocchio。

  1. README 列出 franka_server 的三個相依套件:ruckig、libfranka(必須與你的機器人韌體版本相符)與 pinocchio(若 libfranka 版本高於 0.14.0 則為必要)。
  2. 伺服器的 CMakeLists.txt 也會尋找 Eigen3 與 Threads,並將 libfranka 的安裝路徑預設為你家目錄下的 ws/franka/install 資料夾。
  3. LeFranX 的文件並未說明如何安裝即時核心、libfranka 或 ruckig,只指向 libfranka 與 ruckig 專案。

3.2 建置 franka_server

在 franka_server 資料夾中執行 build.sh。

  1. 在即時 PC 上的 LeFranX 資料夾中:cd franka_server,然後 bash build.sh
  2. 如果 libfranka 安裝在其他位置,build.sh 接受以安裝路徑作為第一個參數;它會把該路徑以 FRANKA_INSTALL_PATH 傳給 CMake。
  3. build.sh 會建立 build 資料夾、以 CMAKE_BUILD_TYPE=Release 進行設定、以 make -j$(nproc) 建置,並印出 ./build/franka_server <robot_ip> 作為執行檔。

3.3 最先啟動 franka_server

以機器人的 IP 位址執行伺服器;每個會讓手臂移動的 LeRobot 指令都需要它正在執行。

  1. 執行:./franka_server [YOUR_FRANKA_ROBOT_IP]
  2. README 表示,在使用任何 LeRobot 工具移動手臂之前,你必須先在 RTPC 上執行此指令以啟動伺服器。
  3. 伺服器監聽 TCP 連接埠 5000(franka_server.cpp 中的常數 PORT)。LeRobot 端預設 server_port 為 5000、server_ip 為 192.168.18.1,這是作者的位址;範例腳本以註解標示,要你填入自己的 RTPC 位址。
  4. 原專案並未記載伺服器的內建限制。在 franka_server.cpp 中,它設定最大關節速度為 {1.5, 1.5, 1.8, 1.8, 2.0, 2.0, 2.0}、加速度為 {4.0, 4.0, 4.0, 4.0, 6.0, 6.0, 6.0}、急動度為 {8.0, 8.0, 8.0, 8.0, 12.0, 12.0, 12.0},並在連線時設定碰撞閾值與關節阻抗。

4. 主 PC:將 LeFranX 加入 LeRobot

LeFranX 不是從 PyPI 安裝;你要把它的檔案複製到 LeRobot 程式碼副本上,再安裝兩個 Python 套件與 XHand wheel。

4.1 將 LeFranX 檔案複製到 LeRobot

將此儲存庫合併到已簽出測試過 commit 的 LeRobot 上。

  1. 將 LeRobot 切換到 commit ce3b9f627e55223d6d1c449d348c6b351b35d082,也就是 README 所說的測試版本。
  2. README 寫道:將儲存庫內的所有內容複製貼上到你的 LeRobot 目錄。其第 3 節「LeRobot classes」針對 src 資料夾重申這一點:複製並與 LeRobot 的 src 目錄下的檔案合併。這會加入框架其他部分所使用的新 Robot 與 Teleoperator 類別(franka_fer、xhand、franka_fer_xhand,以及 VR 遠端操作器)。
  3. 該儲存庫也包含一些 LeRobot 檔案的副本(例如 src/lerobot/scripts/train.py 與 eval.py),因此合併時會覆蓋這些檔案。原專案並未說明如果你的 LeRobot 是不同版本時該怎麼做。
  4. 儲存庫中沒有 requirements.txt,而且這些說明中並不包含以 pip install lerobot 安裝 LeRobot。

4.2 安裝 Franka 遠端操作套件

將 franka_xhand_teleoperator 安裝到你的環境中。

  1. 在 LeFranX 資料夾中:cd franka_xhand_teleoperator,然後 [uv] pip install -e .
  2. [uv] 表示你可以使用 pip 或 uv pip。
  3. 其 setup.py 會從 C++ 原始碼建置兩個 pybind11 模組 weighted_ik_bridge 與 vr_message_router,並透過 pkg-config 或常見的 include 資料夾尋找 Eigen3 標頭檔。

4.3 安裝機器手動作重定向套件

拉取 vr-dex-retargeting 子模組並安裝。

  1. 在 LeFranX 資料夾中執行:git submodule update --init --recursive
  2. 接著:cd vr-dex-retargeting,然後 [uv] pip install -e .
  3. README 表示這是修改自 Yuzhe Qin 的 dex-retargeting 的儲存庫,用於將人手動作對應到機器手。其 pyproject.toml 要求 Python 版本低於 3.13。

4.4 安裝 RobotEra 的 XHand wheel

下載 RobotEra 的 Python wheel,並為你的 Python 版本安裝。

  1. README 表示,你還需要安裝 RobotEra 的 Python API 才能控制 XHand 機器人,並附上 RobotEra 文件中心的 wheel 連結。
  2. 它提到的檔案是 xhand_controller-1.1.7-cp312-cp312-linux_x86_64.whl。它給的指令是:[uv] pip install xhand_controller-1.1.7-cp312-cp312-linux_x86_64.whl,並註明「使用你對應的 Python 版本」。
  3. 如果缺少這個 wheel,程式碼中的 xhand 類別會記錄 'XHand SDK not available - using stub implementation',並在沒有真實機器手的情況下繼續執行,因此請確認沒有出現這則訊息。
  4. 下載頁面位於 RobotEra 那邊,不屬於 LeFranX;原專案文件未說明其授權條款。

4.5 設定 XHand 連線參數

在你將執行的腳本中檢查序列埠與其他 XHand 設定。

  1. XHand 類別預設的設定為 protocol RS485、serial_port /dev/ttyUSB0、baud_rate 3000000 與 hand_id 0。錄製腳本以註解 YOUR XHAND SERIAL PORT 標示序列埠,因此請依你的電腦修改。
  2. EtherCAT 雖被列為一種協定,但程式碼對它會拋出 NotImplementedError,因此請使用 RS485。
  3. 原專案沒有發布 XHand 的接線、電源或轉接說明。也沒有校正程序可執行:程式碼中的 XHand calibrate 方法只是一個佔位(TODO),只會記錄 'XHand calibration completed'。

5. Quest 頭戴裝置與手部追蹤 App

VR 端是另一個儲存庫中的獨立 Quest App;你安裝的版本必須送出 LeFranX 預期的訊息格式。

5.1 找到 Quest app

README 指向 franka-vr-teleop,而它又指向 Quest app 的儲存庫。

  1. LeFranX 的 README 寫道:此外,你還需要從 franka-vr-teleop 儲存庫設定 Meta Quest VR 應用程式。
  2. 那個儲存庫並不是應用程式。其 README 表示 Meta Quest VR 應用程式位於 quest-wrist-tracker 儲存庫。它還包含一個 ROS 2 套件,以及一個來自更早、另一種驅動 Franka 方式的 C++ 機器人客戶端。LeFranX 並不使用那條 ROS 2 路線。
  3. quest-wrist-tracker 儲存庫現在是 Hand Tracking Streamer 應用程式(1.1.0 版,2026 年 3 月 11 日),可從 Meta Quest Store 或 SideQuest 取得,也可作為 APK 透過 adb 上傳。
  4. vr-dex-retargeting 的 README 指向 quest-wrist-tracker 中一個名為 dex-retargeter 的分支。該分支已不再以這個名稱存在;包含相同工作的分支現在名為 obsolete/dex-retargeter-TCP。

5.2 選擇與 LeFranX 訊息格式相符的 app 版本

LeFranX 會從頭戴裝置讀取特定格式的文字行;目前商店版本記錄的是另一種格式。

  1. LeFranX 的 vr_message_router.cpp 監聽 TCP 連接埠 8000,並比對以下格式的行:Right wrist:, x, y, z, qx, qy, qz, qw, leftFist: state,以及以 Right landmarks: 開頭的行。它只比對右手。
  2. 較舊的分支 obsolete/dex-retargeter-TCP(HandTrackingTCP.cs)會傳送到 remotePort 8000,並在手腕那一行附加 leftFist:。其 README 表示,它透過 adb 以 TCP 串流右手關節資料與手腕向量,以及左手握拳狀態。其中含有一個約 65 MB 的預先建置 dexRetargeterTCP.apk。
  3. 目前應用程式的 CONNECTIONS 頁面記載手腕那一行只有七個數字(x, y, z, qx, qy, qz, qw),並表示有線 TCP 預設為 localhost:8000。它沒有提到 leftFist 欄位。
  4. 原專案並未說明 LeFranX 作者使用的是哪個應用程式版本。從檔案來看,較舊的分支符合 LeFranX 的格式,而目前的版本似乎不符合;這點尚未在機器人上試過。
  5. 較舊分支的 README 要求參閱另一個儲存庫(vr-hand-tracking)了解部署與建置細節。該儲存庫說明,要以 Android 作為建置平台、Meta Quest 3/3s 作為建置目標來建置 Unity 專案,然後執行 Build and Run。

5.3 將頭戴裝置切換為開發者模式並連接 adb

使用資料線,啟用 USB 連線,並轉送連接埠 8000。

  1. 直接上傳應用程式之前,請將頭戴裝置設為開發者模式,並允許 USB 連線。應用程式的 README 表示,它是在 Unity 6000.0.65f1 上建置與測試的。
  2. 確認 adb 能偵測到頭戴裝置:adb devices
  3. 轉發連接埠:adb reverse tcp:8000 tcp:8000。用以下指令確認:adb reverse --list
  4. LeFranX 的遠端操作器設定中,setup_adb 預設為 True,會透過 adb_setup.py 替你執行 adb reverse。這需要 adb 在你的 PATH 中;若找不到,程式碼會警告 'Please install Android SDK platform-tools'。
  5. 手臂遠端操作器使用 TCP 連接埠 8000。僅手部的遠端操作器(xhand_vr)預設使用連接埠 8001,註解說明這是為了避免與手臂遠端操作器衝突。Franka 與 XHand 合併的遠端操作器使用一個共用的連接埠 8000。

5.4 了解網路方面的注意事項

有線 TCP 連線較穩定;無線 UDP 可能會將訊息批次送出。

  1. 應用程式的 CONNECTIONS 頁面表示,透過 Wi-Fi 的 UDP 串流高度依賴你的網路,而 DTIM 間隔較高的 Wi-Fi 網路可能導致訊息批次傳送(延遲突增)。為了更可靠的效能,它建議使用有線或無線的 TCP 連線。
  2. 它也表示,透過 USB 的 TCP 通常效能最穩定,Quest 手部追蹤最高約可達 70 Hz。
  3. LeFranX 的腳本使用透過 adb 的 TCP 路線。論文指出系統以 30 Hz 輸出指令。

6. 遠端操作、錄製與重播

scripts/dual_robot 下的腳本會同時驅動手臂與機器手;機器人 IP 等設定寫在腳本內,因此請先修改它們。

6.1 依你的設定修改腳本

在你將執行的腳本中填入你自己的 IP 位址、序列埠、攝影機裝置與路徑。

  1. 原專案的 scripts README 只說細節請參考腳本,而主 README 則說合併機器人時,請在你自己的 Python 腳本中直接呼叫工具方法。因此執行腳本前請先打開來看。
  2. dual_vr_teleoperator.py 中有 server_ip=192.168.18.1,附註解 'Update with your Franka IP',以及 server_port=5000。
  3. dual_vr_record.py 以註解 YOUR FRANKA RTPC IP 標示 server_ip、以 YOUR XHAND SERIAL PORT 標示 XHand 的 serial_port,並以註解 USE YOUR VIDEO STREAM 標示位於 /dev/video18 的相機。它也從 /home/zkweng/lerobot 組出資料集路徑,那是作者的資料夾。
  4. README 的注意事項:合併機器人(Franka 加 XHand)會導致 Draccus 出現循環匯入呼叫,作者透過直接撰寫訓練與部署腳本來繞過這個問題。合併機器人時,請使用 scripts/dual_robot 中的 Python 腳本,而不是單一機器人的 .sh 檔。

6.2 測試 VR 遠端操作

在伺服器與頭戴裝置都準備好後,執行雙遠端操作腳本。

  1. 在 RTPC 上執行 franka_server、連接頭戴裝置並啟動 app 後,執行:python scripts/dual_robot/dual_vr_teleoperator.py
  2. 腳本本身的說明是 'Test script for the dual VR teleoperator (FrankaFER + XHand)'。它會連線到真實的機器人,並呼叫 reset_to_home,將手臂與手移到原點位置。手臂的原點位置是 [0, -0.785, 0, -2.356, 0, 1.571, -0.9],程式碼註解說明這是為 XHand 修改過的。啟動前請保持工作空間淨空。

6.3 錄製示範資料

執行錄製腳本;它需要資料集名稱、片段數量與片段長度。

  1. 執行:python scripts/dual_robot/dual_vr_record.py
  2. 其選項包括 --dataset-name(預設 dual_robot)、--num-episodes(預設 100)、--episode-time(預設 60 秒)、--task、--fps(預設 30)與 --resume。
  3. 錄製時腳本會印出:Press 's' to stop recording, 'r' to re-record current episode。每個片段開始前,它會要求手動確認並讓機器人回到原點。
  4. 論文以 30 Hz 的相機記錄 19 維動作(手臂 7 維、手 12 維),並為三項任務各蒐集了 100 個示範片段。

6.4 重播已錄製的片段

在機器人上重播一個片段,可選擇放慢速度。

  1. 執行:python scripts/dual_robot/dual_robot_replay.py /path/to/dataset --episode 2 --speed 0.5 --robot-ip [YOUR FRANKA ROBOT IP]
  2. 腳本開始前會要求確認;--no-confirm 可略過確認。速度預設為 1.0,片段預設為 0。

7. 訓練並執行策略

原專案的訓練腳本是透過 LeRobot 訓練 ACT 與 Diffusion Policy,而不是視覺語言動作模型。

7.1 訓練 ACT 或 Diffusion Policy

填入雙機器人訓練腳本中的預留欄位並執行。

  1. 執行以下其中之一:python scripts/dual_robot/train_act_policy.py 或 python scripts/dual_robot/train_dp_policy.py
  2. ACT 腳本中有你必須替換的佔位符:[YOUR_DATASET_REPO_PATH](本機絕對路徑)、[REPO_ID_ACT]、[YOUR_WANDB_PROJECT]、[YOUR_OUTPUT_DIR] 與 [YOUR_JOB_NAME]。它設定 chunk_size=8、n_action_steps=8、batch_size=16、steps=100000,並啟用 Weights and Biases 記錄。
  3. 單一機器人時,scripts/franka_fer 與 scripts/xhand 下的 shell 腳本會呼叫 python -m lerobot.scripts.train。ACT 腳本使用 --steps=100000、--batch_size=32 與 --policy.device=cuda;diffusion 腳本使用 --steps 50000 與 --batch_size 32。如果你合併兩個機器人,README 的注意事項同樣適用。

7.2 在機器人上執行訓練好的策略

使用與你所訓練策略類型對應的部署腳本。

  1. 執行以下其中之一:python scripts/dual_robot/dual_robot_deploy_act.py 或 python scripts/dual_robot/dual_robot_deploy_dp.py
  2. ACT 部署腳本中有需要替換的佔位符:[YOUR_FRANKA_IP]、一個相機裝置(註解:USE YOUR VIDEO DEVICE),以及 [YOUR_POLICY_PATH],也就是存放檢查點的資料夾。它會載入編號最新的檢查點資料夾。
  3. 論文透過 LeRobot 以 gRPC 為基礎的策略伺服器,在一台配備 NVIDIA RTX 6000 Ada Generation GPU 的遠端伺服器上執行策略推論,並由一台本機工作站負責機器人控制。論文指出,Diffusion Policy 比 ACT 對推論延遲更敏感,在配備 RTX 4060 GPU 的本機工作站上尤其明顯。
  4. 專案的公開資料集放在 Hugging Face 上的一個集合中,共三個:toaster、orange_cube_pnp_with_force 與 box_pnp。

本網站需要 JavaScript 才能正常運作。請啟用 JavaScript 以瀏覽我們的開源機器人專案。