使用者操作手冊

適用版本：v5.9.214+（2026-06-05）
適用對象：現場工程師、設備管理員、系統整合人員

v6 更新摘要（v5.9.197 → v5.9.214）

• 發佈間隔由 MQTT payload 設定（WI-143，v5.9.214）：定時發佈類流程（用電量、磅秤發重量） 啟動命令的 payload 數值 = 發佈間隔秒數。送 5 → 每 5 秒發；送 2 → 改每 2 秒（即時生效， 不用重設）；送 0 → 停。秒數夾 1~3600。例：{prefix}/cmd/signal/1 送 5。 （舊版 ≤5.9.213：payload 只當開關，間隔固定。）
• RS485 型號模板 + 一鍵套用（WI-139/143）：RS485 設備編輯視窗挑「設備類型」（Finder 6M / SF965 計數器 / TDA08B 磅秤 / 自訂）即帶出正確 Modbus 暫存器；既有設備可按 **「⤵ 套用型號預設暫存器」**一鍵補齊。Finder 設備另有 「⚡ 套用「用電量發佈」流程範本」 一鍵建立整套發佈流程（閘訊號 + 通道 + 模板），免手動逐項設定。
• SF965 計數器暫存器圖修正：當前計數值在 0x0004（非 0x0000）；32-bit 值需 ÷256 解碼。
• MQTT topic 前綴 = 設備 UID：所有命令/發佈走 mes/gateway/{設備UID}/...（UID 見 Settings → 系統資訊；非 MQTT 設定頁顯示的 topicPrefix）。

v5 更新摘要（v5.9.128 → v5.9.197）

• 新增「工作流程」頁（WI-128/129/130）：把規則鏈以白話卡片呈現，操作員從畫面就能 觸發 / 開關 / 監看流程與即時狀態，無需下 MQTT 命令。詳見 §10.5。
• 對外 MQTT 設備探索/資訊（WI-131，v5.9.197）：第三方現場管理端可發免前綴廣播 mes/gateway/whoami（或 <prefix>/cmd/info）→ 設備回 <prefix>/info 摘要 + 各通道 <prefix>/info/io/<id>（含可控制的 MQTT topic）。整合合約見 ../specs/spec-mqtt-integration.md。
• 開關型流程（WI-130，v5.9.196）：持續性的「閘門信號」（如磅秤的 發重量開關）會自成一張 on/off 開關卡，附即時「發送中 / 待命」狀態 —— 一鍵開始 / 停止，畫面看得出在不在動。
• 磅秤發重量 100% 通用化（WI-130）：移除磅秤特製韌體，改用通用 Converter＋命令門控； 舊主題 cmd/scale/active 已停用，啟停改用「發重量開關」（內部 cmd/signal/7）。

v4 更新摘要（v5.9.64 → v5.9.82）

• 登入流程強化（v5.9.64+）：不再信任下拉「權限級別」選項，登入時實際 probe /api/tokens 判定 admin/viewer 真實權限。即使下拉誤選，UI 角色仍以 token 真實權限為準
• /api/system auth 補上（v5.9.76）：亂打密碼會被 401 擋下，不會誤導用戶以為登入成功
• 登入 lwIP race 修補（v5.9.75）：兩個連續 fetch 加 250ms 間隔 + 3 次 retry，避免 單線程 HTTP 短時間內被打爆出現「網路錯誤：Failed to fetch」
• 瀏覽器 cache ETag 機制（v5.9.65）：升級韌體後 ETag 變動 → 強制 re-fetch，不再卡 24h max-age 拿到舊 UI bundle
• OTA 連續升級穩定（v5.9.66~78）：修補多項 race 問題（QSPI partition 殘留、 localConfig.remount() 干擾、reboot delay 中其他 task 寫 QSPI），現在連續 OTA 升級不再 brick 進 DFU
• Settings → 使用者管理 改稱「使用者/密碼」（v5.9.77）：UI 字眼從 token 改成 更直覺的「密碼」，admin 可在 Settings 頁直接新增/刪除/變更使用者，三語完整

v3 更新摘要（v5.9.63）

• WI-112/115：Web 登入改密碼制，admin/viewer 兩級權限
• WI-113：UI 三語切換（繁中 / 簡中 / EN，右上 🌐 自動偵測 + 強制切換）
• 雲端 admin UI 韌體列表改 card 排版（最新版高亮 + changelog details）
• Viewer 可瀏覽 + 切換語系，無法變更設定 / I/O / 規則
• OTA 加入同版號 + size 安全 guard（>780KB 強制改用 USB DFU，避免 brick）

本手冊說明 MES I/O Gateway 的核心設計理念，以及如何透過 Web Dashboard 完成安裝、設定與日常操作。

#1. 產品概述

MES I/O Gateway 是一台安裝在工廠現場的智慧型 I/O 閘道器。它以 Arduino Opta 工業控制器為核心，將產線上的感測器、開關、電表等設備，透過內建的規則引擎與通訊協議，串接到工廠的 MES、SCADA 或其他上層管理系統。

一句話定位：把現場的物理訊號，變成工廠系統能理解的數位資訊，並且根據規則自動執行控制動作。

#1.1 它能做什麼？

#1.2 系統組成

┌─────────────────────────────────────────────────────┐
│                    工廠上層系統                        │
│         MES / SCADA / HMI / 資料庫                    │
└──────────┬──────────────────┬────────────────────────┘
           │ MQTT             │ Modbus TCP
┌──────────▼──────────────────▼────────────────────────┐
│              MES I/O Gateway (Arduino Opta)           │
│  ┌──────────────────────────────────────────────┐    │
│  │  Web Dashboard    規則引擎    設定持久化       │    │
│  └──────────────────────────────────────────────┘    │
└───────┬────────────────────────────┬─────────────────┘
        │ Ethernet / WiFi           │ RS485 Modbus RTU
   ┌────▼────┐                ┌─────▼───────┐
   │ 瀏覽器   │                │ 電表/感測器  │
   │(設定操作) │                │ (現場設備)   │
   └─────────┘                └─────────────┘

        物理 I/O：I1-I8 輸入 ←→ DO1-DO4 輸出

#2. 核心設計理念

在開始操作 Dashboard 之前，請先花幾分鐘理解以下核心概念。掌握這些設計理念，你會發現後續的操作設定變得直覺而且有邏輯。

#2.1 多對多架構：為什麼不是一對一？

傳統的 I/O 控制通常是「一個輸入控制一個輸出」。例如：按下按鈕 → 燈亮。

但在工廠現場，真實需求往往更複雜：

• 多個輸入 → 一個判斷：安全門關閉 AND 急停未按下 AND 壓力正常 → 才算「可以啟動」
• 一個判斷 → 多個輸出：「可以啟動」 → 綠燈亮 + 蜂鳴器短響 + 發送 MQTT 訊息通知 MES
• 同一個輸入 → 參與多個判斷：「安全門」同時用於「啟動條件」和「緊急停止條件」

這就是 多對多（Multi-to-Multi） 的設計理念：

        多個輸入                              多個輸出
  ┌─────────────┐                      ┌─────────────┐
  │ 安全門 (I1)  │──┐                ┌──│ 紅燈 (DO1)   │
  │ 急停 (I2)    │──┼── 訊號群組 ──┐ │  │ 綠燈 (DO2)   │
  │ 壓力 (I3)    │──┘              │ │  │ 蜂鳴器 (DO4) │
  │              │        規則引擎  ├─┤  │ MQTT 通知    │
  │ MQTT 指令    │──┐    (IF→THEN) │ │  └─────────────┘
  │ 電表讀數     │──┼── 訊號群組 ──┘ │
  │ 計數器到達   │──┘                └── 動作群組
  └─────────────┘                       (控制多個輸出)

關鍵好處：你可以自由組合任意輸入和輸出，不受硬體接線的限制。改接線不需要改規則，改規則不需要改接線。

#2.2 四層邏輯模型

