Microduck 組裝教學：從零件、系統安裝到雙足機器人第一次行走

在網路上看到一個很適合小朋友們學習機器人的專案，想推薦給大家，要把 AI 放進機器人，和在電腦上跑一個聊天模型，是兩種很不同的實作。程式可以重新執行，但舵機方向裝反、電壓接錯，或姿態感測器固定不牢，機器人不會靠多問幾次提示詞就自己修好。

Microduck 是一個小型雙足機器人專案，透過 3D 列印結構、Dynamixel 舵機、姿態感測器與預先訓練的行走策略，將模擬中的控制能力帶到實機。AI-FanGe 整理的建置版本提供原始碼與預建系統映像，讓第一次組裝不必同時從零處理作業系統、依賴套件和強化學習訓練。

我認為這個專案最適合拿來學習的，是機械、電控、感測與模型之間怎麼配合。先把同一個版本穩定復刻，再談換舵機或增加功能，會比一開始就把所有零件都改成便宜替代品更容易成功。

先看懂架構：Pi 負責推論，舵機負責動作

Microduck-build-tutorial把軟體分成兩個主要目錄。microduck/是在 Raspberry Pi Zero 2 W 上執行的部署程式，mjlab_microduck/則是 MuJoCo／MjLab 強化學習訓練環境。兩者不要混為一談。

• 感測：IMU 提供姿態與角速度，舵機回報關節狀態。
• 指令：鍵盤或藍牙手把提供前進、後退與轉向需求。
• 推論：Pi 載入 walk.onnx，根據目前狀態與指令產生關節目標。
• 執行：Pi 經 USB 連到 OpenRB-150，再透過 Dynamixel 通訊總線控制舵機。
• 回授：下一輪讀取新的姿態與關節狀態，持續修正動作。

這裡的 AI 是行走控制策略，不是大型語言模型在即時逐句指揮每一顆馬達。預建映像已包含策略，第一次復刻不需要先訓練。若之後改變結構、重量或致動器特性，才需要重新評估原本模型能不能沿用。

本次復刻的範圍是運動模組，不包含攝影機與語音對話。會走路、會轉頭，不代表已經能看懂環境或和你聊天，這些功能需要另外加上感測硬體與軟體。

想比較不同開源機器人的學習方向，可以接著看站內的 HopeJR 機器人與手臂控制介紹。機械操作與雙足步態的目標不同，但都需要把感測、驅動與控制策略一起考慮。

採購前先對版本，別把兩份 BOM 混在一起

截至 2026 年 9 月 8 日查核，這份教學採用 Pi Zero 2 W 與 OpenRB-150。完整機械配置可裝 15 顆舵機，但目前 README 與行走程式實際控制的是 14 顆 XL330-M288-T，對應雙腿 10 顆、頭頸 4 顆。嘴部 ID 15 是額外的開合關節，不是目前行走策略必要的關節。採購時先決定是否要裝嘴部，別把「15 顆機械結構」誤認為「行走模型一定需要 15 顆」。

但 microduck/docs/bom.md仍可看到包含 19 顆舵機、RPI Robot HAT 與另一種電池配置的資料。這代表文件中存在不同配置，不能拿舊清單的數量、電源接法與目前部署程式隨意拼在一起。本文以本次教學的根目錄 README 與目前程式為主。

零件	數量	用途
Pi Zero 2 W	1	執行控制與行走策略
OpenRB-150	1	連接舵機通訊總線
XL330-M288-T	14 + 選配 1	雙腿 10、頭頸 4、嘴部 1
BNO08x IMU	1	量測姿態與角速度
microSD	1	16GB 起，32GB 較寬裕
3D 列印結構件	1 套	依本版本模型製作
供電與開關	1 套	電壓、電流另行核對
螺絲與線材	依裝配	固定、通訊與供電

另外還需要能進行列印或代印的管道、合適螺絲起子、電表，以及必要的線材處理工具。電池、穩壓、保險與線徑不能只照名稱採購，必須依實際電壓、峰值電流與接頭規格確認。

