Hardware Lab 安裝與使用說明

1. 下載與啟動

2. 先選對 Target

Hardware Lab 的第一個重要步驟不是燒錄，而是先選對硬體組合。v0.3.0 先選 MangoX2／MangoLite 主板，再選 Pico／Pico W／Pico 2 W 控制板。不同 Target 的 MCU、UF2、Host UART、Gateway 能力與 Recovery 手勢都不同。

3. 上方連線區怎麼填

選好 Target 後，按「重新整理」讓程式掃描可用連接埠。Hardware Lab 會顯示：

• MicroUSB COM：Pico 原生 USB／管理通道。
• USB-TTL / UART COM：Host UART 管理路徑。
• Gateway URL：無線 Target 可使用，預設格式為 ws://mangobox-gateway.local:8765。
• Device ID：需要指定 Gateway 裝置時填入，例如 MB001；切換不同 Target 時不應沿用舊板子的 Device ID。

4. 一般韌體更新

1. 在「韌體」頁按「選擇檔案」。
2. 選擇與目前 Target 完全相符的 UF2。
3. 確認 Target、MCU 與檔名，不要跨板型燒錄。
4. 使用一般「更新韌體 / Update Flash」流程。
5. 依畫面指示進入 UF2 模式；Hardware Lab 會辨識 RP2040 / RP2350 對應的磁碟。
6. 等待複製、重新啟動與後續狀態檢查完成。

進階部署／教師套件

1. 選擇正確的主板、控制板與正式版 UF2。
2. 匯入 Teacher Profile 或 Device Manager Runtime config，確認執行模式與選用的 Gateway 設定。
3. 預設使用 Teacher Profile v1，保留學生檔案與裝置身分。
4. 開始部署，依提示進入 UF2 模式。流程只複製一次 UF2，之後等待 Runtime 版本與目標核對、設定套用及狀態驗證。
5. 等待完成訊息與裝置重新啟動，再進行操作。

選用的 Teacher Profile v2

v2 仍須明確啟用實驗模式。preserve_all 保留設定與檔案；teacher_kit 以韌體預設值套用教師設定並保留檔案；fresh_classroom 清除可寫檔案系統後套用教師設定。

5. Clean Flash 什麼時候用？

Clean Flash 是較深層的重新部署流程，適合裝置設定、執行模式或檔案系統已經混亂，單純更新 Firmware 無法恢復正常狀態時使用。它會結合 Factory Reset-assisted deployment、重新進入 UF2、重新燒錄與目標執行模式設定。

1. 確認 Target 正確。
2. 選擇正確 UF2。
3. 在「初始模式」選擇 Clean Flash 完成後希望進入的模式；一般維護可優先選 MicroPython。
4. 按「Clean Flash」。
5. 依畫面指示完成 Factory Reset、重新連線、Bootloader / UF2 與後續驗證。
6. 不要在流程中任意拔線或關閉程式，除非畫面明確要求。

6. Button + RESET 維護手勢

「維護手勢」頁可協助驗證 Normal、Recovery、Deep Rescue 與 Cancel。先依畫面選擇手勢與目前 stored mode，再使用計時器配合實機操作。

實際按法

1. 先按住 Recovery Button。
2. 短按 RESET，RESET 放開後 Recovery Button 繼續按住。
3. 依目標時間與板上聲光提示判斷。
4. 到達要測試的區間後放開 Recovery Button。

7. 偵測與切換執行模式

在「執行模式」頁可先 Probe Current Mode，再選擇目標模式並切換。Preferred Path 建議先使用 Auto，讓 Hardware Lab 依目前 Target 與可用傳輸選擇管理路徑。

8. 診斷紀錄與報告

視窗下方會累積結構化診斷事件。遇到問題時，不要只截一張「失敗」畫面，建議保留完整紀錄：

• 複製紀錄：快速貼到 GitHub Issue、ChatGPT 或團隊討論。
• 儲存報告：輸出 JSON，包含 app version、Target、選擇的 COM Port、Gateway、Firmware 與診斷事件。
• 清除紀錄：開始下一輪獨立測試前再清除。

9. 常見問題與工具分工

選了 UF2，但 Hardware Lab 不接受

先確認 Target 是否選錯，尤其 MangoX2 / Pico 與 MangoX2 / Pico 2 W 是不同 MCU、不同 UF2。

找不到 MicroUSB

• 確認 USB 線可傳資料。
• 按「重新整理」。
• 若裝置正在被 Thonny 使用，先釋放 COM Port。
• 若需要 ROM UF2，依畫面提示進入 Bootloader。

找不到 Host UART

• 確認 USB-to-TTL 驅動與 COM Port。
• MangoLite Host UART 為 GP4 / GP5；MangoX2 為 GP12 / GP13，115200。
• TX / RX 要交叉接，並共地。

只是想改 Servo / PIR / Light 的 Pin，要用這裡嗎？

不用。這類日常模組與 Pin 設定請使用 Device Manager。Hardware Lab 不把一般 GPIO／ADC／RGB／OLED／Servo／Sensor production test 宣稱為目前公開功能。