為了實現多對多，系統將訊號處理分成四層。每一層各司其職，互不干擾：

  第一層              第二層              第三層            第四層
  ─────              ─────              ─────            ─────
  命名與定義          邏輯處理            組合分組           規則連結

  ┌─────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
  │ I1 安全門 │────▶│ 計數器    │────▶│ 訊號群組  │────▶│ 規則引擎  │
  │ I2 急停   │     │ 計時器    │     │(多輸入合一)│     │(IF → THEN)│
  │ I3 壓力   │────▶│ 類比換算  │────▶│          │     │          │
  │ DO1 紅燈  │     │ 延遲處理  │     │ 動作群組  │◀────│          │
  │ DO2 綠燈  │     └──────────┘     │(多輸出合一)│     └──────────┘
  │ MQTT 通道 │                      └──────────┘
  └─────────┘

第一層：命名與定義（你有什麼？）

把硬體端子和網路通道取一個人看得懂的名字。

為什麼要命名？ 之後建立群組和規則時，選單裡會顯示你取的名字而不是 I1、I3。這讓設定更直覺，也讓其他工程師一眼就知道每個通道的用途。

第二層：邏輯處理（需要計算嗎？）

有些訊號不能直接用，需要經過處理：

不是每個通道都需要第二層。 如果你只是要偵測「門開了沒」，I1 的數位訊號可以直接跳到第三層使用。

第三層：組合分組（怎麼組合判斷？）

把多個訊號來源組合成一個有意義的條件（訊號群組），或把多個輸出組合成一個動作（動作群組）。

訊號群組範例（📡 輸入側）：

動作群組範例（⚙️ 輸出側）：

第四層：規則連結（什麼時候做什麼？）

為什麼要分這麼多層？ 因為解耦。假設你把壓力感測器從 I3 換到 I5，你只需要在第一層改名字，第二到四層的設定完全不用動。

#2.3 三大通道類型

在多對多架構中，「多」不只是物理的開關和繼電器。系統支援三種通道，它們都可以自由混合在群組裡：

混合範例：一個訊號群組可以同時包含「I1 安全門（物理）」+「計數器到達 100（虛擬）」+「MES 發來 START 指令（網路）」。這三個條件全部成立時，才觸發動作。

#2.4 設定流程總覽

理解了四層模型後，實際操作的順序就是依序完成每一層：

第一步                第二步               第三步              第四步
在「配置頁」          在「配置頁」          在「配置頁」         在「規則頁」
命名你的 I/O          建立虛擬通道          建立群組            連結規則
───────────          ───────────          ──────────          ──────────
I1 → 安全門           壓力 → 類比換算       訊號群組：           IF 壓力異常
I3 → 壓力感測器       I1 → 產量計數器       「壓力異常」          THEN 警報模式
DO1 → 紅燈                                動作群組：
DO4 → 蜂鳴器                              「警報模式」          驗證 ✓
MQTT → MES 指令

後續章節將按照這個順序，帶你在 Web Dashboard 上完成每一步的操作。

#3. 端到端範例：壓力監控場景

在進入各頁面的詳細操作說明之前，先用一個完整的現場情境，示範從接線到規則觸發的全過程。

#情境說明

工廠有一台沖壓機，現場配置如下：

需求：壓力超過 6.5 bar 且安全門關閉時 → 亮紅燈 + 蜂鳴器響 + 通知 MES。壓力恢復正常時 → 切回綠燈。

#設定步驟對照表

每個步驟的詳細畫面操作說明，請參見第 7 章（配置頁）和第 8 章（規則頁）。

#4. 安全與操作注意事項

在接線、設定與更新前，請先確認以下事項：

• 請使用穩定的 24V DC 工業電源。
• 接線或更換 RS485 設備前，先關閉相關設備電源。
• RS485 匯流排上的每台設備必須使用唯一 Slave ID。
• WiFi 僅支援 2.4GHz 網路。
• 執行 OTA 或工廠重置前，先確認設備不在關鍵生產控制時段。
• 不要在公開文件中記錄管理員密碼、Token、雲端 Registry 密碼或 VPN 密碼。
• 若使用 USB Serial Monitor 除錯，拔除 USB 前請先關閉 Serial Monitor，避免 Mbed OS Serial 阻塞影響主迴圈。

#5. 系統組成

MES I/O Gateway 由以下元件組成：

#6. 首次上線流程

#6.0 全新設備開荒（USB 拓荒包，僅第一次）

📦 剛出廠 / 變磚的設備請先做這一步；已在運作的設備可直接跳到 6.1。

全新 Opta 出廠時還沒有本專案的完整韌體與網頁。請先用 USB 燒一次拓荒包把設備帶起來：

1. USB 首燒拓荒包 mes-gateway-bootstrap.bin（無版號、固定一顆，雲端公開頁「🔧 全新設備開荒」藍框可直接下載，連結永不變）：

   bash

   arduino-cli upload -b arduino:mbed_opta:opta -p <PORT> -i mes-gateway-bootstrap.bin

   （詳細燒錄步驟見 guide-cli-opta.md。）
2. 開機即見開荒設定頁：顯示 🆔 裝置 UID（供雲端綁定/授權）+ 🌐 網路設定 + 🚀「上傳 .mesb」大按鈕。8310 會自動隱藏 WiFi 欄（型號感知）。
3. 上傳官方完整版 .mesb → 設備自動寫入 QSPI 並重開 → 完整版上線（韌體 + 完整 UI 一次到位）。

💡 拓荒包只負責「開荒」這一次,極少更新;之後所有功能 / 版本更新一律走完整版 .mesb（見 §13）。發佈端的程序分工見 guide-ota-embedded-web.md。

#6.1 接線與上電

1. 將 Arduino Opta 接上 24V DC 電源。
2. 若現場有有線網路，接上 Ethernet 網線。
3. 上電後等待設備完成啟動。
4. 確認狀態燈不是紅色錯誤狀態。

常見 LED 判讀：

主機 Status LED（L1-L4）= DO1-DO4 輸出狀態指示

USER LED = 系統狀態燈號

⚠️ 心跳燈顏色依機型不同（v5.9.244+ / WI-152）：

• Opta WiFi (8320)：心跳是藍燈（與下表「藍色慢閃」相同）。
• Opta RS485 (8310)：藍燈是 BLE 模組燈，官方明文「僅 WiFi 版能亮」，8310 點不亮 → 心跳改用琥珀色（紅+綠同亮）。看到 8310 跳琥珀慢閃 = 系統正常，不是錯誤。

#6.2 找到設備 IP

優先使用 Ethernet：

1. 將設備接上工廠 LAN。
2. 到路由器或 DHCP Server 查找設備 IP。
3. 在瀏覽器開啟 http://<gateway-ip>/。

若無法取得 IP，可使用 AP 設定模式（僅 Opta WiFi 8320）：

開機時按住 USER 按鈕，依燈號分段放開（門檻依機型自動切換，WI-152）：

進 AP 設定模式（僅 8320）後：

1. 使用手機或電腦連接 WiFi：MES-Gateway-Setup。
2. 預設密碼：12345678。
3. 瀏覽器開啟 http://192.168.3.1。

⚠️ 「原廠重置」只刪設定、留授權憑證、不清分割區（僅 config.json/config.bak，重開機）。 要連 QSPI 分割區一起清(從無到有)請用 QSPIFormat，見 新機初始化「從無到有」。

⚠️ Opta RS485 (8310) 無 WiFi，進不了 AP 模式（嘗試會 fallback）。8310 請改走有線網路設定，或用「拓荒包（Bootstrap）」自包設定頁（見 安裝手冊 §4.2 與 新機初始化）。韌體會用 OTP 自動分辨機型，型號感知過濾見下方「網路設定差異」。