舵機為什麼不能只看價格，直接換成便宜的？

DIY 不一定比買成品便宜，尤其多顆智慧舵機容易成為主要支出。除了馬達本身，還要計入列印失敗、接頭、工具、運費與備品，因此我不會把不同版本、不同地區的舊價格直接加總，當成今天一定能買到的總預算。

替代舵機需要比對的，也不只是扭力。外殼尺寸、固定孔、輸出軸、重量、速度、間隙、通訊協定、回授資料與控制延遲都可能不同。機械上裝得進去，不代表控制程式相容，更不代表原本的行走策略還能保持平衡。

如果真的要更換，應先確認結構能否固定，再處理驅動介面與關節校正，接著檢查模擬中的致動器參數，必要時重新訓練。並非每次更換都必須從零重做，但也不能預設只改一個型號名稱就能走。若只是想先學機器人組裝，也可以參考站內的 Pupper 開源機器狗實作，比較四足與雙足平台的學習需求，舊文價格則不應當作目前報價。

下載原始碼與列印檔，先完成不通電的裝配

原始碼可從 GitHub 專案頁下載 ZIP，或在開發電腦使用 Git。這一步只取得檔案，不會操作機器人。

git clone https://github.com/AI-FanGe/Microduck-build-tutorial.git
cd Microduck-build-tutorial

根目錄提供 microduck3D打印.3mf，microduck/cad/也有 CAD 相關檔案。先確認檔案與目前採用的裝配版本一致，不要把不同版本的腿、頭部與電源艙混印。PLA 可以作為起點，但方向、支撐、孔位與配合公差仍須依實際零件確認。

• 先整理左右腿與頭頸零件，確認沒有鏡像裝反。
• 檢查螺絲長度，避免頂住舵機內部或穿透結構。
• 預留關節活動所需線長，但不要讓線材垂進齒輪或夾點。
• 先對好舵機中立位置與零點，再固定輸出端，不能只憑外觀鎖緊。
• 首次通電前再確認所有固定件、極性與絕緣，調整接線時先斷電。

組裝可以分成腳部與左右腿、軀幹支架、頸部、頭部，再合體整理線材。先鎖好之後會被其他零件擋住的螺絲孔，再裝覆蓋其上的舵機。從動盤與支撐環也要檢查轉動阻力，不能用過度鎖緊來換取表面上的穩固。電池尺寸與控制板位置會影響空間和重心，別以強塞方式固定。

供電是最重要的關卡，不要靠關閉保護解決問題

教學 README 寫的是成品 6V 電池方案，但「標示 6V」不代表充飽後、空載時或負載變化時都恰好是 6.0V。必須量測實際輸出，並確認整條供電路徑符合零件規格。

依 ROBOTIS XL330-M288-T 原廠文件，輸入範圍為 3.7 至 6.0V，建議電壓為 5.0V。不要把超過上限的電池直接接到 XL330，也不要為了讓機器繼續動就取消輸入電壓錯誤保護。如果電壓不穩，應先處理電源、線材與負載問題。

另外，OpenRB-150 原廠規格的板子輸入範圍，不等於舵機也能承受同樣電壓。原廠也列出 DYNAMIXEL 埠電流限制，14 顆舵機同時動作時，不能假設一條 USB 線或板載電源路徑一定足夠。Pi 應有穩定的 5V 供電，舵機電源、分配方式與共地則要依控制板文件設計，不能把板上的小電流 5V 腳當成整機電源。

這次實作的關鍵，是把舵機的大電流供電與控制板通訊分開，舵機有獨立的配電路徑，Pi 則由穩壓後的 5V 供電。這與 README 中較簡化的電源流程描述並不完全相同，因此不能只看總線連線就認定所有電力都經過 OpenRB。若採外部舵機配電，須核對 VDD 隔離、共地、線徑與保護，不讓外部電源反灌控制板，也不要照著線色猜接法。

程式中的電壓模型參數也不是硬體額定值，不能看到模擬常數就照著供電。沒有電路與電池經驗時，先請熟悉硬體的人檢查，不建議把自行製作電池組當成第一次實作。測試時使用支架或安全吊掛，手指遠離活動關節，並保留能立即切斷動力的方式。

