MES I/O Gateway / 安裝工程師
02安裝工程師

新裝置配置

📅 最後更新：2026-06-16 | 📌 負責人：KC

本文件描述當拿到一台全新的 Arduino Opta (或 QSPI 分區毀損、需要徹底重置的設備) 時，如何從零開始進行完整的格式化與韌體部署，以確保設備能夠正常切分 User Data Partition (Partition 4) 給 LittleFS 使用，並避免 -3101 掛載失敗的錯誤。

[!TIP] 新做法（v5.9.241+）：QSPI -3101 已自我修復、首燒可走拓荒包。 v5.9.241 起韌體開機會自動修復空白 QSPI（-3101/-3102 都救），全新設備第一次燒入即自我建分割區 + 格式化，不再強制依賴下方手動 QSPIFormat 手續（8320 仍需官方 WiFiFirmwareUpdater 寫入 P1 WiFi 韌體才能用 WiFi）。 新設備最簡單的開荒路徑是 「拓荒包（Pioneer）USB 首燒 → 拓荒頁上傳 .mesb」（見下方「拓荒包流程」與 guide-cli-opta.md）。本文第一/三階段為傳統手動流程，仍可用。

#拓荒包（Pioneer）流程（WI-149，新設備最推薦）

  1. USB 首燒 mes-gateway-bootstrap.bin（無版號、固定一顆；DFU；指令見 guide-cli-opta.md）。拓荒包是同一份完整韌體，只把首頁換成自包的開荒頁（inline CSS/JS，不依賴 QSPI 資產）。雲端下載連結永不變，發佈程序見 guide-ota-embedded-web.md。

  2. 開機設網路：瀏覽器開設備 IP → 拓荒設定頁。頁面只露三件事：

    • 🆔 裝置 UID（唯讀，可一鍵複製，供雲端綁定/授權）。
    • 🌐 網路設定：介面模式（自動/僅有線/僅 WiFi）+ Ethernet（DHCP/靜態 IP）+ WiFi（SSID/密碼）。存檔走 POST /api/config merge，持久化生效。
    • 🚀 上傳 .mesb：大按鈕，選官方 .mesb → 上傳後設備自動燒錄重開成完整版。

    💡 MQTT 出廠已預設官方 broker（v5.9.261）：完整版上線後已內建官方 TLS broker + 帳密（port 8883），一般不需手動設定 MQTT；只有要改用自家 broker 時才到「設定 → MQTT」修改。

  3. 型號感知過濾（WI-151）：拓荒頁 fetch /api/license 取 hasWifi；若為 8310（hasWifi:false），自動隱藏 WiFi SSID/密碼欄 + 整個介面模式選單（強制 ETH_ONLY，只留 Ethernet IP 設定）。8320 顯示完整選項。

  4. 一鍵完整安裝：上傳官方 .mesb（韌體 + 6 個網頁資產 app.js/workflow/styles/i18n×3 + favicon.ico 打包成單一檔）→ 設備寫 QSPI 並重開 → 完整版上線。閉環已實機驗證。

#從無到有：把整台機器清乾淨再重建（簡易）

依「要清多乾淨」分三級，由輕到重：

級別 清除範圍 怎麼做
L1 原廠重置（最常用） 只清設定（config.json），留授權憑證、留分割區 開機長按 USER 按鈕到原廠重置（8320 ≥10s / 8310 ≥5s，見附錄）
L2 徹底清空（交機推薦） 連 QSPI 分割區一起格式化（真正「從無到有」） 跑原廠 QSPIFormat 全清 → 見下方「第一階段」
L3 連韌體一起換 L2 + 重燒底層韌體 雙擊 RESET 進 DFU 重燒，再做 L2

清乾淨後的重建一律走拓荒包三步（不論哪一級）：

  1. USB 燒拓荒包 mes-gateway-bootstrap.bin（無版號固定一顆）。
  2. 開機 → 開荒頁設網路（8310 自動隱藏 WiFi 欄）。
  3. 上傳官方 .mesb → 自動重開成完整版。

💡 多數情況用 L1 就夠（換現場、清掉舊設定）；只有 QSPI 真的壞了 / 要當全新機交付才需要 L2。

以下第一～四階段為傳統手動 / 進階備援流程，需要 L2 徹底清空或不走拓荒頁時才用。

#第一階段：QSPI 徹底清空與格式化 (含 WiFi Firmware 重建)

在寫入自己的專案韌體之前，必須透過原廠提供的 QSPIFormat.ino 工具完整切分 QSPI Flash 磁區。