網路設定差異（型號感知，WI-151）：8310（無 WiFi）開啟「設定」頁的網路卡片時，會自動隱藏 WiFi 帳密區與整個介面模式選單（強制乙太網路，只留 Ethernet IP 的 DHCP/靜態設定）；8320 顯示完整 WiFi + 介面模式（自動/僅有線/僅 WiFi）。前端依 /api/system 的 hasWifi 欄位判斷。

#6.3 首次登入與帳號

進入 Web Dashboard 後會跳出 🔐 登入框：

#出廠預設密碼

多數設備（含目前在線的 v5.9.82）都是 change-me-admin / change-me-viewer：

為什麼不是 smmsadmin？ WI-115（v5.9.54）把預設值「程式碼裡」改成了 smmsadmin / smmsviewer，但 seedDefaults() 只在 tokenCount == 0 時執行（首次 boot / factory reset）。任何升級上來的設備，QSPI LittleFS 已有舊 token 紀錄（tokenCount > 0），不會 reseed，所以仍是 change-me-admin / change-me-viewer。

新出貨的全新設備（QSPI 從未寫過 config）才會看到 smmsadmin / smmsviewer。

想確認你的設備：USB 接上 → serial 115200 baud → 開機 log 會看到 [Token] Loaded N tokens from config（升級設備）或 [Token] Seeded defaults (admin / viewer). PLEASE CHANGE PASSWORDS IMMEDIATELY.（首次 boot 才會 seed 新預設值）。

首次登入後請立即更換密碼（見下方「變更密碼」流程）。

#登入流程說明（v5.9.64+）

1. submitLogin 發 GET /api/system 帶 Bearer token → 401 = 密碼錯誤；200 = token 有效
2. 250ms 後再發 GET /api/tokens probe → 200 = admin；401 = viewer/control（最多 retry 3 次防 lwIP busy）
3. 三次 probe 全失敗 → fallback 用 token 字面比對預設值 (smmsadmin/change-me-admin → admin)
4. 登入成功 → localStorage 存 token + 真實 perm，body class 套 perm-admin 或 perm-readonly

下拉「權限級別」誤選不會卡死 UI：v5.9.64 之前若下拉選 viewer + 用 admin 密碼登入，UI 會被 perm-readonly CSS 鎖死所有按鈕。現在以 /api/tokens probe 為準，下拉只是 UI 提示。

#變更密碼（admin only）

1. 以 admin 登入
2. 進「設定」頁 → 「👥 使用者管理」卡片
3. 點 admin 那組旁邊的「💾」儲存（先在密碼欄輸入新密碼 4-31 字元，留空＝保留原值）
4. 也可按「🗑」刪除（系統會防呆，不允許刪掉最後一個 admin token）
5. 「➕ 新增」可加最多 4 組使用者，每組可獨立設定權限（viewer / control / admin）
6. 變更後重新登入確認新密碼可用

#切換語系

右上角下拉「🌐 自動」可選 🇹🇼 繁中 / 🇨🇳 簡中 / 🇺🇸 EN。

• 自動：依瀏覽器設定（zh-TW/zh-HK → 繁中、其他 zh → 簡中、其他 → EN）
• 強制切換後存於 localStorage，下次開啟保留設定
• viewer 也可切換語系（純 UI 偏好，不需 admin 權限）

#登入後檢查

• 左側顯示的設備名稱與 IP
• 總覽頁是否能顯示系統狀態
• 設定頁的網路狀態是否符合現場需求
• 若需要 MQTT，先設定 Broker 後再測試連線
• 右上角徽章：🔴 admin / 👁 viewer — 確認與你登入的帳號一致

權限差異：viewer 進站後會看到所有「儲存 / 切換 / 刪除 / 新增」按鈕呈灰階（pointer-events:none），可瀏覽但點不到。例外：語系下拉、輪詢頻率下拉、登出按鈕、關閉 Login modal 按鈕仍可用（純 UI 偏好不算寫入）。

權限不足提示：若 viewer 不小心觸發了需要 admin 的功能（如 API 直接呼叫），會跳出 ⛔「權限不足，此操作需要 admin 權限」toast，不會重新跳出登入框（避免誤導用戶以為密碼過期）。

瀏覽器 cache 提示（v5.9.65+）：升級韌體後若還看到舊 UI 行為，按一次 Cmd+Shift+R（Mac）/ Ctrl+Shift+R（Windows）強制重整即可。之後 ETag 機制會自動帶你抓最新 bundle，不再需要手動清 cache。

#7. Web Dashboard 導覽

Dashboard 主要頁面如下：

在 AP Mode 下，Dashboard 會聚焦在 WiFi / 網路設定，部分工業控制頁面會隱藏，避免設定模式下誤操作。

#8. 總覽頁操作

總覽頁是系統的入口，提供所有實體與虛擬 I/O 的即時狀態監控。

可確認的內容：

• Gateway 是否在線。
• 當前網路介面：Ethernet 或 WiFi。
• MQTT 是否已連線。
• I1-I8 輸入狀態。
• DO1-DO4 與擴充輸出狀態。
• RS485 設備是否在線。
• 生產計數、類比數值、虛擬裝置狀態。

操作建議：

1. 班前先確認所有關鍵設備顯示在線。
2. 若 I/O 命名仍是預設名稱，先到「配置」頁補上現場名稱。
3. 若某個通道呈現灰色或未使用，表示它沒有被納入目前的訊號或動作群組。
4. 重置統計前，先確認是否已備份或記錄本班次資料。

#9. 配置頁操作

配置頁用於設定 I/O 節點的功能與通訊。畫面分為 Host（主機）與 Expansion（擴充模組）兩大區塊。建議依序完成 Layer 1 到 Layer 3：

1. Layer 1：定義實體 I/O 與設備名稱。
2. Layer 2：建立訊號群組與動作群組。
3. Layer 3：在規則頁連接條件與動作。

#9.1 設定 I1-I8 輸入

I1-I8 是共用輸入，可依現場用途設定為數位或類比。

操作步驟：

1. 進入「配置」頁。
2. 找到 I1-I8 通道列表。
3. 為每個通道輸入易懂名稱，例如 安全門, 壓力感測器, 入料偵測。
4. 選擇模式：
   • Digital：用於開關、接點、光電、近接等 0/24V 訊號。
   • Analog：用於 0-10V 類比訊號。
5. 儲存後回到總覽頁確認顯示是否正確。

#9.2 設定 DO1-DO4 輸出

操作步驟：

1. 進入「配置」頁。
2. 找到輸出通道。
3. 為 DO1-DO4 命名，例如 紅燈, 綠燈, 蜂鳴器, 排風扇。
4. 若輸出要由規則控制，後續需在「規則」頁加入動作群組。

#9.3 類比邏輯處理

Analog Logic 可用於比例換算、單位顯示、門檻判斷與濾波。

常見設定：

#9.4 TCP IO 通道（網路通道）

TCP IO 是讓 Gateway 和外部系統（MES、SCADA、其他設備）雙向溝通的橋樑。它把網路上的資料變成規則引擎可以使用的「虛擬輸入」，也可以把 Gateway 的即時資料組合成訊息發送出去。

#運作概念

外部系統                     Gateway 內部
────────                     ────────────

  MES 發 JSON ──── Parser ────▶ TCP IO 通道 ──▶ 可作為訊號群組的來源
  (MQTT 訂閱)     (擷取欄位)     (虛擬輸入)       (跟物理 DI 一樣用)

  Gateway 資料 ── Converter ──▶ MQTT 發佈 ──▶ MES / SCADA 接收
  (DO、計數器等)  (填入樣板)     (組合 JSON)

簡單來說：

• Parser（解析器） = 從外面收資料進來，變成 Gateway 看得懂的訊號
• Converter（轉譯器） = 把 Gateway 的資料包裝好送出去

#三種模式說明

#Parser 詳細操作：從 MQTT JSON 擷取數值

場景：MES 透過 MQTT 發送以下 JSON 到 Topic factory/line1/status：