設定舵機 ID 與 IMU，讓軟體認得實際裝配

舵機最好在正式串接前逐顆設定與標記。OpenRB-150 可以搭配 DYNAMIXEL Wizard 2.0，原廠預設提供 usb_to_dynamixel韌體。若板子曾被改刷其他程式，需先確認它仍處於可用的 USB 通訊橋接模式。

目前教學使用 Protocol 2.0 與 1Mbps。ID 必須和程式一致，線在總線上的實際排列不等於 ID 會自動依序產生。

在 Wizard 中先只接一顆舵機，Scan 找到裝置後設定 ID 與通訊速度，再依目前設定核對 Return Delay Time。確認周圍無干涉後，才啟用扭矩讓它回到中立位置，接著斷電再裝配。未設定的舵機可能都是相同 ID，一次全部串上會難以分辨。不要把操作示範中的保護關閉動作視為必要步驟。

• 右腿 ID 1 至 5：右踝、右膝、右髖俯仰、右髖橫滾、右髖偏航。
• 左腿 ID 6 至 10：左踝、左膝、左髖俯仰、左髖橫滾、左髖偏航。
• 頭頸 ID 11 至 14：頭部俯仰、頸部俯仰、頭部偏航、頭部橫滾。
• ID 15：選配嘴部，不能假設目前行走程式會驅動它。

IMU 使用 BNO080／BNO085／BNO086 系列模組，依模組標示確認電源，I2C 的 SDA 對應 GPIO2，SCL 對應 GPIO3。安裝方向與固定方式會影響姿態解讀，不能把感測器旋轉後仍沿用未確認的設定。

目前 constants.py還包含右膝與左膝的相反方向零點偏移，這些是特定裝配的校正，不是通用數值。若一啟動就往奇怪方向扭，先停機檢查 ID、零點、方向與 IMU，不要靠提高增益硬撐。

系統安裝：使用預建映像，先跑通第一次開機

1. 從正式 Release 取得映像

先到 image.v1 發布頁，下載 microduck.img.xz。這是教學作者提供的第三方映像，不是 Raspberry Pi 官方原版映像，寫入前應確認來源。

下載完成後計算 SHA256。macOS 使用第一段，Linux 使用第二段。

shasum -a 256 microduck.img.xz

sha256sum microduck.img.xz

本次查核 image.v1 資產的 GitHub SHA256 為下列值。未來若作者重新發布檔案，應以當次 Release 的值為準。校驗一致代表檔案符合發布資產，不等於已完成安全稽核。

096885dc32fb5b1db2ad69ba6bea868d8ab988f2b47c0d884eb63ba0dfdcb5c4

2. 寫入 microSD

安裝 Raspberry Pi Imager，裝置選 Raspberry Pi Zero 2 W，作業系統選自訂映像，再指定剛下載的檔案與 microSD。寫入會清除所選儲存裝置，務必確認不是電腦內部磁碟。

這份自訂映像的教學要求在 OS customization 提示選擇 No，使用它自己的初始化方式。不要把這個做法誤套成所有 Raspberry Pi 映像都應該關閉自訂設定。寫入與驗證完成後，才把卡放進 Pi。

3. 連上 2.4GHz Wi-Fi

Pi Zero 2 W 的無線網路是 2.4GHz。可依 README 在 bootfs 的 network-config修改 Wi-Fi，或接上 mini HDMI 螢幕與鍵盤，在 Pi 終端設定，鍵盤需要合適的 USB OTG 轉接。第一次啟動需要等待分區擴展完成，期間不要隨意拔電。

使用本次映像的預設帳號 user與密碼 password登入後，立刻執行 passwd換掉預設密碼。不要把 SSH 直接開放到公網。下面命令是在 Pi 上執行，依 nmcli 官方說明，--ask會互動詢問 Wi-Fi 密碼，避免將密碼直接寫在命令列。

