Acorn Precision Farming Rover 組裝指南
用於精準農業的開源太陽能巡行車,具備 4WD/4WS 與 RTK GPS
授權條款
- mechanical designs, motor controller, encoder and CM4 robot board hardware: CERN-OHL-P 2.0 (permissive)
- vehicle software and controller firmware: Apache 2.0
分部分授權。機構設計,以及馬達控制器、編碼器與 CM4 機器人主板的硬體,採用寬鬆的開源硬體授權 CERN-OHL-P。車輛軟體與控制器韌體採用 Apache-2.0。部分內容未載明授權:軟啟動、超級電容、GPS 轉接與磁性感測器板的資料夾、較舊的 rp2040-motor-controller-firmware 儲存庫,以及文件原始檔(robot_docs)。原專案表示其轉向 PDF 的授權不明,另有一支基地台腳本帶有另一位作者的 BSD 3-Clause 標頭。查核日期:2026 年 11 月 2 日。
組裝指南
1. 請先閱讀:原專案公開了什麼
原專案公開了零件清單、設計檔、配線、Raspberry Pi 啟動指令與軟體,但沒有機架、轉角組件或電源系統的製作或組裝方式。本指南如實說明,並不填補這個空缺。
1.1 原專案公開與未公開的內容
原專案文件涵蓋配線、一份簡短的物料清單與軟體,並表示機架製作說明尚未提供。
- 框架:Frame Design 頁面寫道:「本頁將在框架構件的製作說明可用時刊登這些說明。」除了一張照片之外,這句話就是整個頁面的內容。我打開的較早文件原始碼版本(2024 年 5 月 10 日與 5 月 21 日)也沒有框架說明,最新版本(2024 年 6 月 1 日)也沒有。
- 轉角組件:Corner Assembly 頁面只寫道:「轉角組件包含了系統大部分的機器人複雜度。」它有一張照片,沒有任何步驟。
- 機械:Mechanical 頁面寫道:「截至 2024 年中,機械設計仍在大幅變動中,機械設計的資料夾結構也尚未整理。到 2024 年底,我們的機械設計應會穩定下來,並將建立設計發行版。」我沒有找到這樣的設計發行版。機械設計儲存庫中只有一份指向 Onshape 文件的說明檔,最後一次變更日期是 2021 年 2 月 3 日。
- 因此本指南不包含任何焊接、治具、軸承安裝或齒輪嚙合的步驟。原專案沒有說明如何製作框架或轉角叉架,本指南也就不說明。請依 Onshape CAD 製作,並到原專案文件指名的社群討論頁面提問。
- 原專案實際以步驟形式公開的內容很少:一份 Raspberry Pi 啟用文字檔、一份模擬說明檔、M12 線纜腳位、輪轂馬達的線色,以及用於韌體燒錄與軟體啟動的腳本與原始碼。下方的步驟就是這些,也只有這些。
- 原專案文件首頁載有以下註記:「本專案正在積極開發中。」
1.2 電壓與電源:原專案沒有提供電源操作程序
這台探測車以太陽能板與超級電容組供電,標稱電壓 45 伏特,原專案沒有公開開機或關機程序。
- 原專案的 Overview 頁面寫道:「電力系統由標稱 45 伏特運作的太陽能板系統、用於暫時儲存電力的超級電容陣列,以及保護超級電容的簡單電力電子電路組成。沒有電池,Acorn 直接以太陽能運作。」
- 我讀過的文件都沒有給出連接太陽能板、超級電容組、軟啟動板與轉角組件的順序。也沒有任何文件給出預充電或放電方法、保險絲額定值,或安全處理電容組的方式。本指南也沒有給出,其章節順序不應被解讀為通電順序。
- 不要僅憑本指南就通電。在連接任何電源之前,請先閱讀超級電容板、軟啟動板以及原專案記錄的電路板缺陷這幾個章節。
2. 工具、零件與設計檔
原專案列出的工具與零件,以及其設計檔的位置。原專案的物料清單很簡短,沒有提供扣件、管材或板材的尺寸。
2.1 原專案列出的工具
原專案列出的主要工具有 3D 印表機、焊機、電漿切割機、鑽床、桌上型砂輪機與焊接工作台。
- 主要工具,附原專案給出的價格:3D 印表機 $1000;焊機 $500;電漿切割機 $8000;鑽床 $200;桌上型砂輪機 $200;焊接工作台 $200。
- 其他實用工具:金屬銼刀、鑽頭、圓形砂紙機、螺絲起子、扳手。
- 原專案表示:電漿切割件可以很好地平整包裝,因此若想向外部工廠採購這些零件,可以省掉最昂貴的工具 CNC 電漿切割機。
- 原專案表示,只要稍加練習並仔細研讀網路上免費的焊接教學影片,任何人都能學會鋁的 MIG 焊接。它沒有給出焊接程序。
2.2 原專案公開的物料清單
Bill of Materials 頁面列出兩種組裝配置與一份簡短的零件清單;沒有列出扣件、軸承尺寸、管材尺寸或板厚。
- 組態:機器人可以用 DIY 框架加四個轉角組件製作,或做成帶鋁框架的完整機器人。
- 完整機器人:Solar Panels x 4;Chassis Wiring - data;Chassis Wiring - power;Corner Assemblies x4;Super Capacitors;Motherboard Assembly;GPS Modules x 2;GPS Antennas x 2;Frame Side x 2;Frame Front x 2;Frame solar panel mounts。
- 轉角組件:Motor controller PCB assembly with UI PCB,$100;Induction encoder PCB,$20;Aluminum fork upper weldment;Aluminum fork lower weldment;Thrust bearings;3D printed steel steering drive gear;Drive motor phase and hall cable;Steering motor phase cable;Induction encoder interface cable。
- 驅動馬達:BOM 連結的供應商頁面上那款帶減速齒輪的獨輪手推車馬達,$275.00。原專案的說明:「這款馬達大致上相當不錯,但防水性可能不夠。」原專案補充說,它聯繫過的供應商都不願意製作同樣高減速比的馬達,Bafang 要求 500 件起訂,而透過 Alibaba 的嘗試至今都沒有成功。
- 輪胎:Carlisle X Trac ATV Bias Tire - 4.80-8,$40。
- 轉向馬達:AM Equipment AMP240-0502,$300。原專案的說明:「我們不再需要內建編碼器,因此應找一款更便宜的防水密封馬達,或測試非密封馬達加外殼的做法。」原專案建議,網路市集上約 $45、60 RPM 等級的馬達可能可行,並警告這些出貨商似乎又慢又不可靠,還說:「這些馬達可能動力不足,需要測試。」
- GPS 模組與天線只列出供應商連結,沒有價格。
2.3 機構設計檔案的位置
機構設計是 Onshape 中的 CAD 文件,需要免費的 Onshape 帳號。
- 機械設計儲存庫的說明檔寫道:「Acorn 的機械設計存放在 onshape 中。」它也說明這些設計以 CERN-OHL-P 授權,並指向 Onshape 的免費註冊頁面以申請免費帳號。
- Mechanical 頁面表示 CAD 資料夾結構尚未整理,並邀請讀者目前先瀏覽這些檔案作為參考。
- 儲存庫中沒有 CAD 匯出檔。尺寸、管材與板材規格、扣件以及任何焊接細節都只在 Onshape 文件中,而我無法開啟該文件。
3. 機架與轉角組件(原專案無說明)
原專案沒有公開這些零件的製作或組裝說明。本章節只記錄它所陳述的內容,並指向 CAD。這不是組裝方式。
3.1 機架:原專案的說明
兩個側邊焊件與兩個前後焊件以螺栓鎖合;物料清單另外列出機架用的太陽能板支架。
- 原專案的 Frame Design 頁面表示,框架由兩個側面焊件與兩個前/後焊件以螺栓連接組成,並附有一張框架照片。
- Mechanical 頁面表示,框架是 MIG 焊接的鋁框架,由鋁管與 CNC 電漿切割的鋁板製成。
- 焊接順序、治具、點焊做法、管材尺寸、板厚與扣件,在我讀過的任何文件中都沒有說明。請從 Onshape CAD 取得,而原專案表示該 CAD 仍在變動中。
- 框架的製作說明:尚未提供。原專案的原話是:「在這些說明可用時」。
3.2 轉角組件:原專案的說明
四個相同的轉角組件各在一個鋁製焊件中裝有一顆驅動馬達與一顆轉向馬達,以及配套的電子元件,並以螺栓鎖到機架上。
- 原專案的 Overview 頁面寫道:「Acorn 大部分的機器人複雜度都集中在四個相同的模組化轉角組件中,它們負責驅動與轉向。這些組件以螺栓固定到框架上,並接上底盤線路,即完成機器人。」
- System Design 段落表示,每個轉角組件在一個鋁焊件中包含一顆驅動馬達與一顆轉向馬達,內部另有輔助電子元件。
- 一個轉角的零件列於上方的物料清單中。原專案沒有提供接合叉架焊件、安裝止推軸承、安裝 3D 列印鋼製轉向驅動齒輪或使其與轉向馬達嚙合的說明。它沒有給出扭力值,也沒有螺絲膠的說明。不要自行假設任何數值。以 CAD 所示為準。
4. 電路板
原專案自己的建議是先不要訂購它的電路板。本章節列出這項建議、各設計檔的位置,以及原專案在筆記中記錄的故障。
4.1 訂購任何電路板之前
原專案表示其電路板設計尚未成熟,建議不要訂購。
- Electrical 頁面寫道:「任何人都可以使用我們 github 上的檔案透過 JLCPCB 訂購我們的 PCB,但在我們的 PCB 設計成熟之前,不建議這麼做。未來我們會發布正式的 PCB 版本,讓使用者更容易訂購。」
- 馬達控制器說明檔載有以下警告:「這些檔案仍在開發與測試中。雖然我們希望做出他人能輕鬆製作的設計,但目前還不建議你自己製作!」原專案請讀者到其社群論壇詢問電路板的狀態。
- 馬達控制器韌體說明檔寫道:「我們的系統是實驗性的,仍在測試中。初步測試結果良好,但目前我們無法保證運作安全或可靠。」
- 根據 commit 訊息,儲存庫中的電路板檔案最後一次更新是為了 2024 年 7 月下的訂單。
4.2 各電路板的設計檔案位置
每塊電路板的 KiCad 檔案都放在 Twisted Fields 的某個儲存庫中;原專案列出了資料夾名稱,但沒有提供任何電路板的組裝步驟。
- 主機板(搭載 Raspberry Pi Compute Module 4):acorn-robot-electronics 儲存庫的 cm4_robot_board 資料夾。該資料夾的說明檔仍描述一個透過 RS-485 與四個 Odrive 馬達控制器通訊的舊設計;較新的 Electrical 頁面則說主機板透過 CAN bus 與四個馬達控制器通訊。
- 馬達控制器(三片電路板:Motor Driver Module、CPU Base、User Interface):rp2040-motor-controller 儲存庫的 driver_module、RP2040_base 與 user_interface 資料夾,附有量產用物料清單。
- 感應式編碼器:induction_encoder 儲存庫。Electrical 頁面表示,該 PCB 部分是由該儲存庫中的一個 python 腳本產生的。
- 磁性角度編碼器:rp2040-motor-controller 儲存庫的 rp2040_encoder 資料夾。原專案表示目前機器人上並未使用它。
- RP2040 除錯器 PCB:rp2040-motor-controller 儲存庫的 debugger 資料夾。
- 磁感測器:acorn-robot-electronics 儲存庫的 mag_sensor 資料夾。原專案表示,有一片單一類比磁場強度感測器 PCB,可在製作工具或其他機械時用於客製的終點感測,並可與馬達控制器的 CPU Base PCB 對接。
- GPS 轉接板、超級電容板與軟啟動板:acorn-robot-electronics 儲存庫的 gps_adapter、supercap 與 soft_start 資料夾。Electrical 頁面只描述了超級電容板,並說它仍在開發中。頁面沒有提到軟啟動板或 GPS 轉接板。
- 攝影機系統 PCB:尚未製作。原專案表示:「未來我們將為 Acorn 製作攝影機系統。」
4.3 原專案記錄的主機板問題
原專案的主機板筆記列出開機不穩定、極性標示不清楚與晶振數值錯誤;沒有說明 2024 年 7 月的電路板是否已修正這些問題。
- board_TODO.txt(最後變更於 2022 年 1 月)對主機板列出:「在設計中加入某種在電源穩定前讓 CM4 保持重置的機制?為什麼開機時不一定每次都能啟動?」它也問道:「有沒有開關裝反了?」並寫道:「USB 二極體不起作用,我猜需要理想二極體來處理更大的功率?」
- notes.txt(最後變更於 2023 年 1 月),標題為 TODO RECOMMENDATIONS AFTER PRODUCTION,要求標清楚 U5、D19、D5、D6、D20、D7、D21 與 D18 的極性,並說要把 CAN 控制器的晶振值標得更清楚:「16mhz 不是 12mhz!」
- 同一個檔案寫道:「線纜斷開時應觸發緊急停止。——算了,它已經會這樣做。」
- 這些是原專案自己的筆記。它們沒有說明哪些缺陷仍存在於 2024 年 7 月的電路板檔案中。
4.4 原專案記錄的馬達控制器問題
原專案在 2023 年生產批次後的筆記列出接頭方向相反、額定 53 伏特的電路板上使用 50 V 陶瓷電容,以及一顆燒毀的飛輪二極體。
- 馬達控制器儲存庫中的 TODO.txt(最後變更於 2023 年 3 月),標題為 2023 AFTER PRODUCTION NOTES,寫道:「修正接頭方向,看看能否在檔案中修正輸出方向。」它補充說,接頭的絲印矩形沒有適當置中,外框只有在反向插件時才對得上,這或許能解釋為什麼接頭會被反向插件。
- 同一個檔案寫道:「馬達電容:有些陶瓷電容只有 50V!」Electrical 頁面將驅動模組的額定值標為標稱 53 伏特。
- 它也寫道:「馬達飛輪二極體:我燒掉了一顆二極體!需要更高的功率能力。」以及:「當我讓馬達高負荷運轉後再停下時,聽到電路板上發出一聲電子爆裂聲(一次)。這是二極體燒掉了嗎?煞車需要什麼?」
- 儲存庫在 2024 年 7 月為新的電路板訂單更新過。沒有任何說明指出這些缺陷是否已在那些檔案中修正。
5. 轉角電子元件
馬達控制器、其韌體、CAN 位址、輪轂馬達電線顏色與轉向角度感測器,以原專案記錄的範圍為限。
5.1 馬達控制器電路板
馬達控制器由一塊 Motor Driver Module、一塊裝有兩個驅動模組與兩顆 RP2040 CPU 的 CPU Base,以及一塊 User Interface 板組成。
- 原專案的描述:「由三片 PCB 組成:Motor Driver Module、CPU Base 與 User Interface。驅動模組上有 MOSFET 與相關的功率驅動電路,用來驅動馬達。標稱額定 53 伏特、持續 20A(視散熱而定)、峰值 50A。」
- CPU Base 承載兩個馬達驅動模組,並包含兩顆 RP2040 CPU。一顆 CPU 處理所有馬達驅動功能,另一顆處理 CAN bus 通訊與其他輔助功能。
- User Interface PCB 裝在 CPU Base PCB 上,具有數個按鈕、開關與 LED,並預留了 OLED 顯示器的空間。原專案表示它用於控制轉角組件。
- Electrical 頁面表示主機板與四個馬達控制器通訊,Overview 則說每個轉角組件有一顆驅動馬達與一顆轉向馬達。CPU Base 承載兩個驅動模組,因此一個控制器可以驅動一個轉角的兩顆馬達。原專案沒有說明哪個驅動模組驅動哪顆馬達。
5.2 馬達控制器韌體:保護電路板的建置旗標
韌體以 PlatformIO 與 SimpleFOC 建置,SIMPLEFOC_PWM_LOWSIDE_ACTIVE_HIGH 必須設為 false,否則可能損壞元件。
- 目前的韌體位於 rp2040-motor-firmware 儲存庫。較舊的儲存庫 rp2040-motor-controller-firmware(最後變更於 2022 年 9 月)在其自己的說明檔中標示:「開發中,測試中。請勿使用。」請使用較新的那一個。
- 較舊儲存庫說明檔中的警告,同樣適用於這片電路板:「Twisted fields 控制器的低側開關使用低電位有效極性。請務必在建置時設定 -DSIMPLEFOC_PWM_LOWSIDE_ACTIVE_HIGH=false,否則電路板將無法正常運作,且可能有東西損壞。」
- 在目前的儲存庫中,platformio.ini 為 motorcontroller、auxiliary-unit 與 encoder_verification 環境設定了 -DSIMPLEFOC_PWM_LOWSIDE_ACTIVE_HIGH=false。canbus 環境沒有使用這個旗標。
- 目前的說明檔表示專案設定為使用 PlatformIO,並寫道:「目前版本依賴 SimpleFOC 函式庫尚未發布的變更。若要在 SimpleFOC 2.2.3 發布前編譯本專案,請將 SimpleFOC dev 分支 git clone 到本專案的 lib/ 目錄中。」儲存庫將 SimpleFOC 函式庫列為 lib/ 下的子模組。
- 原專案燒錄腳本所需的韌體由兩個環境建置:canbus 與 motorcontroller。腳本會尋找 .pio/build/canbus/firmware.bin 與 .pio/build/motorcontroller/firmware.bin。
- 第一次載入韌體的方法沒有書面說明。platformio.ini 設定了 debug_tool=cmsis-dap 與 upload_protocol=cmsis-dap,Electrical 頁面也描述了一片 RP2040 除錯器 PCB,但沒有任何文件給出首次燒錄的步驟。之後,Electrical 頁面寫道:「兩片 PCB 都可以使用我們的韌體燒錄腳本透過 CAN bus 重新燒錄。」
5.3 各轉角控制器的 CAN 位址
車輛軟體預期控制器位於 CAN 位址 0x6、0x7、0x8 與 0x9,韌體則從電路板上的三個輸入讀取自己的位址。
- 在 vehicle/motors_can.py 中,四個轉角以下列 CAN 位址定義,全都在名為 can1 的 Raspberry Pi 介面上:左前 0x6、右前 0x7、左後 0x8、右後 0x9。
- 在控制器的 CAN 韌體(main-canbus.cpp)中,位址是基底 0x5 加上從 I/O 擴展器輸入 0、1 與 2 讀取的三位元值,其中低電位輸入計為 1。
- 原專案的馬達控制器筆記說,曾考慮用 DIP 開關設定位址,但為了節省空間將改用 SMT 跳線。沒有任何文件說明哪個跳線設定哪個位址。我沒有追查電路圖。在你追查清楚之前,無法依本指南設定位址。
5.4 從車輛透過 CAN 重新燒錄控制器
原專案的 flash_firmware_from_host.py 會將兩個韌體二進位檔複製到 Raspberry Pi,並針對每個轉角位址各執行一次 can_firmware.py。
- 以下是這兩個腳本執行的動作。原專案沒有相關的書面說明,腳本的預設值是某位開發者的路徑。
- flash_firmware_from_host.py 在檔案開頭寫死了韌體資料夾、機器人主機名稱與 CAN 位址清單(FIRMWARE_FOLDER、ROBOT_HOSTNAME、CAN_ADDRESSES)。預設值是某位開發者的家目錄、主機名稱 acorn4.local,以及位址 0x6、0x7、0x8 與 0x9。請先編輯它們。
- 腳本以 rsync 將兩個建置好的二進位檔複製到機器人上的 vehicle 資料夾,檔名為 firmware_can.bin 與 firmware_motor.bin,使用帳號 acorn。
- 接著,它對每個位址透過 ssh 在機器人上執行 python3 can_firmware.py,帶三個參數:位址、是否燒錄 CAN CPU(0 或 1),以及是否燒錄馬達 CPU(0 或 1)。
- can_firmware.py 透過 can1 介面使用 ISO-TP,先傳送馬達 CPU 映像檔,等待兩秒後再傳送 CAN CPU 映像檔。
5.5 驅動馬達線材顏色
原專案的 hubmotor_wiring.txt 列出輪轂馬達上六條有標示的線:H1 黃色、H2 藍色、H3 綠色,以及正極紅色、負極黑色與 ST 白色。
- 檔案內容為:H1 Yellow;H2 Blue;H3 Green;+ Red;- Black;ST White。
- 檔案沒有說明這些標籤的含義。物料清單將這條線稱為驅動馬達相線與霍爾線,Electrical 頁面也沒有描述馬達接線。
- 不要因為假設紅線與黑線是電源線,就將它們接到電源供應器或 45 伏特匯流排。原專案並沒有說它們是電源線。連接任何東西之前,請對照輪轂馬達供應商自己的接線文件確認每個標籤。
5.6 轉向角度感測器
一塊大型環狀感應式編碼器 PCB,搭載 IPS2200 晶片與八個磁場感測器,讀取轉向角度,並透過 I2C 與馬達控制器通訊。
- 原專案的描述:一片大型環狀 PCB,具有特殊的線圈圖樣與一顆 IPS2200 感應式編碼器晶片,另有 8 個等距分布的類比磁場感測器。三顆 ADS1115 I2C ADC 讀取這些感測器。PCB 透過馬達控制器的編碼器埠以 I2C 與馬達控制器通訊。
- 感應部分使用兩相,磁感測器會偵測轉向齒輪中的一顆磁鐵,藉此區分兩相。
- 車輛程式碼在 corner_actuator_can.py 中設定 INDUCTION_STEERING_SENSOR = True,並在 motor_controller.py 中定義了 SET_STEERING_HOME 訊息。沒有任何文件說明如何擺放磁鐵或設定轉向原點位置。
5.7 corner_debug.py 測試台腳本的作用
corner_debug.py 會在 1.57 將左後轉向馬達歸零,再將它驅動到命令列指定的位置,因此一執行就會讓硬體動作。
- 這是從腳本中讀出的內容。原專案沒有書面說明。
- 該腳本只針對一個轉角撰寫:左後,CAN 位址 0x8,在 can1 上。它會設定緊急停止輸出腳位、清除錯誤碼、呼叫 set_home_position(1.57),然後無限迴圈傳送你以第一個參數給定的位置並印出錯誤。
- 它會先將 bus 6 上 I2C 擴展器的輸出 0 拉高一秒,再拉低一秒;原專案沒有說明該輸出控制什麼。
- 若參數大於 8 或小於 -8,它會立即結束。腳本沒有說明位置的單位或 1.57 的方向,原專案也都沒有記載。由於它在移動前會先歸位,因此一執行就會讓硬體動起來。
6. 底盤配線與緊急停止
M12 資料纜線、電源纜線與緊急停止,依原專案的記錄。
6.1 M12 資料纜線
每個轉角以一條 8-pin A-code M12 纜線接到主機板,傳送兩組 CAN 電路、緊急停止訊號與一路隔離的 5 伏特電源。
- 原專案描述了一套客製的資料線系統,具有兩個 CAN bus 迴路與一套特殊的緊急停止系統,另有第二組線纜用來輸送電力。一個 CAN bus 迴路專用於馬達控制器,另一個迴路則可作一般用途。頁面沒有說明哪個迴路是哪個。
- 資料線系統使用工業乙太網路常用的 8 pin M12 接頭與線纜。「我們使用 A-code 對接方式,而不是 X-code。」
- PCB 安裝接頭:M12A-08PFFR-SF7003。線纜:類似 M12A08ML-12AML-SD002 或 M12A08ML-12AFL-SB002 的型號。
- 原專案給出的腳位表:1 ESTOP SWITCH CIRCUIT;2 CAN 1 HIGH;3 CAN 1 LOW;4 ISOLATED GROUND;5 CAN 0 HIGH;6 ESTOP SQUARE WAVE;7 ISOLATED FIVE VOLT;8 CAN 0 LOW。
- 原專案沒有給出線纜長度、接線順序、終端處理說明,除了接線圖中顯示的四個轉角之外也沒有線纜數量。車輛軟體在 Raspberry Pi 介面 can1 上與四個轉角控制器通訊;原專案沒有說明那是底盤上的哪一個 CAN 迴路。
6.2 電源纜線
電源纜線為 12 gauge 矽膠外被線,末端壓接 Anderson PP45 接頭。
- 原專案表示:「電源線一般為 12 號矽膠外被線,末端壓接 Anderson PP45 接頭。」它連結了自己使用的特定線材:額定攝氏 200 度、600V 的 12 號矽膠線捲。
- 原專案沒有給出電源線的線纜長度、壓接說明、佈線或保險絲說明,也沒有接線圖,只有一張方塊圖,其標籤為 Solar Panels、Solar Power、Chassis Power、Super Capacitors、Motherboard 與四個 Corner Assemblies。
- 軟啟動板與超級電容板的設計檔中也使用 PowerPole PP45 接頭。
6.3 緊急停止:原專案的說明
緊急停止由一個開關電路,加上主機板經由每條 M12 纜線第 6 腳送出的方波組成;只有在方波持續變化時,轉角控制器才允許動作。
- 原專案的 M12 腳位表中,pin 1 是 ESTOP SWITCH CIRCUIT,pin 6 是 ESTOP SQUARE WAVE。
- 在車輛程式碼中,motors_can.py 以方波驅動 Raspberry Pi BCM 編號的 pin 6(ESTOP_PIN)。程式註解稱其為 approx 100Hz。
- 在 CAN CPU 韌體中,只有當方波輸入在最近 200 ms 內有變化時才允許動作(ESTOP_DURATION_MS 200)。原始碼將 DISABLE_ESTOP 定義為 false。請保持 false。
- 韌體也會讀取另一個開關狀態輸入,並以狀態 LED 顯示:該輸入為高電位時為綠色,低電位時為紅色。
- 原專案的筆記寫道:「線纜斷開時應觸發緊急停止。——算了,它已經會這樣做。」
- 沒有任何文件說緊急停止會切斷馬達電源。我讀到的內容描述的是一個由轉角控制器監看的訊號。不要假設緊急停止會斷開接觸器。
6.4 CAN 位元率:文件說法不一
Raspberry Pi 端設定為 500K,控制器韌體則以 100KBPS 初始化其 CAN 晶片;原專案沒有調和兩者。
- bringup/raspberry/80-can.network 為所有名為 can* 的介面設定 BitRate=500K。啟用腳本會將它安裝到 Compute Module 上。
- 控制器韌體中的 main-canbus.cpp 呼叫 CAN0.begin(MCP_STDEXT, CAN_100KBPS, MCP_16MHZ)。
- 我無法判斷這兩者指的是否是同一條匯流排,或其中一個已經過時。不要假設其中任何一個是正確的就進行接線或燒錄。請到原專案的社群論壇詢問,或對照電路圖閱讀這兩份原始碼。
7. 主機板與 Raspberry Pi Compute Module 啟動
原專案的啟動文字檔是它公開的唯一一份完整書面程序。以下步驟依照該文件及其呼叫的腳本。
7.1 主機板:上面裝了什麼
主機板裝有 Raspberry Pi Compute Module 4,並透過 CAN 匯流排與四個馬達控制器通訊。
- 原專案的描述:「承載主電腦 Raspberry Pi Compute Module 4,並透過 CAN bus 與四個馬達控制器通訊。也負責管理 GPS、wifi、緊急停止系統以及其他數項功能。」
- 主機板的物料清單檔(cm4-robot.csv,最後變更於 2023 年 11 月)列出的項目包括:兩顆 MCP2515 CAN 控制器、兩顆 SC16IS752 UART 橋接晶片、一顆 LM2576HVS-5 穩壓器、一顆 TPS61040、一顆 ISL54222AIUZ、一顆 LTC4412xS6、七顆 WS2812B LED、一個搭配 ET6226M 驅動器的 CC56-12SEKWA 顯示器,以及兩個 120R 電阻(R34、R35)。電路板檔案的日期是 2024 年 7 月,因此該清單可能與其不符。
- 原專案沒有說明要使用哪一種 Compute Module 4 規格(RAM、儲存空間、無線)。下方的啟用步驟使用 rpiboot 將模組掛載為磁碟。
7.2 燒錄 Compute Module
以開機模式接上 Compute Module,燒錄 Raspberry Pi OS Lite 64-bit,再以你想要的主機名稱執行 bringup-cm4.sh。
- 原專案的引言:「燒錄 compute module 並為 Acorn 進行設定,需要依序完成數個步驟。此外,Raspberry Pi OS 的每次更新都可能破壞啟用流程。」
- 首先,以開機模式插入模組,並用 sudo 執行 rpiboot 指令以連接到檔案系統。(文字檔將指令拼成 raspiboot;腳本呼叫的是 sudo rpiboot。)
- 執行磁碟映像工具來燒錄磁碟映像檔。原專案給出的最新測試版本為 Raspberry Pi OS Lite,發布日期 2023 年 10 月 10 日,64 位元,核心版本 6.1,Debian 版本 12(bookworm),大小 435MB。
- 燒錄完成後,拔下裝置再重新插上。
- 接著以一般的非 root 使用者執行 bringup-cm4 腳本。你可能會被要求輸入 root 密碼。你必須將想要的主機名稱傳給腳本。若要讓 Pi 的主機名稱為 acorn123,請執行:bash bringup-cm4.sh acorn123
- 記下腳本印出的 rsync 指令;稍後會用到。
- 從腳本中讀出它的動作:它預期模組的 boot 與 root 分割區掛載在 /media/<your user>/bootfs 與 rootfs 下,若沒有就執行 sudo rpiboot,若仍未掛載則以錯誤結束。它會啟用 ssh,複製 dt-blob.bin、config.txt 與 dual-sc16is752-spi1 overlay,複製 GPS udev 規則、CAN 網路檔、兩個 Wi-Fi 連線設定檔與 CAN ISO-TP 模組設定,建立使用者 acorn 並存入密碼雜湊值,設定主機名稱,建立 /home/acorn/acorn 資料夾,然後卸載兩個分割區。
- bringup/raspberry 中的 Wi-Fi 連線設定檔帶有網路名稱 twistedfields 與一組儲存的金鑰。原專案沒有說明如何將它們換成你自己的網路。
7.3 首次開機並複製軟體
將開機開關切到一般開機,接上乙太網路,以 acorn 身分 ssh 登入,擴展檔案系統,並以 rsync 複製軟體資料夾。
- 腳本完成後會卸載模組。拔下模組,將開機開關切到一般開機,再插回去通電。
- 接上乙太網路線,大約一分鐘後以 ssh 登入裝置。密碼是 acorn。
- 你也可以選擇複製你的 ssh id,這樣就不必輸入密碼:執行 ssh-copy-id acorn@<hostname>,若被詢問就回答 yes,然後輸入密碼。之後就可以正常以 ssh 登入。
- 目前的 Raspberry Pi 映像檔似乎不會自動擴展檔案系統,因此請執行 sudo raspi-config,選擇 advanced options,再選擇 expand filesystem。離開選單並將 Compute Module 重新開機。
- 此時用啟用腳本印出的 rsync 指令將 acorn 軟體資料夾 rsync 過去。腳本的結尾訊息給出的指令是:rsync -aP ../. acorn@<hostname>.local:/home/acorn/acorn/
7.4 執行燒錄後腳本並建置車輛容器
在 /home/acorn/acorn/bringup 中執行 bringup-post-flash-raspberrypi.sh,然後建置 docker-compose-vehicle.yml,需時 10 到 60 分鐘。
- 再以 ssh 登入 Compute Module,進入 /home/acorn/acorn/bringup,執行 bringup-post-flash-raspberrypi.sh 腳本。
- 從腳本中讀出:它會複製 .bashrc 與 .profile,將時區設為 US/Pacific,停用兩個 wait-online 服務,啟用 systemd-networkd,執行 apt-get update 與 upgrade,安裝 can-utils,用 Docker 提供的便利腳本安裝 Docker,將 acorn 使用者加入 docker 群組,安裝 vim、libffi-dev、libssl-dev、python3-dev、python3-pip、python3-venv、docker-compose、python3-crccheck、ntpdate 與 i2c-tools,並用 pip 安裝 can-isotp。
- 時區設定為加州。原專案沒有提到要變更它。
- 最後,進入 /home/acorn/acorn 並執行:docker-compose -f docker-compose-vehicle.yml build。視你的網路連線速度而定,這需要 10 到 60 分鐘。
7.5 啟動車輛容器
在 /home/acorn/acorn 中執行 ./run_docker_vehicle.sh;它會為主程序、馬達、LED 與 RTK 修正資料中繼啟動 tmux 工作階段。
- 原專案:「若一切順利,你現在應該可以執行 ./run_docker_vehicle.sh 並啟動 docker 容器。設定到此完成!」
- 從腳本中讀出:run_docker_vehicle.sh 會停止並移除任何名為 acorn_vehicle 的容器,然後在背景啟動 docker-compose-vehicle.yml。compose 檔以特權模式執行容器,使用主機網路並掛載主機的 /dev,且除非手動停止,否則會自動重新啟動。
- 容器會執行 autolaunch_vehicle.sh。暫停 5 秒後,它會啟動四個 tmux 工作階段:main(vehicle/main_process.py)、motors(vehicle/motors_can.py,結束時會在迴圈中重新啟動)、leds(vehicle/led_control.py)與 rtcm(bringup/serial/rtcm_bash.sh,同樣在迴圈中重新啟動)。60 秒後,它會用 ntpdate 從網路時間伺服器校正時鐘。
- 除非手動停止,compose 檔會讓容器自動重新啟動,motors 程序也會隨之啟動,一旦量測到的電壓高於 15,就會連接轉角控制器。原專案沒有提供停用這個自動啟動的步驟。
8. GPS 與 RTK
主機板上的兩個 u-blox ZED-F9P 接收器提供位置與航向;RTK 校正來源與基地站沒有以程序形式記錄。
8.1 接收器與序列埠
車輛程式以 921600 baud 從 /dev/ttySC0 與 /dev/ttySC1 讀取兩個接收器。
- 物料清單列出 GPS Modules x 2 與 GPS Antennas x 2,各附一個供應商連結。
- 在 vehicle/gps.py 中,第一個接收器在 /dev/ttySC0 上開啟,註解為 Center Receiver;第二個在 /dev/ttySC1 上開啟,註解為 Rear Receiver,兩者都是 921600 鮑率。config.txt 會載入 dual-sc16is752-spi1 overlay。
- 啟動時,程式碼會對每個接收器傳送 CFG_RATE_MEAS = 40 與 CFG_RATE_NAV = 2,只在執行期間設定,不會存入 flash。
- 在 vehicle/rtk_process.py 中,航向偏移為 VEHICLE_AZIMUTH_OFFSET_DEG = 90 + 45.0。
- 原專案沒有文件說明天線要裝在哪裡、間隔多遠,或如何將接收器連接到主機板或 GPS 轉接板。
8.2 以 u-center 設定新的接收器
原專案的 GPS 筆記表示,新的接收器必須以 u-center 設定,u-center 可透過 Wine 在 Linux 上執行。
- GPS 筆記(日期為 2020 年 2 月 15 日)寫道:「新的 GPS 接收器務必用 u-center 進行設定。」它連結了 RTKLIB Explorer 網站上的一份設定指南。
- 它補充說,u-center 可以在 linux 上透過 wine 執行,wine 會在 ~/.wine/dosdevices/ 中建立指向現有序列埠的符號連結。
- 這份筆記來自 2020 年,並說 Acorn 使用 RTKLIB。目前的車輛程式碼直接從接收器讀取 u-blox 訊息,因此這份筆記可能早於目前的設置。它沒有列出要套用的設定。
8.3 RTK 修正資料與基地站
修正資料經由 bringup/serial/rtcm_relay.py 從網路 socket 傳到接收器;原專案沒有記錄基地站的設定程序。
- rtcm_relay.py 連接到一個位址寫死在檔案中的 TCP 伺服器(HOST 192.168.1.50、PORT 130),讀取 RTCM 訊息,並將其寫入 /dev/ttySC2 與 /dev/ttySC3。它由 rtcm tmux 工作階段啟動。你必須編輯該位址;原專案沒有說明該位址上應執行什麼。
- 基準站腳本是存在的:gps_base_station/f9p_basestation.py(來自另一位作者,採 BSD 3-Clause 授權,撰寫目的是搭配 NTRIP caster 使用)與 gps_base_station/survey_in.py。survey_in.py 在檔案中寫死了連接埠(/dev/ublox9)、9600 鮑率與模式設定(MODE_SETTING),因此必須編輯檔案才能在 survey-in 與固定位置之間切換。
- 沒有任何文件說明基準站的設置地點、要測量多久,或如何將其修正資料傳送給移動站。
8.4 軟體認定的良好定位
當水平精度低於 550 mm、定位類型為 3 或以上,且差分解旗標為 1 時,定位才算良好。
- 在 vehicle/gps.py 中,生效的值是 MAX_ALLOWED_HACC_MM = 550。# MAX_ALLOWED_HACC_MM = 50 這一行已被註解掉,沒有作用。
- 對每個接收器套用的檢查為:hAcc 低於 MAX_ALLOWED_HACC_MM、fixType 為 3 或以上,且 difSoln 等於 1。
- 程式碼保留 120 秒的 GPS 樣本(TOTAL_HISTORY_SAMPLE_DURATION_S = 120)用於品質檢查。
- 當 RTK 資料時效超過 20.0 秒,或解算結果時效超過 1.0 秒時,自主功能會將其指令歸零(remote_control_process.py 中的 _ALLOWED_RTK_AGE_SEC、_ALLOWED_SOLUTION_AGE_SEC)。
- 原專案沒有給出成品應達到的精度目標。
9. 電源系統:標稱 45 V、超級電容、無電池
原專案對電源板的說明,包括其保護板尚未完成。由於原專案沒有提供通電順序,這裡也不提供。
9.1 超級電容平衡與保險絲板:警告,開發中
原專案表示,負責平衡超級電容並在短路時切斷電源的電路板仍在開發中,因此不要依賴它。
- 警告。Electrical 頁面寫道:「這片 PCB 仍在開發中,但它將會平衡超級電容,並在系統電源導線短路時提供某種安全保險絲或基於電流的斷電功能。該電路板的一個版本在這裡」(它連結到 supercap 資料夾)。
- 「將會平衡」與「某種安全保險絲」這些字眼描述的是這片電路板預期要做的事,而不是它實際做到的事。不要將這片電路板的任何版本視為 45 伏特超級電容組的有效保護。
- 原專案沒有公開替代設計:沒有保險絲額定值、沒有保險絲位置,也沒有超級電容組接線圖。因此本指南無法提供。
- 儲存庫中有兩個版本:supercap 與 supercap_simple(於 2024 年 7 月的更新中加入)。它們的量產物料清單列出 20 顆 120F 2.3v、徑向 18 mm 封裝的電容,以及 20 顆 2.4v 齊納二極體。原專案沒有說明這 20 顆如何接線,因此不要自行推斷電容組的配置。
- 僅供參考:儲存庫的 supercap 韌體(馬達韌體儲存庫中的 main-supercap.cpp)在啟動後的第一秒之後,若量測到的輸出電流超過 15.0 就會關閉輸出,並以電路板上的三個開關切換輸出。原專案沒有描述這個韌體,也沒有說明它在哪片電路板上執行。
9.2 軟啟動板:沒有原專案文件,且有已列出的問題
電子元件儲存庫中有一個 soft_start 資料夾,但沒有任何文件說明它,而它自己的 issues 檔案指出輸入端 MOSFET 的配置不正確。
- Electrical 頁面與 Bill of Materials 頁面都沒有提到軟啟動板。該資料夾最後一次變更是在 2024 年 4 月,早於 2024 年 7 月的更新。
- 它的 issues.txt 寫道:「輸入 mosfet 配置錯誤」,並參考了一份 Texas Instruments 應用筆記(slva948);「至少對輸入電源而言,電流感測不應是單向的,且必須注意確保輸出電流感測的方向正確(看起來沒問題)。」supercap_simple 資料夾中有一份相同的 issues.txt。
- 電路圖中的一則註記寫著:BIDIRECTIONAL OR UNIDIRECTIONAL? WHICH DIRECTION ARE WE SENSING?
- 沒有任何文件說明這片電路板的用途。我沒有找到任何說它能限制湧入電流的內容。從檔案看,電路板上有 PowerPole PP45 接頭、MOSFET 與電流感測。不要僅憑本指南就製作或安裝這片電路板。
9.3 軟體量測的電壓與套用的限制
主機板透過 100k 與 5.1k 分壓電路及一顆 ADS1115 量測系統電壓,軟體則使用 15 V 與 25 V 的門檻值。
- vehicle/voltage_monitor.py 透過 R_HIGH = 100 與 R_LOW = 5.1(千歐姆)的分壓器讀取一個 ADS1115 通道。主機板上有一個由 ET6226M 驅動的 7 段顯示器,車輛軟體用它來顯示電壓。
- 在量測到的電壓高於 _SAFE_STARTUP_VOLTAGE = 15 之前,motors_can.py 不會連接馬達。它會記錄 Input voltage too low,並每秒重試一次。
- remote_control_process.py 設定 _VOLTAGE_CUTOFF = 25。平均電壓低於 25 時,它會將自主指令歸零,而在手動控制分支中,它會記錄 LOW VOLTAGE PAUSE,且不轉發搖桿指令。
- 這些是程式碼中的軟體門檻值,而不是有文件記載的運作極限。原專案沒有說明匯流排的最高電壓。驅動模組的描述是標稱額定 53 伏特。
10. 伺服器、模擬與首次自主運行
伺服器另外在 Docker 中執行。原專案詳細記錄了模擬步驟,實車則只透過腳本記錄。
10.1 先執行模擬
原專案的模擬說明檔會在一台 Linux 電腦上,以 Docker 執行一個伺服器與一台模擬車輛,不需要任何硬體。
- 說明檔表示這是「早期階段的 alpha 品質」。啟動腳本設計為在 linux 上執行。
- 安裝 Docker,依照 Docker 的安裝後步驟讓一般使用者能啟動容器,並安裝 docker-compose。
- 複製儲存庫,進入該目錄並執行 ./run_docker_simulation.sh。容器需要一些時間建置。主機上必須有數個可用的連接埠,包括 port 80,你也可能需要中斷 VPN 連線。
- 在瀏覽器中開啟 localhost。若要載入路徑並執行模擬機器人:點選 select a path,然後選擇例如 aaa_test3;點選右側的 Load Path(應會出現 Loaded Path Name);點選 Clear Autonomy Hold;點選 Activate Autonomy。移動車會沿著載入的路徑行進。
- 若要查看輸出,執行 ./attach_docker_vehicle.sh,然後執行 tmux a -t main(或 tmux a -t motors)。要離開 tmux,請按 Ctrl+B 再按 D。不要按 Ctrl-C,那會終止程序。在容器提示字元下按 Ctrl+D,可以離開容器而不停止它。
- 用 ./stop_docker_simulation.sh 停止模擬。
10.2 伺服器電腦
伺服器容器會在任何能執行 Docker 的電腦上執行 Redis、ZMQ 常駐程式、網頁介面與系統管理程式。
- Software 頁面表示,伺服器程式碼通常在另一台機器上執行,但也可以在機器人上執行。
- build_docker.sh 會建置 docker-compose-server.yml。run_docker_server.sh 會停止並移除任何名為 acorn_server 的容器,並在背景啟動它。
- docker-compose-server.yml 開放連接埠 80、8123、5570、6379 與 6799,並以特權模式執行容器。
- server/autolaunch_server.sh 會為 redis、zmq、zmq_ppq、web 與 system_manager 啟動 tmux 工作階段。
- 除了這些腳本之外,原專案沒有針對實際伺服器的書面設定說明。模擬說明檔將網頁介面描述為工程用介面,在部署給終端使用者之前還需改進。
10.3 告訴車輛伺服器的位置
vehicle/server_config.yaml 包含 vehicle_name、server(位址與連接埠)與 site,隨附的檔案指向某位開發者的網路。
- 隨附的檔案內容為:vehicle_name: acorn1;server: 192.168.1.170:5570(另有兩個位址被註解掉);site: twistedfields。
- 將 server 改為你的伺服器電腦位址。Port 5570 是伺服器容器開放的連接埠之一。
- main_process.py 從 Raspberry Pi 上的 /home/acorn/vehicle/server_config.yaml 讀取該檔案。由於 docker-compose-vehicle.yml 將主機資料夾 /home/acorn/acorn 掛載為容器中的 /home/acorn,因此該檔案就是同步過去的軟體資料夾中的 vehicle/server_config.yaml。
10.4 軟體中會讓探測車停止與不會讓它停止的條件
軟體在發生馬達錯誤、電壓過低、失去 GPS 定位或路徑誤差過大時,會將自主運作歸零,但目前的程式碼中已關閉與伺服器連線的檢查。
- 從 remote_control_process.py 中讀出:當馬達未啟用、平均電壓低於 25、雙 GPS 定位遺失、RTK 資料時效超過 20.0 秒或解算結果時效超過 1.0 秒時,自主指令會被歸零;路徑跟隨程式碼會收到 _MAXIMUM_ALLOWED_DISTANCE_METERS = 2.5 與 _MAXIMUM_ALLOWED_ANGLE_ERROR_DEGREES = 120 的限制值。我沒有追查超過這些限制時會發生什麼事。
- 伺服器連線檢查(距上次與伺服器聯繫超過 SERVER_COMMUNICATION_DELAY_LIMIT_SEC = 10 秒)被包在 IGNORE_SERVER_COMMUNICATIONS_ERRORS == False 條件中,而該常數被設為 True。因此在目前的程式碼中,與伺服器失去聯繫並不會讓移動車停下。
- 在 main_process.py 中,60 秒的伺服器中斷限制(_MAX_ALLOWED_SERVER_COMMS_OUTAGE_SEC)只用在已被註解掉的程式碼中。
- 手動控制使用 SBUS 接收器(程式碼設定 _USE_SBUS_JOYSTICK = True)。原專案沒有指明接收器或發射器的型號。
- 原專案沒有提供實地測試程序,也沒有安全區域的指引。