Open Source Robotics

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

Upkie 組裝指南

開源輪式雙足機器人,具備平衡控制、強化學習環境與組裝文件。

授權條款

Apache-2.0

組裝指南

1. 入門

訂購零件、備齊工具並準備纜線

1.1 訂購零件

先訂購物料清單中列出的零件,因為運送需要一些時間。

  1. 範圍:組裝頁面將列印件連結到 upkie_parts 儲存庫的 commit 8e539b825affe10ad872741564bdc1c19f4df965(2024 年 8 月 12 日)。該版配置包含背蓋、背板、底板、面板、側板、加強件、腳踝、股骨、膝部、脛骨與舵盤。
  2. 警告:upkie_parts 目前的 main 分支(2.0.0 版,2026 年 1 月 14 日)是重新設計的版本,採用一體式軀幹外殼,沒有板件、沒有舵盤,股骨與脛骨各只有一件。原專案的組裝頁面尚未針對它更新,也沒有發布該設計的組裝說明,因此請勿以 2.0.0 版的檔案依照以下步驟操作。
  3. 組裝頁面已於 2026 年 9 月 2 日(upkie 13.0.0 版)從 GitHub wiki 移到文件中。以下軟體步驟中的指令適用於 upkie 13.1.0 版;較早的版本若有不同,該步驟會註明。

1.2 備齊工具

準備以下工具:JST PH 端子用壓接鉗(建議 PA-09)、M2.5 與 M3 螺絲用公制六角起子(建議球頭,例如 DK-03)、焊接 XT 接頭用的烙鐵、斜口鉗,以及 17 mm RC 六角扳手。

  1. 在你的電腦上複製主儲存庫:git clone https://github.com/upkie/upkie.git,然後 cd upkie。原專案表示,安裝軟體時所有指令都從這個目錄執行。

1.3 準備纜線

依原專案纜線頁面的說明,製作通訊纜線(母對母 JST PH-3、26 AWG、42 cm)與電源線(XT-30、14 AWG)。

  1. 通訊線的針腳,從接頭背面看(從線材往接頭看):左邊 CAN_H(通常為藍色),中間 CAN_L(通常為綠色),右邊 GND(通常為黑色)。GND 的位置留空。
  2. 原專案的提示:通訊線請訂購 PVC 線而不是矽膠線,因為比較容易絞合。線徑 24 AWG 至 32 AWG 應該都可以。通訊線是雙絞線。
  3. 電源線:XT-30 接頭,14 AWG 線(16 AWG 也可以),不需絞合。線材頁面列出兩種:致動器之間,母對母,42 cm;接到電源分配板,母對公,20 cm。物料清單列出的長度不同:腿部電源線母對母 400 mm(4 條)與軀幹電源線公對母 30 cm(3 條)。組裝頁面要求 7 條通訊線與 6 條電源線。

2. 3D 列印

以 PETG 列印所有結構件,並裝上熱熔螺帽

2.1 取得零件檔案

從 upkie_parts 儲存庫的 commit 8e539b825affe10ad872741564bdc1c19f4df965 取得可列印檔案,這是組裝頁面所連結的 commit。

  1. 在該 commit 中,torso/、legs/ 與 add-ons/ 資料夾為每個零件都存放一個 STL 檔案與一個 3MF 專案檔。3MF 檔案帶有切片設定。3MF 檔案已於 2026 年 3 月 13 日從 upkie_parts main 移除,因此請使用該 commit,而不是目前的 main 分支。
  2. 目前的 upkie_parts main 分支需要 Git LFS(其 README 如此說明)。固定的 commit 沒有 .gitattributes 檔案,因此其中的檔案都是一般檔案。

2.2 列印軀幹零件

以 PETG、0.2 mm 層高列印軀幹零件:back covers、back plates、battery shore plug、battery stud、bottom plate、face plate、head plate、stiffener bottom 與 stiffener top 各 1x,以及 side plate 2x。

  1. 原專案依零件列出的填充率:背蓋(下)20%、背蓋(上)20%、背板(下)60%、背板(上)60%、電池支撐插塞(選配)40%、電池座(左)30%、電池座(右)30%、底板 40%、面板 60%、頭板 40%(錐體部分 100%)、側板 60%、加強件(下)20%、加強件(上)20%。
  2. 原專案表示,大多數填充率是推測值,並非來自觀察機器人跌倒後零件斷裂的情形。所有零件都是用 Prusa i3 MK3S+ 列印的;使用其他印表機時,請匯入 STL 檔案並套用相同設定。

2.3 列印腿部零件