passwd
nmcli device wifi list
sudo nmcli --ask device wifi connect "你的WiFi名稱"
hostname -I

先查看連線設定名稱，再將實際使用的設定開啟自動連線。下列的名稱是連線設定名稱，不一定和 Wi-Fi 名稱完全相同。

nmcli -f NAME,TYPE,AUTOCONNECT connection show
sudo nmcli connection modify "你的連線設定名稱" connection.autoconnect yes

如果平常用的是 wpa_cli 管理 Linux 無線網路，這裡要留意工具不同。本次映像的教學使用 NetworkManager／nmcli，不要在沒有確認管理方式前，混用另一套設定流程。

4. 從電腦用 SSH 連線

ssh [email protected]

若名稱找不到，到路由器查看 Pi 的 IP，再改用該 IP 連線。若出現主機金鑰變更警告，先確認是不是自己重新刷過同一台 Pi，並核對裝置，不能遇到警告就直接刪除紀錄繼續。

首次執行：先會停止，再讓它走

先將機器人安全支撐，確認關節周圍沒有人手。程式開始時就會啟用扭矩並回到中立姿態，不是等你按前進才會動。也不要同時啟動多個控制程式爭用舵機總線。

以下是在 SSH 登入 Pi 後執行的命令。預建映像已提供部署目錄、虛擬環境與行走模型。

cd ~/microduck
PYTHONPATH=src .venv/bin/python src/main.py

• v：切換行走。
• 方向鍵上／下：前進與後退。
• 方向鍵左／右：轉向。
• x：速度指令歸零，不是硬體急停。
• i：顯示或隱藏 IMU 資訊。
• q：結束控制迴圈。

需要從另一個 SSH 視窗要求停止時，使用以下命令。它是軟體停止機制，不應取代測試區的實體斷電措施。

cd ~/microduck
PYTHONPATH=src .venv/bin/python src/stop.py

一般結束使用，先停止控制並支撐好機器人，再正常關閉 Pi。等待關機完成後，才關閉主電源。若有冒煙、異味或機構卡死等危險狀況，應立即切斷動力，不要為了正常關機而延誤。

sudo shutdown -h now

藍牙手把模式：為什麼一連上就斷 SSH？

預建映像包含無頭手把服務，可以不開電腦終端就啟動控制。第一次配對，可在 Pi 上開啟 bluetoothctl，再執行下列互動命令，把範例 MAC 換成掃描到的手把位址。

bluetoothctl

power on
agent on
scan on
pair XX:XX:XX:XX:XX:XX
trust XX:XX:XX:XX:XX:XX
connect XX:XX:XX:XX:XX:XX
scan off
quit

配對前先讓手把進入配對模式，看到確認要求時核對裝置後再接受。不同手把的按鍵映射可能不同，以下以本次教學的映射為準。

• 按住 START 約 2 秒：啟動控制迴圈。
• A：切換行走。
• 左搖桿：前後與左右速度。
• 右搖桿左右：轉向。
• B：停止控制迴圈。
• 同時按住左右扳機約 2 秒：要求正常關機。

這個版本的背景服務會在手把連線後關閉 Wi-Fi，以改善 2.4GHz 藍牙連線穩定性。因此 SSH 中斷不一定是 Pi 當機，先關閉手把，等 Wi-Fi 恢復後再連線。這是本專案的服務設計，不是所有 Raspberry Pi 藍牙連線都會這樣。

常用維護命令：分清楚在電腦還是 Pi 執行

前面的 Python 命令是在 Pi 上跑。下面的 Makefile 命令則是在開發電腦的 Microduck-build-tutorial/microduck目錄執行，需要可用的 make、rsync 與 SSH 環境，Windows 使用者可採 WSL。明確指定 [email protected]，避免預設 SSH 別名或帳號不符。

cd Microduck-build-tutorial/microduck
make sync [email protected]
make voltage [email protected]
make imu [email protected]

make sync會把本機程式同步到 Pi，因此只應在確認本機版本正確、已備份 Pi 上個人修改後使用。部分檢查目標也會先同步，不是完全不改動遠端檔案的只讀診斷。若只是第一次使用預建映像，先用前面的 SSH 操作即可。