{
  "machine_id": "CNC-001",
  "pressure": 6.8,
  "temperature": 42.5,
  "door_open": true,
  "status": "RUNNING"
}

你想把 pressure 和 door_open 擷取出來，讓規則引擎可以用。

操作步驟：

1. 進入「配置」頁 → 右側「TCP 通道」卡片 → 點擊 + 新增
2. 設定基本資訊：

3. 新增擷取欄位：

4. 點擊「儲存」。系統會自動訂閱該 MQTT Topic。

5. 回到「配置」頁左側的「虛擬通道」，你會看到新建的 TCP IO 通道已經出現在列表中，可以在建立訊號群組時選取它作為來源。

多欄位擷取：一個 MQTT Topic 可以同時擷取多個欄位。Web UI 提供「新增擷取欄位」按鈕，每個欄位會自動建立一個獨立的 TCP IO 通道。

安全機制：如果 MQTT 斷線或 JSON 格式錯誤，系統會維持「最後有效值」，不會讓規則因為收不到資料而亂跳。你也可以設定「過期時間」，超過 N 秒沒收到更新就自動標記為失效。

#Converter 詳細操作：組合 JSON 發佈到 MQTT

場景：你希望 Gateway 每次規則觸發時，自動發送一則 JSON 到 MES 系統的 Topic factory/line1/gateway_report：

{
  "device": "Gateway-A",
  "pressure_bar": 6.8,
  "door_closed": 1,
  "production_count": 42,
  "uptime_sec": 3600
}

操作步驟：

1. 進入「配置」頁 → 右側「TCP 通道」卡片 → 點擊 + 新增
2. 設定基本資訊：

3. 編寫 JSON 樣板（Template）：

{
  "device": "Gateway-A",
  "pressure_bar": ${io.I3},
  "door_closed": ${io.I1},
  "production_count": ${vc.CNT1},
  "uptime_sec": ${sys.uptime}
}

4. 樣板中的 ${...} 是變數標籤，Gateway 在發送時會自動替換成即時數值。

5. 儲存後，在「規則」頁的動作群組中，就可以選取這個 Converter 通道作為輸出動作之一。

#可用的變數標籤一覽

在 Converter 樣板中，你可以使用以下標籤。Dashboard 的樣板編輯器右側會提供可點擊複製的標籤列表。

進階用法：Process-and-Forward 如果你想讓 Gateway 收到一則 MQTT 訊息後，加上 Gateway 自己的資料再轉發出去，可以在 Converter 樣板中使用 ${raw_payload} 把原始訊息嵌入：

json

{
  "original": ${raw_payload},
  "gateway_ip": "${sys.ip}",
  "local_door": ${io.I1}
}

#Modbus TCP 雙向整合

除了 MQTT，TCP IO 也支援 Modbus TCP 協議，適用於需要與 PLC、HMI 或 SCADA 直接整合的場景。Gateway 同時扮演 Server 和 Client 兩種角色：

                    Gateway 是被動端              Gateway 是主動端
                    (Modbus TCP Server)          (Modbus TCP Client)
                    Port 502 監聽                 主動連線到外部 PLC
    ┌──────────────────────────────┬──────────────────────────────┐
    │ 情境 A：PLC 讀 Gateway       │ 情境 C：Gateway 讀 PLC       │
讀  │                              │                              │
取  │ HMI 讀取 Gateway 的           │ Gateway 輪詢外部 PLC 暫存器， │
    │ DI/AI 狀態顯示在畫面上        │ 作為規則引擎的訊號來源        │
    │ ✅ 已支援                     │ ✅ 已支援                     │
    ├──────────────────────────────┼──────────────────────────────┤
    │ 情境 B：PLC 控 Gateway       │ 情境 D：Gateway 寫 PLC       │
寫  │                              │                              │
入  │ PLC 透過 Coil 遠端控制        │ 規則觸發後，Gateway 主動      │
    │ Gateway 的 DO 輸出            │ 寫入外部 PLC 暫存器           │
    │ ✅ 已支援                     │ 🔜 規劃中                    │
    └──────────────────────────────┴──────────────────────────────┘

情境 A + B：Gateway 作為 Modbus TCP Server

Gateway 開機後自動在 Port 502 監聽。外部 PLC 或 HMI 可以連線讀寫，Register Map 如下：

在設定頁可以調整 Modbus TCP Server 的 Slave ID（預設 = 1）。

情境 C：Gateway 作為 Modbus TCP Client（讀取外部 PLC）

這部分的設定整合在「TCP 通道」中，因為它與 MQTT 一樣都是走乙太網路通訊。

操作步驟：

1. 進入「配置」頁 → 右側找到「TCP 通道」卡片 → 點擊 + 新增。
2. 在彈出的視窗中，將「協議 (Protocol)」下拉選單從預設的 MQTT 改為 Modbus TCP。
3. 此時下方的欄位會動態改變，請設定目標 PLC 的 IP 和 Port。
4. 設定要讀取的暫存器位址 (Register) 與觸發條件 (大於、等於閾值等)。
5. 儲存後，此通道的值可在訊號群組中作為來源使用

情境 D：Gateway 寫入外部 PLC 🔜

此功能目前規劃中。完成後可透過規則引擎在 Action 中選擇 Modbus TCP Write，主動將數值寫入外部 PLC 的暫存器。

#10. 規則頁操作

規則引擎是 Gateway 實現「邊緣運算」與「自動控制」的核心。你可以透過圖形化介面，將多個輸入條件組合，觸發對應的輸出動作。

規則引擎的基本概念是：

IF 訊號群組成立
THEN 執行動作群組

#10.1 建立訊號群組

訊號群組用來描述「什麼情況算成立」。

操作步驟：

1. 進入「規則」頁。
2. 新增或編輯訊號群組。
3. 選擇來源，例如 I1、類比邏輯、RS485 數值、TCP IO。
4. 設定 AND / OR 關係。
5. 設定 debounce 或延遲，避免接點抖動。
6. 儲存。

範例：

#10.2 建立動作群組

動作群組用來描述「成立時要控制哪些輸出」。

操作步驟：

1. 新增或編輯動作群組。
2. 選擇輸出來源，例如 DO、擴充 DO、TCP IO、MQTT 發佈。
3. 設定每個輸出的值。
4. 若是脈衝輸出，設定 pulse 時間。
5. 儲存。

範例：

#10.3 建立規則 (端到端實戰教學)

實戰情境：我們要將設定好的「I1 安全門」與「DO1 紅燈」綁定。當門打開時，亮紅燈。

步驟一：建立訊號群組 (定義 IF)

1. 進入「規則」頁，在左側「訊號群組」卡片點擊 +。
2. 群組名稱輸入：門被打開。
3. 點擊「新增條件」按鈕。
4. 在出現的下拉選單中，來源選擇 I1 安全門。
5. 條件選擇 等於，數值選擇 LOW (假設門開是 LOW)。
6. 點擊「儲存」。

步驟二：建立動作群組 (定義 THEN)

1. 在中間「動作群組」卡片點擊 +。
2. 群組名稱輸入：亮起紅燈。
3. 點擊「新增動作」按鈕。
4. 來源選擇 DO1 紅燈。
5. 動作選擇 開啟 (ON)。
6. 點擊「儲存」。

步驟三：將兩者綁定為一條規則

1. 在右側「規則引擎」卡片點擊 +。
2. 規則名稱輸入：安全防護規則。
3. 當 (IF) 下拉選單，選擇剛建立的 門被打開。
4. 選擇觸發時機為 成立時。
5. 就 (THEN) 下拉選單，選擇剛建立的 亮起紅燈。
6. 確認「啟用」開關有打開，點擊「儲存」。

步驟四：硬體驗證 7. 回到「總覽」頁，手動將接在 I1 的磁簧開關移開（模擬開門）。 8. 你會立刻看到總覽頁的 DO1 燈號亮起，同時機器上的 L1 紅色指示燈亮起。恭喜你完成第一次端到端設定！