以 PETG、0.2 mm 層高列印腳踝、股骨、膝部、脛骨與輪轂各 2x,以及舵角 4x;並在輪轂的六角聯軸器接頭處套用填充修改器。

  1. 選配的把手(固定 commit 中的 add-ons/handle)現在或之後任何階段都可以列印。

2.4 裝入熱熔螺帽

用烙鐵將熱熔螺帽裝入列印零件:依原專案的表格,70 顆 M3x5x4 與 15 至 18 顆 M2.5x4x4。

  1. 依零件:電池座左 1、右 1(M3x5x4);背蓋 2 件,各 5 個,共 10 個(M2.5x4x4);底板 4 個(M2.5x4x4,表格的總計欄寫 1);股骨 2 件,各 4 個,共 8 個(M3x5x4);頭板 4 個(M2.5x4x4);側板 2 件,各 26 個,共 52 個(M3x5x4);脛骨 2 件,各 4 個,共 8 個(M3x5x4)。
  2. 物料清單列出 100 個 M3x5x4 與 8 個 M2.5x4x4 嵌件。8 個少於上表所需的 15 至 18 個,因此 M2.5x4x4 嵌件請買得比物料清單那一列寫的更多。
  3. 如果你是第一次使用熱熔嵌件,原專案推薦 Hackaday 的文章「Threading 3D Printed Parts: How To Use Heat-Set Inserts」。

2.5 組裝電池座

以兩顆電池彈簧、一條紅色與一條黑色電源線、一個 XT90-S 接頭、M3x5x4 熱熔螺帽與兩顆 M3x8 螺絲,組裝電池座的兩半。

  1. 電池座的兩半並不對稱。請分辨出與電池正極配合的那一半,以及與負極配合的那一半。
  2. 將一條紅色電源線穿過正極那一半的孔,並在線上焊接一個電池彈簧。用一條黑色電源線與另一半重複此步驟。
  3. 將兩個電池彈簧推入定位,讓其平面部分與列印件齊平。
  4. 將紅色與黑色線焊入 XT90-S 接頭。
  5. 在每一半電池座對應的孔中各插入兩個 M3x5x4 熱熔嵌件,然後用兩顆 M3x8 螺絲將兩半結合。

3. Raspberry Pi 設定

燒錄 OS 映像檔並設定網路存取

3.1 建置 OS 映像檔

在 upkie 儲存庫的 tools/raspios 目錄中執行 make,建置客製 Raspberry Pi OS 映像檔。

  1. tools/raspios 的 Makefile 會執行 docker、curl 與 jq,下載最新的 pi3hat_spine release 資產,並用 Packer 建置映像檔。原專案在 13.1.0 版的 release 資產中沒有發布現成的映像檔(只有 pi3hat_spine 與 Bullet spine 壓縮檔)。
  2. 文件將產出稱為 raspios_upkie.img;Makefile 會將它重新命名為 raspios_upkie-VERSION.img(例如加上最新的版本號),並寫出 .sha1 與 .sha256 校驗檔。
  3. 映像檔以 2024-03-12 的 Raspberry Pi OS Bullseye arm64 為基礎,並建立使用者 pi,密碼為 raspberry。

3.2 燒錄 SD 卡

將映像檔寫入物料清單中的 microSDXC 卡(U3、V30、A2)。

  1. 將映像檔寫入物料清單中的 microSDXC 卡(U3、V30、A2)。

3.3 設定網路

接上螢幕、鍵盤與滑鼠啟動 Raspberry Pi,以使用者 pi、密碼 raspberry 登入,連上區域網路,並在 SSH 設定中加入 upkie 主機。

  1. 原專案的範例假設機器人的 IP 位址為 192.168.0.42。之後就可以用 ssh [email protected] 登入。
  2. 為了方便,將以下內容加入你的 ~/.ssh/config 檔案,並將 upkie 換成你偏好的暱稱:Host upkie、Hostname 192.168.0.42、User pi(三行)。
  3. make upload 等 Makefile 規則假設已設定名為 upkie 的主機。物料清單為螢幕列出一條 micro HDMI 線。

4. 電子測試

組裝前先設定伺服機 ID、測試 CAN 通訊,並確認所有致動器正常

4.1 測試檯配置