修改依賴後，才執行以下同步與依賴更新命令。

make setup [email protected]

需要啟動控制時，先做好安全支撐，再執行下面這一行。它會先同步程式，接著讓機器人進入控制流程。

make run [email protected]

需要停止時，在另一個終端機執行下面這一行，並注意失去扭矩後機器人可能倒下。

make stop [email protected]

控制停止、機器人已支撐妥當後，才執行正常關機。

make shutdown [email protected]

訓練環境負責產生可部署策略，但重新訓練不是第一次開機的必要步驟。目前匯出腳本產生的檔名為 policy.onnx，部署端則讀取 src/agents/walk.onnx。不能只把任意 ONNX 改名就認為能用，仍須核對觀測、關節順序、動作尺度與模型版本。替換前保存可用的舊模型，再進行受控測試。

遇到問題，先查這四個地方

• 找不到 Pi：確認 2.4GHz Wi-Fi、首次啟動是否完成、路由器是否分配 IP，以及手把服務是否暫時關閉 Wi-Fi。
• 舵機不回應：先檢查供電和極性，再查 OpenRB USB 裝置、韌體、舵機 ID、波特率與插頭。不要帶電拔插舵機線。
• 一啟動就倒或關節扭錯：停止後核對左右腿 ID、膝部零點、關節方向、IMU 固定與安裝方向，別急著換模型。
• 程式無法啟動或總線被占用：先確認背景控制是否已執行，查看服務狀態與日誌，不要用多開程序的方式重試。

在 Pi 上可以用以下命令查看背景服務的狀態與近期日誌。這些命令不會啟動行走。

systemctl status microduck-gamepad.service
journalctl -u microduck-gamepad.service -n 80 --no-pager

常見問題

Microduck 一定要先訓練 AI 才能走嗎？

不需要。本次預建映像包含 walk.onnx 行走策略，第一次復刻先完成裝配、供電、舵機與 IMU 檢查，再使用既有模型。更換硬體或開發新步態時，才進一步評估訓練需求。

這次教學到底需要幾顆舵機？

完整機械配置可裝 15 顆，目前行走程式使用其中 14 顆，雙腿 10 顆、頭頸 4 顆。嘴部 ID 15 為額外關節，採購前先決定是否安裝嘴部，並核對版本。

可以用較便宜的舵機替換 XL330 嗎？

可以研究替代方案，但需要確認結構尺寸、通訊、回授、速度與控制特性。差異可能需要改機構、驅動與模擬參數，甚至重新訓練，不是一定能直接替換。

手把連線後，SSH 斷線正常嗎？

本版本的無頭手把服務會暫時關閉 Wi-Fi，以改善藍牙穩定性。關閉手把後 Wi-Fi 應恢復，可再用 SSH 連線。若沒有恢復，再查看服務日誌。

標示 6V 的電池可以直接接上嗎？

不能只看標稱值。XL330 原廠輸入上限為 6.0V，必須確認充飽與負載變動時的實際電壓，並檢查電流、穩壓與配電能力。不要靠取消電壓保護來處理異常。

我的建議：先把一台做穩，再開始改造

Microduck 讓具身控制不再只是研究論文裡的概念，你可以看到一個姿態讀值如何影響關節命令，也能理解為什麼模擬成功不等於實機一定穩定。但這仍是需要調校的硬體專案，不是刷完映像就保證能走的家電。

先鎖定同一個版本，確認供電與關節，再跑通預建模型。等到站立、停止、行走與關機都能重複完成，再逐步嘗試外觀、動作或訓練上的改變。每次只改一個因素，保留原本能用的程式與模型，除錯會容易得多。

原始資料可從 AI-FanGe 建置教學與上游 Pollen Robotics Microduck繼續閱讀。此整理未經本文作者實機驗證，正式通電前仍須依零件原廠文件檢查。程式庫根目錄與部分子目錄、檔案採不同授權，若要修改散布或商用，應逐項核對，不宜把整個專案一概當成同一授權。