驗證規則時建議先使用低風險輸出，例如指示燈，再連接真正設備。

#10.5 工作流程頁操作（白話流程 + 一鍵操作）

「規則」頁是工程師建立邏輯的地方；「工作流程」頁則是把這些規則鏈，以白話卡片呈現給 現場操作員 —— 不必懂訊號 / 規則 / 動作，從畫面就能「執行 / 開關 / 監看」，全程不需下 MQTT 命令。

每張卡片把一條（或一串接在一起的）流程寫成一句話：「當 X → 就 Y」，並依其性質歸成四種角色， 卡片右上角有對應徽章與即時狀態燈：

#操作要點

• 執行一個觸發型流程：在卡片上（必要時）填參數 → 按「▶ 執行」。送出後會短暫顯示「⟳ 送出中」。
• 開關一個持續流程（開關型）：直接撥卡片上的 on/off 開關。
  • 切 ON → 徽章變「🟢 發送中」、卡片發亮，下游開始持續動作（如每 2 秒送一筆重量）。
  • 切 OFF → 徽章變「⚪ 待命」、停止。
  • 狀態由設備即時回報，多人 / 多裝置看到的開關狀態一致（不是只反映你按的那下）。
• 即時值：武裝監控型卡片會顯示條件當前值與「達成 / 未達成」，方便現場判斷。

範例：磅秤發重量 「發重量開關」是一張開關型卡片。切 ON 即開始每 2 秒送 scale/weight；切 OFF 即停。 這取代了舊版要記主題、用 MQTT 工具發 1/0 的做法。詳見《磅秤測試指引》第 3 節。

小提醒：側邊欄切換頁面是即時的；但若剛升級韌體 / UI，請整頁重新整理（Cmd/Ctrl+R）一次， 確保載入最新畫面。卡片資料偶爾顯示「載入中…」數秒屬正常（設備單執行緒輪詢中），稍候即顯示。

#11. 設備頁與 RS485 操作

設備頁用於管理 RS485 / Modbus RTU 設備。RS485 設備分為兩種用途：

一個 RS485 設備可以同時有讀取和寫入暫存器。例如光警器可以讀取「目前狀態」，也可以寫入「切換燈色」。

#11.1 RS485 接線原則

• 使用菊花鏈接線，不建議星狀接線。
• A 接 A，B 接 B，GND 共地。
• 每台設備使用唯一 Slave ID。
• 匯流排長度較長時，於最遠端加 120Ω 終端電阻。
• 所有設備需使用相同 Baud Rate、Parity、Stop Bits。

建議通訊參數：

#11.2 新增 RS485 設備（讀取）

操作步驟：

1. 進入「設備」頁。
2. 開啟 RS485 匯流排工具。
3. 設定全局通訊埠參數。
4. 使用掃描工具尋找設備，或手動新增。
5. 輸入設備名稱、Slave ID、設備類型與輪詢間隔。
6. 如果是已知設備（如 Finder 6M 電表），選擇設備模版自動帶入暫存器。
7. 如果是未知設備，選擇「自訂 Modbus 設備」，手動新增讀取暫存器。
8. 儲存後確認設備狀態為在線。

讀取到的數值會出現在：

• 總覽頁 的 RS485 區塊（即時顯示）
• Converter 樣板 中可用 ${rs485.SlaveID.欄位名} 引用
• 訊號群組 中可作為條件來源

#11.2a 自訂 Modbus 設備完整教學

當你遇到一台不在已知模版清單中的 RS485 設備，需要手動設定暫存器。以下是完整的流程指引。

#步驟一：從設備說明書收集通訊參數

打開設備隨附的說明書（或從廠商官網下載），找到以下資訊：

💡 小技巧：如果設備說明書只有紙本，可以搜尋設備型號 + "Modbus" + "通訊協議" 來找 PDF 版。

#步驟二：設定通訊埠參數

1. 進入「設備」頁 → 點擊「通訊埠設定」
2. 將 Port 1 的 Baud Rate 和 Parity 設為與設備一致
3. ⚠️ 同一條匯流排上的所有設備必須使用相同參數

#步驟三：手動新增暫存器

1. 新增設備 → 類型選「未知 / 自訂 Modbus 設備」
2. 填入 Slave ID（與設備 DIP 開關一致）
3. 在「自訂暫存器」區域，逐一新增：

#步驟四：使用 Modbus Probe 驗證

新增暫存器後，建議用「設備」頁底部的 Modbus Probe 工具做即時測試：

1. 填入 Slave ID、起始暫存器、讀取數量
2. 點「📡 發送 Probe」
3. 確認回應有數值（而非 timeout）
4. 若成功，表示通訊參數正確，可以儲存設備設定

#倍率 (Scale) 與偏移 (Offset) 的常見用法

#實際範例：YX523R 光警器

YX523R 是一款 RS485 光警器，同時有「讀取」和「寫入」暫存器：

快速套用：在設備編輯畫面，從「樣板匯入」下拉選擇「YX523R 光警器 (含寫入)」，系統自動帶入：

• 設備名稱：YX523R 光警器
• Slave ID：4（QA 治具預設；如有不同實機請手動改）
• Baud / Parity：使用 Bus 0 設定（建議 9600 / 8N1）

套用模版後，你仍可以修改或新增暫存器（例如再加 0x03 蜂鳴器）。

#11.2b 手動寫入操作（Dashboard）

設定好寫入暫存器的設備後，在總覽頁 (Dashboard) 的設備卡片中，寫入暫存器會顯示在獨立的「✏️ 寫入暫存器」區塊，每個暫存器旁邊有數值輸入框和「▶ 寫入」按鈕。

操作方式：

1. 在數值框輸入要寫入的值
2. 點擊「▶ 寫入」按鈕
3. 成功時會出現綠色 Toast：✅ 寫入成功: Slave X Reg 0xYYYY = Z
4. 失敗時會出現紅色 Toast：❌ 寫入失敗: Slave X 無回應

💡 手動寫入適合用在：調試新設備、臨時控制、出廠測試。正式生產建議透過「規則引擎」自動觸發寫入。

#API 觸發（curl 範例）

除了 UI 按鈕，韌體還提供 POST /api/rs485/:deviceIdx/write 端點，可從外部腳本一次性寫入：

curl -X POST http://<gateway-ip>/api/rs485/0/write \
  -H "Authorization: Bearer admin-token" \
  -H "Content-Type: application/json" \
  -d '{ "registerIdx": 1, "value": 2 }'
# → { "ok": true, "wroteValue": 2, "elapsedMs": 38 }

• :deviceIdx 為 cfg.modbusDevices[] 索引（0、1、…）
• registerIdx 為該設備自己的 write registers 列表索引（從 0 開始，依設備卡顯示順序）
• 失敗時回 { "ok": false, "error": "rs485_timeout", "message": "RS485 bus 無回應" }

#11.3 新增 RS485 寫入暫存器

當你需要透過 RS485 控制設備（而不只是讀取），需要設定寫入暫存器。

場景：工廠有一台 YX523R 光警器，接在 RS485 匯流排上，Slave ID = 2。你想透過規則引擎控制它的燈色和閃爍模式。

操作步驟：

1. 進入「設備」頁 → 新增或編輯 RS485 設備
2. 在「自訂暫存器」區塊，新增暫存器：

3. 選擇模式為 Write 時，系統會：

   • 自動將 Function Code 設為 FC06（Write Single Register）
   • 不會在背景輪詢中讀取此暫存器（避免衝突）
   • 此暫存器會出現在規則 Action 的輸出選單中

4. 儲存設備設定。

在輸出群組中使用 RS485 寫入（WI-118 端到端範例）：