設定測試檯:將附 pi3hat 的 Raspberry Pi 接到電源分配板,並以電源線與通訊纜線,將每條腿的 hip qdd100、knee qdd100 與 wheel mj5208 dev kit 菊鏈串接。

  1. 桌上的配線(4.1):裝有 pi3hat 的 Raspberry Pi 以一條短的公對母電源線接到電源分配板,並以通訊線接到每個髖部 qdd100。電源分配板以 XT-90 電源線接到電池,接到 pi3hat,並以短的公對母電源線接到每個髖部 qdd100。每個髖部 qdd100 接到一個膝部 qdd100,每個膝部 qdd100 再接到一個輪子 mj5208,皆以電源線與通訊線連接(菊鏈)。每條腿都有自己的通訊匯流排。
  2. 為電源分配板上電(4.2):將電源開關接到電源分配板;將電池座上的 XT90-S 接頭接到電源分配板;將電池裝入電池座;撥動開關。電源分配板上應該會亮起紅色 LED。
  3. 為 Raspberry Pi 與 pi3hat 上電(4.3):將 pi3hat 插在 Raspberry Pi 上方,用 pi3hat 隨附的 4 組螺帽、螺絲與六角支柱鎖固。先關閉系統電源:系統通電時,絕不可連接或拔除電源線。用一條公對母 XT30 線將 pi3hat 接到電源分配板,然後為電源分配板上電。pi3hat 與電源分配板上都應該會亮起紅色 LED。

4.2 設定伺服機 ID

透過 USB 使用 tview 軟體設定伺服機 ID:1=左髖、2=左膝、3=左輪、4=右髖、5=右膝、6=右輪。

  1. 對每個伺服機:以 USB 連接到電腦,在 tview 中前往 configuration 分頁,將 id.id 設為所需的值,關閉 tview 並以新的 ID 重新啟動(tview -t X),確認主控台有列出設定參數(若清單是空的,表示通訊有問題),然後在主控台執行指令 conf write,永久儲存該 ID。
  2. 原專案推薦 mjbots 的 moteus 開發套件設定影片。

4.3 逐一測試伺服機

先測試左髖伺服機:將它接到電源分配板(電源)與 pi3hat 的 JC1(通訊),以 ssh pi@upkie 登入,執行 sudo moteus_tool -t 1 -c,再用 conf enumerate、d stop 與 d pos 測試。

  1. 先關閉系統電源:系統通電時,絕不可連接或拔除電源線。(原專案在連接左髖之前重複了這一點。)

4.4 製作 CAN 終端電阻

製作兩個 CAN 終端電阻:在一顆 120 Ohm 電阻的兩端壓上 JST PH 端子,插入 JST PH-3 接頭的 CAN_H 與 CAN_L 孔,再在電阻外套上熱縮套管。

  1. 原專案表示,由於 40 cm 的通訊線相對較長(線材頁面寫 42 cm),所以需要終端電阻。它也提到現成的 JST PH3 CAN-FD Terminator 可作為替代。

4.5 完整系統測試

關閉電源,以菊鏈方式將左腿(IDs 1、2、3)接到 JC1、右腿(IDs 4、5、6)接到 JC3,在每顆車輪伺服機空著的資料接頭插上終端電阻,開啟電源,再用 moteus_tool 檢查每顆伺服機。

  1. 先關閉系統電源:系統通電時,絕不可連接或拔除電源線。
  2. 以 ssh pi@upkie 登入,並對每個伺服機 ID X 執行 sudo moteus_tool --pi3hat-cfg "1=1,2,3;3=4,5,6" -t X -c,然後以 conf enumerate、d stop 與 d pos 測試。原專案的頁面在此處印的是 "1=1,2,3;2=4,5,6",但它自己的文字將右腿放在匯流排 3(JC3),而原專案的 tools/hard_rezero 與 tools/configure_servos 都使用 "1=1,2,3;3=4,5,6"。上面這行依照的是腳本。

5. 運動控制軟體

在機器人上安裝並設定平衡軟體

5.1 設定伺服機限制

在機器人上進入 tools 目錄,執行 ./configure_servos,並確認每一行輸出都是 OK 或 AOK。

  1. 較舊的版本:在 upkie release v5.0.0 至 v11.0.0 中,腳本是 tools/setup/configure_servos.py,一個 Python 腳本。從 v12.0.0 起則是 tools/configure_servos,沒有 .py 副檔名。如果你取出的是較舊的版本,請使用你手上版本的路徑與名稱。
  2. 閱讀原專案檔案後的註記:tools/raspios 中建置的 Raspberry Pi OS 映像檔會在 /usr/local/bin 安裝 hard_rezero、stop_servos、upkie_tool、vcgenall 與 pi3hat_spine,但沒有 configure_servos,而 make upload 會將儲存庫的 tools 目錄複製到機器人上。原專案的頁面將此步驟放在上傳步驟之前,且沒有說明 tools 在機器人上的位置,因此若找不到它,請先上傳。