⚠️ 警告：嚴禁在此階段使用 CLI 或全自動腳本 (如 pio)。 由於 Opta 的硬體設計限制，從 DFU 模式燒錄底層程式後，設備會陷入 dfuMANIFEST 狀態不會自動重啟。這會導致自動連線腳本丟失 USB Port 並且卡死。為了保證 100% 成功，請務必手動透過 Arduino IDE 執行本階段。

  1. 拔掉 Opta 的 USB 線並重新插上（確保硬體徹底斷電，脫離可能的 DFU 錯亂狀態）。
  2. 打開 Arduino IDE。
  3. 點擊頂部選單：檔案 (File) > 範例 (Examples) > STM32H747_System > QSPIFormat。
  4. 在上方選單選擇版子 Arduino Opta 以及對應的 Port (應為 /dev/cu.usbmodem...，非 DFU)。
  5. 點擊 上傳 (Upload)。
  6. 上傳成功後，打開 Arduino IDE 右上角的 Serial Monitor (設定為 115200)。
  7. 對著 Opta 設備按一下實體 RESET 鍵（USB 孔旁邊）。
  8. 等待約一分鐘的紅燈閃爍 (Full Erase)，紅燈熄滅後，Serial Monitor 會出現 Do you want to proceed? Y/[n] 提示字元。
  9. 依序輸入三次 Y 並送出。這會依序建立分區、寫入 WiFi 韌體並以 LittleFS 掛載 Partition 4。

當出現 QSPI Flash formatted! It's now safe to reboot or disconnect your board. 即表示底層格式化大功告成。

#第二階段：專案韌體部署

完成環境淨化後，即可開始寫入我們的 MES Gateway 韌體。

  1. 利用 PlatformIO 編譯並上傳: 切換到專案根目錄 (PillarArduno)，執行：

    bash
    pio run -t upload

    註：若無法自動偵測 port，請加上 --upload-port /dev/cu.usbmodemXXXX

  2. 驗證初次啟動日誌: 開啟 Serial Monitor。確認系統是否有成功掛載 Partition 4 並通過 DHCP 取得 IP：

    log
    [LocalConfig] QSPI size (KB): 16384
[LocalConfig] User partition size (KB): 7168
[LocalConfig] LittleFS mounted successfully!
[LocalConfig] Existing config found: NO
...
Ethernet: DHCP... OK, IP = 192.168.0.x

#第三階段：部署 Web UI (前端畫面)

⚠️ upload_web.py 已廢除（ADR-004/005）。index.html＋核心 app.js 已編進韌體 PROGMEM， CSS／語系／workflow.html 走 QSPI，全部由 .mesb 一檔帶齊 —— 不再有單獨上傳 web 的步驟。

韌體啟動後內建 Web Server 已就緒；把 QSPI 網頁資產補齊有兩條路：

  1. 灌官方 .mesb（推薦，fw＋6 資產一次到位）：

    bash
    curl -sS -X POST "http://<DEVICE_IP>/api/ota/bundle" \
  -H "Authorization: Bearer smmsadmin" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @release/mes-gateway-v<版本>.mesb
# 設備重燒重開，約 90 秒

  2. 純補資產不重燒：逐一 POST web/build/*.gz（見 guide-cli-opta.md §5 方法 B）。

  3. 確認畫面: 打開瀏覽器訪問 http://<DEVICE_IP>/，應看到完整的 MES Gateway 儀表板。

💡 若是全新設備走拓荒包流程（上方），上傳 .mesb 這步已自動完成，無需本階段。

#第四階段：與 Config Server 對接還原 (選擇性)

若這是一台汰換的重製備機，您可以將舊有的設定一鍵還原回去。若為全新出廠設備，可略過此步直接在 Web 介面開始您的設定。

  1. 尋找最新的備份 ID:

    bash
    curl -s http://<CONFIG_SERVER_IP>:8888/api/devices/<DEVICE_ID>/backups

    從回傳的 JSON 陣列中挑選要還原的 filename (例如：config.bak.1773145690841.json)。

  2. 觸發遠端還原: 呼叫 Config Server 的 restore API 將該備份直接推向目標新 IP：

    bash
    curl -X POST http://<CONFIG_SERVER_IP>:8888/api/devices/<DEVICE_ID>/restore \
  -H "Content-Type: application/json" \
  -d '{"filename":"<BACKUP_FILENAME>","targetIp":"<DEVICE_IP>"}'

    注意：被推播的設備將會自動覆寫 /fs/config.json 並在一秒後自動重啟。重啟後 MQTT 與 I/O 設定即全數恢復運作。

恭喜，您已完成 Opta MES Gateway 的全新建置流程！

#附錄：實體 USER 按鈕（開機長按，型號感知 WI-152）

設備正面有一顆實體 USER 按鈕。開機當下按住可觸發以下動作（運行中按無效）； 門檻依型號自動切換（8320 有 WiFi、三段；8310 無 WiFi、兩段），BOOT_LED 進入各 zone 時會閃爍提示。

設備 0–5 秒放開 5–10 秒放開 10 秒+ 放開
8320（有 WiFi）三段 正常開機 AP 模式（MES-Gateway-Setup / 12345678 / 192.168.3.1） 原廠重置
8310（無 WiFi）兩段 正常開機 原廠重置（5 秒+，無 AP 段） 原廠重置

⚠️ 「原廠重置」只刪設定、不清分割區。 它僅 remove("/cfg/config.json") + remove("/cfg/config.bak") 後重開機，授權憑證與 QSPI 分割區都保留。這是「恢復出廠」三級裡最輕的 L1。 真正的「清分割區 / 格式化 QSPI」是上面第一階段的 QSPIFormat，或 -3101 自我修復，跟按鈕是兩回事。