1. 進入「規則」頁 → 編輯輸出群組 (Action)
2. 點「+ 新增輸出」
3. 第一個下拉「類別」選 📡 Modbus 寫入 (RS485)
4. 第二個下拉「設備」選對應的暫存器，例如 YX523R 光警器 → 燈色 (0x01)
5. 右側橘色框輸入「寫入值」（例如 2 = 綠燈）
6. 注意值欄旁的 hint：例如 💡 1=紅 2=綠 3=藍 4=黃 5=白 6=紫 7=青，會自動從 DEVICE_TEMPLATES.yx523r.registerLabels 讀取
7. 儲存。再到規則頁綁好觸發信號（例如「按鈕按下」）即可

規則範例（WI-118 預設端到端）：
  輸入群組「按鈕按下」  : I1 == 1
  輸出群組「亮綠燈」    : YX523R 燈色 ← 寫入 2
  規則：按鈕按下 → 亮綠燈

實機驗證：
  按下接到 I1 的按鈕 → YX523R 燈變綠 → toast「✅ 寫入成功」

💡 寫入值是 0~65535 的 uint16；rule 觸發時韌體用 outputMode=1 + mappings[0] 模式 把固定值寫入 register。Edge-trigger + 5 秒 refresh 防止 bus 洪水。

⚠️ RS485 寫入會佔用匯流排，系統已內建匯流排鎖定機制，確保寫入不會和背景讀取輪詢衝突。但如果同時有大量寫入操作，可能會略微增加響應延遲。

#11.4 TDA-08B 稱重／測力控制器完整教學

TDA-08B 是單通道 24-bit 高精度 Modbus-RTU 稱重控制器，支援負載傳感器（四線制）直接接入，透過 RS-485 輸出實時量測值、峰值、谷值及穩定狀態。

#11.5.1 TDA-08B 接線

① 負載傳感器 → TDA-08B（四線制標準配色）

⚠️ 上述顏色為一般標準配色，實際請以傳感器原廠說明書為準。

② TDA-08B → Arduino Opta RS-485 端子

💡 若匯流排線長超過 50m，或同一匯流排上有多台設備，建議在匯流排兩端各接 120Ω 終端電阻。

③ TDA-08B 電源

#11.5.2 TDA-08B 通訊參數設定（E-Group）

在 TDA-08B 面板操作：長按 MENU 3 秒進入主選單 → 找到 E GROUP → 短按 MENU 進入。

💡 設定完後短按 ZER 返回，設備自動儲存。

#11.5.3 Gateway 設定（套用模版）

1. 進入「設備」頁 → 點擊「＋ 新增 RS485 設備」
2. 在「從模版套用」下拉選擇 「TDA-08B 稱重控制器」
3. 點擊「套用模版」，系統自動填入：
   • 設備名稱：TDA-08B 稱重控制器
   • Slave ID：1
   • Baud Rate：9600 / 格式：8N1
   • 5 個讀取暫存器（見下表）
4. 確認 Slave ID 與設備面板 E3 設定一致後，按「儲存」

#11.5.4 暫存器說明

套用模版後自動建立以下讀取暫存器：

💡 實時值解讀：TDA-08B 回傳 32-bit 有符號整數。若面板設定 A1 小數點 = 2，則顯示值 = 實時值 ÷ 100。Gateway 目前以整數儲存，請依現場標定結果設定倍率（× / ÷）。

#11.5.5 規則整合範例

場景：當量測值超過 5000（kg）時，觸發警報 DO1

1. 「規則」頁 → 新增規則
2. 訊號群組 → 選擇「TDA-08B 稱重控制器」→「實時值」→ 條件：> 5000
3. 動作群組 → 選擇「DO1 (DO1)」→ 輸出高電平
4. 啟用規則 → 儲存

場景：穩定狀態 = 1 才執行下游動作

1. 訊號群組 → 選「穩定狀態」→ 條件：= 1（Bit 0 = 1）
2. 結合實時值條件，使用 AND 邏輯

#11.5.6 故障排除

#11.5.7 校正引導精靈（v5.9.130+，含燈號提示）

TDA-08B 有砝碼校正是缺一不可的 4 步驟，Gateway 提供引導式精靈 + 燈號提示，避免操作員漏步驟：

精靈以 MQTT-Chain 工作流實作（純設定、無專屬韌體）：推進按鍵發到 …/cmd/signal/N，狀態經 MQTT loopback 強制順序（缺一不可）。

📖 完整操作流程、MQTT 指令、設定建構步驟見：guide-calibration-wizard.md 📖 工作流引擎原理 + API schema見：../specs/spec-mqtt-chain-workflow.md

#11.5.8 用 MQTT 觸發任何 RS485 量測值的「定期回報」

任何在輪詢的 RS485 量測值（磅秤重量、Finder 用電量、SF965 計米數…）都能用同一套通用機制 做「外部下命令 → 設備每 N 秒回報」：一個 MQTT 閘訊號 + 一個 CONVERTER 輸出通道， 發 {prefix}/cmd/signal/N = 秒數 即開始週期上報、送 0 停（payload 即間隔，WI-143）。純設定、無專屬韌體。

💡 發佈時機共三種模式：除了上述「payload 當間隔」（WI-143），另有固定間隔（converterIntervalSec，每 N 秒固定發）與變更時才發（converterOnChange，v5.9.263；值有變才發、沒變不重複）。三種對照詳見〈觸發式定期回報〉。

📖 通用機制與最小骨架、各裝置 recipe（磅秤 / Finder 電力 / SF965 計米器）見： guide-triggered-periodic-report.md

#11.5 RS485 故障排除

#12. 設定頁操作

設定頁面包含網路連線、通訊伺服器與系統管理等進階參數。MQTT、Config Server、系統維護與重置。

#12.1 網路模式與斷線備援 (Failover)

Gateway 擁有強大的雙網路備援能力，確保資料回報不中斷。可用模式如下：

建議：

• 初次部署使用 Ethernet + DHCP。
• 正式上線後可改為固定 IP。
• 若需 WiFi 備援，先在 Ethernet 連線下儲存 WiFi SSID / 密碼。
• 需要掃描 WiFi 時，可切換到 WiFi 設定模式。

#12.2 WiFi 設定模式

當設備進入 AP Mode：

1. 連接 SSID MES-Gateway-Setup。
2. 開啟 http://192.168.3.1。
3. 掃描或手動輸入 2.4GHz WiFi。
4. 儲存認證。
5. 依畫面提示重啟或返回一般模式。

#12.3 MQTT 設定

💡 v5.9.261 起出廠已預設官方 TLS broker + 帳密（port 8883），客戶免自行設定 broker / 帳號密碼即可上雲；只有要改用自家 broker 時才需動以下欄位。

設定欄位：

操作步驟：

1. 填入 Broker 與認證資料。
2. 先按「測試連線」。
3. 測試成功後再儲存。
4. 回到總覽頁確認 MQTT 狀態。

若 MQTT 連續失敗，系統可能自動停用 MQTT，以避免網路堆疊被重試佔滿。修正設定後重新儲存即可再啟用。

#12.4 Config Server

Config Server 用於多設備管理、備份、OTA 與授權。

使用建議：

1. 設定 Config Server URL。
2. 確認設備能回報 heartbeat。
3. 在 Config Server Dashboard 檢查設備是否在線。
4. 完成現場設定後，建立一份配置備份。

注意：裝置端 QSPI Flash 中的 /fs/config.json 是實際運行設定。Config Server 保存的是設備上傳的快照。若兩者不一致，現場運行以裝置端為準。

#12.5 設備授權啟用 (License Activation)

當你拿到一台全新的 Gateway，或者剛為設備重新燒錄韌體時，設備可能會處於未授權狀態。在未授權狀態下，部分功能（如規則引擎儲存、雲端連線）可能會被限制。

如何啟用授權：