5.2 建置並上傳軟體

在你本機的 upkie 副本中執行 make build,建置 pi3hat spine,然後連上機器人的 Wi-Fi 網路,執行 make upload 將它複製到機器人上。

  1. 第一次執行 make build 時需要網路連線。make upload 會在 Raspberry Pi 上建立一個遠端目錄,內含執行 spine 與 agent 所需的檔案副本。它會連到你 SSH 設定中名為 upkie 的主機。
  2. 使用不同暱稱:原專案的頁面寫的是 make upload UPKIE_HOST=your_nickname。release v13.1.0(2026 年 10 月 11 日)的 Makefile 則改用 REMOTE_HOST 與 REMOTE_PATH(src/upkie),而 release v13.0.0 使用 UPKIE_HOST 與遠端目錄 upkie;請檢查你手上 Makefile 中的變數名稱。
  3. 較舊的版本:make pack_pixi_env 與 UPKIE_NAME 變數(例如 make upload UPKIE_NAME=your_robot_hostname)在 upkie release v9.0.0 至 v12.0.0 的 Makefile 中是實際存在的(UPKIE_NAME 自 v1.5.0 起)。它們已在 2026 年 10 月 1 日發布的 13.0.0 版中移除。

5.3 測試平衡

將 USB 控制器接到 Raspberry Pi,以 pi3hat_spine 啟動 pi3hat spine,然後在第二個 shell 中,於 upkie 目錄執行 pixi run real-follow-joystick,此時 Raspberry Pi 要上下顛倒拿著。

  1. USB 控制器負責傳送指令(例如用搖桿四處移動),同時也是緊急停止:按下右鍵(Xbox 控制器上的紅色按鈕)會立即關閉所有馬達。每次在機器人上執行新的 agent 時,都請將緊急停止放在手邊。
  2. 將 Raspberry Pi 拿在手上,只接觸電路板的側邊,並將它上下顛倒拿著,就像組裝好的機器人直立時那樣。轉動它:qdd100 伺服機應該保持不動,而兩個 mj5208 伺服機朝相反方向轉動。
  3. 較舊的版本:make run_mpc_balancer 在 upkie release v9.0.0 至 v12.0.0 的 Makefile 中是實際存在的目標,從 v13.0.0 起則沒有。

6. 最終機構組裝

以所有準備好的子組件組裝出完整的機器人

6.1 頭板組裝

用四根 M2 六角間隔柱將 Raspberry Pi 安裝到頭板上,USB 連接埠朝向印有 'USB' 字樣的一側,再用隨附的四顆 M2 螺絲將 pi3hat 裝在 Pi 上方。

  1. 原專案還寫道:「將頭部裝到左右板上,使 USB 側位於機器人的右邊(眼睛朝前,電池在後)。」其 6.5 步驟則說頭板的 USB 側位於機器人左邊,XT30 側位於右邊。兩種說法互相矛盾;鎖固前請參閱衝突說明並檢查原專案的照片。
  2. 原專案警告,頭部裝反會讓 XT-30 電源線難以插入,而且需要修改機器人 URDF 中 IMU 座標系的方向。

6.2 軀幹組裝

用四顆 M2.5x6 螺絲將電源分配板鎖到臀板上,用六顆 M3x8 螺絲將電池接頭鎖到面板上,再用 M3x8 螺絲將面板與左右側板鎖到臀板上。

  1. 電池接頭裝到面板上之後,組件就不對稱了:電池接頭的尖端指向機器人的左側,略偏面板左方。
  2. 確認電源分配板的 XT90 那一側位於機器人的左邊。

6.3 頭部整合

將頭板鎖到面板與左右側板上,用 M3x8 螺絲將兩片補強板鎖到前板上,用十顆 M2.5 螺絲裝上兩片內蓋,然後插上電池。

  1. 確認頭板的 USB 側位於機器人的左邊,XT30 側位於右邊。原專案表示,這個方向對硬體(線材長度適合這個方向,換成另一個方向就太短)與軟體(IMU 裝在頭板上)都很重要。這與 6.1 互相矛盾;請參閱衝突說明。
  2. 先不要裝內蓋,等加強件裝上之後再裝。將電池插入接頭:應該會發出清脆的喀噠聲。

6.4 腳踝組裝(x2)