1. 進入「設定」頁面，查看頂部的 「授權狀態 (License Status)」。
2. 如果狀態顯示為 ACTIVE (綠色)，代表設備已經授權，無需任何操作。
3. 如果狀態顯示為 PENDING 或 UNLICENSED (黃色/紅色)：
   • 確認設備已經連上網際網路（Ethernet 或 WiFi）。
   • 點擊旁邊的 「啟動授權 (Activate)」 按鈕。
   • 系統會向 Config Server 發起驗證請求，請等待約 3~5 秒。
   • 成功後，畫面上方會跳出綠色提示，狀態變更為 ACTIVE。

注意：授權綁定於硬體的唯一識別碼 (MAC / CPU ID)。只要連上網啟動一次，授權會永久保存在本機的 QSPI Flash 中，之後即使斷網也可以正常運作所有工業控制功能。

#13. OTA 韌體更新

v5.9.155+ 架構更新： 為釋放 Flash 讓 binary 跌破 780KB OTA 上限，app.js、workflow.html、CSS、三套語系字典 （zh-TW/en/zh-CN）已從韌體 PROGMEM 搬到 QSPI runtime 服務（v5.9.192 起 app.js 也外置）。 因此 OTA 需同時更新韌體 + 這 6 個資產，.mesb 單一檔格式已復活（一檔內含 firmware + 全部 web 資產，一次投遞）。

兩種更新檔:

• .mesb（建議） — 單一檔內含 firmware + CSS/語系資產，OTA 一次帶齊，保證韌體與 前端資產同版本。由 scripts/build_ota_bundle.py 打包（見 13.6）。

• .bin（純韌體） — 只更新 firmware，不帶資產。適用於資產未變動、或走乙太網 raw OTA。 （注意:純 .bin over WiFi 的 raw 路徑可靠性較弱,WiFi 設備建議走 .mesb。）

• index.html（載入器）仍嵌入韌體 PROGMEM；但 app.js 已外置 QSPI（v5.9.192+）→ QSPI app.js 缺檔時 UI 會卡「載入中」（index 的 bootstrap 會重試，但無 inline app fallback）。所以升級一律走 .mesb（帶齊資產），別只燒 raw .bin。

• v5.9.78+ 連續 OTA 已驗證穩定;.mesb over WiFi 端對端已驗證（v5.9.170/172）

#13.1 線上 OTA（雲端 → 設備）

由 Config Server 發起，整段流程約 90 秒：

1. 管理員上傳 .mesb（建議）或 .bin 韌體到 Config Server（Web UI「📦 韌體」頁拖放上傳）。 雲端會依檔案 magic 自動辨識（前 4 bytes MESB → 命名 .mesb，否則 .bin）。
2. 在 Config Server 選擇目標設備按「🚀 部署」
3. 設備下次 heartbeat（30s 一次）取得 OTA 指令（含下載 URL），加入本地 pending 清單
4. 設備在「設定」頁「韌體更新 (OTA)」可看到「☁️ 伺服器韌體 v X.Y.Z 可用」
5. 用戶按「📥 選擇版本後更新」開始下載（admin 強制部署可跳過此步自動觸發）
6. 設備依 URL 副檔名分流寫入:
   • .mesb → handleMesbUpload:firmware 先串流收到 P4 暫存 → 關 WiFi → 強制 reformat P2 → copy 到 P2 UPDATE.BIN、web 資產寫入 P4 /cfg/web/（mbed File API）
   • .bin → handleOtaUpload:直接寫 P2 UPDATE.BIN（pre-unlink + 強制 sync）
7. 設置 RTC backup register 後立即 NVIC_SystemReset() 重啟（不留 delay window）
8. Bootloader 讀 RTC magic → 將 UPDATE.BIN 從 QSPI 複製到內部 flash → boot 新韌體

#13.2 離線 OTA（USB DFU）

當以下情況發生時改用 USB DFU：

• 韌體 binary > 780KB（v5.9.78 起 OTA guard 會回 413 自動拒絕）
• 設備離雲端且網路無法連接 Config Server
• OTA swap 失敗 fallback 到 DFU 模式（綠燈呼吸閃爍且無法重啟）

DFU 流程：

1. USB 線連接電腦
2. 連點兩下 OPTA 上的 RESET 按鈕 → 進入 DFU 模式（綠燈呼吸閃爍）
3. 在電腦上執行 pio run -e opta -t upload，或用 dfu-util -d 2341:0364 -a 0 -D firmware.bin
4. 燒錄約 30 秒，自動重啟到新韌體

#13.3 OTA 安全機制（v5.9.78 累積）

自動 reject 條件（POST /api/ota/trigger 回 409 / 413）：

v5.9.66 → v5.9.78 OTA brick 修補歷程

之前連續 OTA 偶爾會 brick 進 DFU。經過多輪除錯找到根因 + 修補：

連續 OTA 兩次 timing 對比已驗證一致（v5.9.81 → v5.9.82 連測）：

• Download → Content-Length: ~2.4s
• handleOtaUpload START → Pre-unlink: ~240ms（FAT mount）
• 整段下載 + reboot：約 90 秒

#13.4 OTA 更新燈號與安全機制

當設備透過線上或離線成功下載新韌體後，會進入重啟並進入底層 Bootloader 模式來進行韌體的替換。這個階段的特徵如下：

• 燈號狀態：設備面板上的 綠燈會呈現緩慢的呼吸閃爍 (DFU 模式)
• 處理時間：Bootloader 將 UPDATE.BIN 從 QSPI partition 2 搬移到內部 flash。約需 30~60 秒（不像舊版要 2~3 分鐘那麼長）
• 安全還原 (Rollback) 機制：Opta 內建了防磚防護。如果在 DFU 過程中斷電，或是新版本韌體存在嚴重 Bug 導致無法正常開機，可以重新 USB DFU 燒入舊版還原
• ⚠️ 嚴格禁忌：在綠燈呼吸閃爍期間，絕對禁止拔除電源

#13.5 OTA 診斷（v5.9.78+）

OTA 各階段都有 [OTA t=Nms] 時間戳前綴方便診斷。可從 USB serial（115200 baud）即時觀察：

[OTA-V2 t=78896ms] Downloading from: https://...
[OTA-V2 t=81330ms] Got Content-Length: 747 KB
[OTA t=81434ms] === handleOtaUpload START ===
[OTA t=81441ms] Mounting MBR partition 2 (OTA)
[OTA t=81677ms] Pre-unlink UPDATE.BIN: OK (removed)
[OTA] Progress: 10%~90%
[OTA t=NNNms] Upload OK; total 765744 bytes (XXXXX ms)
[OTA t=NNNms] RTC: DR0=0x07AA DR1=0xA4 DR2=2 DR3=765744
[OTA t=NNNms] Rebooting immediately via NVIC_SystemReset()...

若懷疑 OTA brick 規律：

1. pio device monitor --port /dev/cu.usbmodem* --baud 115200 接 serial
2. 觸發 OTA #1 + 記錄時間戳序列
3. 連續 OTA #2 + 比對時間差異
4. 任一階段卡住超過 5 秒都應該回報

.mesb OTA 的 serial 特徵（與 .bin 不同）：

[OTA t=Nms] === handleMesbUpload START (.mesb v2) ===
[OTA t=Nms] bundle: fwSize=726996 assets=6
[OTA t=Nms] FW received → P4 temp + CRC OK
[OTA t=Nms] asset OK: app.js.gz / workflow.html.gz / styles.css.gz / i18n-*.json.gz
[OTA t=Nms] all received; shutting down WiFi before P2 copy
[OTA t=Nms] WiFi off; copy FW P4→P2 (alternating mount)
[OTA t=Nms] FW copied → P2 + CRC OK → arming bootloader & rebooting

#13.6 .mesb 打包與資產投遞

📌 發佈端完整 SOP(一般版本 .mesb vs 拓荒包 bootstrap.bin 兩條程序分工)見 guide-ota-embedded-web.md;本節為手冊內的快速編排。

.mesb v2 是單一檔容器（32B header MESB + firmware + 每個 web 資產的 manifest）， 一次帶齊 firmware 與 QSPI 資產。沒有單一腳本一鍵完成，是多步驟手動編排，順序如下。