每個腳踝:用 M3x8 螺絲將 mj5208 馬達鎖到輪轂上,將列印的腳踝零件鎖到 moteus devkit 支架上,裝上車輪六角聯軸器,再用 17 mm 六角扳手鎖緊車輪。

  1. 用內六角起子將 moteus r4 開發套件支架(同時固定著 mj5208 與其 moteus 板)從 3D 列印的黑色開發套件框架上卸下。不要將 mj5208 或 moteus 從支架上拆下。
  2. 用 M3x8 螺絲將 mj5208 鎖到輪轂上,使用 3 個外側螺絲孔(三角形排列),而不是中心兩側相對的 2 個內側孔。
  3. 將列印的腳踝零件鎖到開發套件支架上;PCB 應該能放入其中。
  4. 將輪子六角聯軸器的輪轂側插到輪轂頂部的圓柱上。原專案表示,你可能需要稍微切開塑膠來攻出螺紋,可能需要較小的螺絲起子清除擋住的塑膠,也可能需要鬆開再重新鎖上,讓馬達與輪轂之間的間隙儘量小,且每顆螺絲處都一樣。
  5. 將插銷插入小孔,把兩個零件鎖在一起。
  6. 將輪轂插入輪子內。將聯軸器的六角形對準輪圈上的六角孔:對準時會喀噠一聲,輪轂會完全進入輪胎內。若輪轂從另一側凸出,請從另一側輕輕推出(或小心敲出),再試一次。
  7. 用 17 mm 六角扳手鎖上輪子六角聯軸器的最後一段,將輪子鎖在輪轂上。

6.5 腿部組裝(x2)

每條腿:將通訊纜線與電源線穿過纜線套管,將脛骨鎖到腳踝上,讓纜線穿過脛骨與股骨,再裝上 qdd100 髖部與膝部馬達以及舵盤。

  1. 剪下約 3 至 4 cm 的熱縮套管(每組線材 2 段),套在線材末端、距離接頭幾公分處並加熱。小心不要加熱到線材的外套:它可能會熔化。在每組線材的一端貼上可移除的膠帶;把膠帶做成尖的「鼻子」,有助於將線材穿過脛骨與股骨。
  2. 將脛骨的接頭接到輪子馬達。用七顆 M3x12 螺絲(或 M3x10,但不能用 M3x8)將 qdd100 髖部馬達鎖到主體上。
  3. 將髖部馬達裝到 T 形舵盤上,將股骨連同其線材插入 T 形部件內,並將接頭接到馬達,留一些餘量讓馬達可以轉動。
  4. 用馬達上的三個小孔(不是三個較大的孔)將 qdd100 膝部馬達裝到 T 形舵盤上。將圓形舵盤裝到馬達的另一側,將脛骨插入圓形舵盤,把兩個零件鎖在一起,再將線材接到馬達(先接資料線,再接電源線)。

6.6 最終連接與校正

用有標示的通訊纜線將左髖接到 pi3hat 的 JC1、右髖接到 JC3,再用軀幹電源線將兩側髖部接到電源分配板,然後在雙腿伸直的狀態下,於機器人上的 tools 目錄執行 sudo ./hard_rezero,將伺服機歸零。

  1. 用標示 JC1 的通訊線將左髖 qdd100 的 CAN 接到 pi3hat 的 JC1,用標示 JC3 的通訊線將右髖 qdd100 的 CAN 接到 JC3。左右兩個 qdd100 各用一條軀幹電源線接到電源分配板。原專案在 4.3、4.5 與 4.7 節說明了「系統通電時,絕不可連接或拔除電源線」的規則;6.8 節沒有重複,但涉及相同的配線。
  2. 零位配置是指兩條腿都伸直。讓機器人底座儘量垂直,並晃動兩條腿讓它們儘量垂直(髖部與膝部有些摩擦)。以 ssh upkie 登入,然後執行 cd upkie/tools 與 sudo ./hard_rezero。
  3. 做過一次硬歸零之後,不需要每次開機都重做。之後在機器人上的 upkie 目錄中以 ./tools/upkie_tool rezero 執行軟歸零;它只需要機器人大致直立(髖關節與膝關節在真實零位的 60 度以內)。
  4. 第一次執行(6.10):在你電腦上的 upkie 儲存庫中執行 make upload;以 ssh upkie 登入;執行軟歸零;在機器人上的 upkie 目錄中執行 make run_pi3hat_spine;在另一個終端機中執行 pixi run real-follow-joystick。若一切正常,當你在空中將機器人往前傾時,輪子會向前加速;確認轉向正確後,再將它放到地面上。release v13.1.0 的 Makefile 會上傳到機器人上的 src/upkie 而不是 upkie,因此上述 cd 指令可能需要加上這個前綴。
  5. 第一次執行時,如同先前的軟體測試,請將緊急停止(控制器的右鍵)握在手中。

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