⚠️ 重點（v5.9.192+）：必須打包「全部 6 個 QSPI 資產」。WI-129 之後 app.js 與 workflow.html 也外置到 QSPI（不再 inline 在韌體）。漏包 app.js/workflow.html → OTA 帶不過 UI 改動（設備留舊資產）。 早期文件只列 4 個（CSS+三語系）是 WI-129 之前的舊狀態，勿照舊抄。

# ── 步驟 0：先產生 web 資產的 .gz（必做，否則 web/build/ 是舊的）──
python3 scripts/build_webpage.py      # → app.js.gz / styles.css.gz / i18n-*.json.gz（+ 重生 WebPage.h）
( cd web && node build-workflow.js )  # → workflow.html.gz

# ── 步驟 1：編譯韌體 ──
pio run -e opta                                            # 授權版(production)
# 免授權版(暫時，授權穩定後將取消)：前置 build flag
# PLATFORMIO_BUILD_FLAGS='-D BYPASS_LICENSE_CHECK' pio run -e opta

# ── 步驟 2：打包 .mesb（fw + 全部 6 個 QSPI 資產）──
python3 scripts/build_ota_bundle.py \
  --fw .pio/build/opta/firmware.bin \
  --asset web/build/app.js.gz \
  --asset web/build/workflow.html.gz \
  --asset web/build/styles.css.gz \
  --asset web/build/i18n-en.json.gz \
  --asset web/build/i18n-zh-TW.json.gz \
  --asset web/build/i18n-zh-CN.json.gz \
  --out release/mes-gateway-v<版本>.mesb

# ── 步驟 3：驗證（務必看到 assets=6 + 各 CRC OK）──
python3 scripts/build_ota_bundle.py --verify release/mes-gateway-v<版本>.mesb

# ── 步驟 4a：本機直接投遞到設備（admin token，會重開機 ~90s）──
curl -X POST http://<device-ip>/api/ota/bundle \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @release/mes-gateway-v<版本>.mesb

# ── 步驟 4b：或上傳雲端 Config Server，再「部署」（設備主動 pull）──
#   ⚠️ 用 https:// 直連（http 會 301→POST 降級 GET→404）；channel=dev 是安全預設(不自動散佈)
CL=$(printf '%s' "v<版本> 變更說明…" | base64 | tr -d '\n')
curl -X POST 'https://opta.smms.com.tw/api/firmware/upload' \
  -H 'Content-Type: application/octet-stream' \
  -H 'X-Firmware-Version: <版本>' \
  -H "X-Firmware-Changelog-B64: $CL" \
  -H 'X-Firmware-Channel: dev' \
  -H 'Authorization: Bearer admin-token' \
  --data-binary @release/mes-gateway-v<版本>.mesb
#   免授權版多帶： -H 'X-Firmware-No-License: 1' -H 'X-Firmware-Variant: nolicense'，檔名加 -nolicense

設備收到後：firmware → QSPI P2 UPDATE.BIN（reboot 後 bootloader 搬入內部 flash）、 web 資產 → QSPI P4 /cfg/web/（runtime 由 serveFile 服務，ETag 304 快取）。

離線/沒網路的現場：用步驟 4a（本機 POST /api/ota/bundle），同網段直接投遞，免雲端。 完全無網路時走 §13.2 USB DFU（但 USB 只燒 firmware、不帶 QSPI 資產 → UI 不會更新；資產需另用 POST /api/web?name=<檔> 逐一補上，或改用 .mesb 路徑）。

雙變體（過渡期）：目前同時發「授權版 / 免授權版」。免授權版是暫時措施（因授權機制尚未穩定）， 授權機制穩定後將停止產出免授權版、並把雲端已公開的 -nolicense.mesb 撤下。

注意：OTA 寫 QSPI 仍有 soft-brick 風險（可 USB DFU 救回）；正式批量部署前務必先單機驗證。

#14. 備份、還原與工廠重置

#14.1 備份

建議在以下時機備份：

• 初次上線完成後。
• 修改規則或通訊設定前。
• OTA 更新前。
• 更換設備前。

可備份的內容：

• 裝置端配置。
• Config Server 的 config-server/data/。
• 韌體版本與 manifest。

#14.2 還原

還原方式：

1. 從 Config Server 選擇指定設備備份。
2. 還原到同一台或替換設備。
3. 設備重啟後檢查配置是否正確。
4. 驗證網路、I/O、規則、RS485、MQTT。

#14.3 工廠重置

工廠重置會清除自訂配置與儲存資料，設備將重新啟動。

執行前請確認：

• 已匯出或備份目前設定。
• 現場人員知道設備會暫時離線。
• 若依賴 WiFi，重置後可能需要重新進入 AP Mode 設定。

#15. 日常巡檢表

建議每班或每日巡檢一次：

#16. 常見問題

#無法開啟 Web Dashboard

處理順序：

1. 確認電源與網路線。
2. 從 DHCP Server 查詢 IP。
3. 嘗試 ping Gateway IP。
4. 若使用 WiFi，確認設備是否進入 AP Mode。
5. 若仍無法連線，使用 USER 按鈕進入安全設定模式。

#設備改 IP 後找不到

可能原因是裝置端 QSPI 已保存舊設定，重新燒錄韌體不會覆蓋已保存的 IP。

處理方式：

1. 使用舊 IP 進入 Web Dashboard。
2. 在設定頁修改網路。
3. 若舊 IP 無法進入，使用 AP Mode 或工廠重置。

#MQTT 顯示連線失敗

檢查：

• Broker IP / Host 是否正確。
• Port 是否開放。
• Username / Password 是否正確。
• Client ID 是否重複。
• 網路是否能連到 Broker。

#MQTT 顯示已連線，但命令／規則沒反應

症狀：Web 正常、MQTT 顯示已連線、設備也能 publish（遙測還在送），但設備收不到任何 MQTT 命令（wizard 推進按鍵、cmd/signal/N 都沒反應）。

原因：broker 重啟或網路抖動後，連線雖恢復但訂閱（subscribe）失效——這是已知 MQTT lib 行為，設備自我偵測不可靠。

處理：

• 立即恢復：POST /api/system/reboot（或斷電重開），重開後訂閱即恢復。
• 長期自動化：部署外部 MQTT Watchdog（scripts/opta_watchdog.py），偵測到連續探測失敗會自動觸發 reboot。詳見 guide-failover-resilience.md §4。

#RS485 設備不穩定

檢查：

• Slave ID 是否唯一。
• 所有設備 Baud / Parity 是否一致。
• A/B 是否接反。
• 線材是否過長或受干擾。
• 是否需要終端電阻。

#OTA 後畫面或功能異常

處理順序：

1. 強制重新整理瀏覽器。
2. 確認設備版本。
3. 檢查 Config Server 是否部署正確 .bin。
4. 若設備無法啟動，進入 DFU / 維修流程重新燒錄。

#17. 文件來源

本手冊依下列文件整理：

• docs/references/ref-document-authority.md
• docs/README.md
• docs/roadmap.md
• docs/api/api-firmware.md
• docs/api/api-config-server.md
• docs/specs/spec-config-system.md
• docs/specs/spec-connectivity.md
• docs/specs/spec-tcp-io-channels.md
• docs/specs/spec-ota-system.md
• docs/guides/guide-first-deployment.md
• docs/guides/guide-calibration-wizard.md — TDA08B 校正引導精靈操作手冊
• docs/guides/guide-failover-resilience.md — 備援機制 + MQTT Watchdog 部署
• docs/specs/spec-mqtt-chain-workflow.md — MQTT-Chain 工作流引擎 + API
• docs/hardware/guide-installation.md
• docs/hardware/rs485/guide-setup-sop.md
• docs/sprints/sprint-23-plan.md
• docs/sprints/sprint-24-plan.md

若後續文件或程式碼顯示功能狀態已更新，請同步修訂本手冊。