現場驗收流程

版本：2.7 | 日期：2026-08-28 | 韌體基線：6.0.83 對象：安裝工程師、業主見證人 相關：出廠測試規範、控制延遲特性

從一台空機開始，到設備上線送出第一筆資料。每一步都寫明要做什麼、看到什麼才算通過、沒通過時怎麼辦，由業主全程見證、逐項打勾。

⚠️ 本文件中的帳號、密碼、IP 一律以 <...> 佔位符表示，實際值請向專案負責人索取，不要寫進公開文件或版本控制。

#給人工驗收者：今天從這裡開始

這一節是人工驗收的作業指引。底下 1500 行是完整規範(遇到問題回頭查), 但你實際要動手的只有兩件事：先讓機器自己證明一遍,再親自走機器碰不到的部分。

#第 0 步 — 先跑自動驗收,綠了才開始(約 13 分鐘)

python3 scripts/acceptance_run.py --dut http://<設備IP> --token <admin token>

看到這行才往下走：

結果：28 PASS · 0 FAIL · 0 SKIP
✅ 驗收流程一口氣跑完，無中斷

為什麼先跑它：它把本文件所有能自動化的測項(階段 0 / 2B.2 / 3 / 4 / 5 / 6、 情境 M、情境 B、情境 D、8.1)串成一次不中斷的執行,測完自清。 先確定這些是綠的,你人工驗的才是機器本身,不是在幫程式抓 bug。 任一項紅燈就先停下處理,不要帶著紅燈進人工階段。

#第 1 步 — 你親自走這 7 項

自動化本質上做不到的部分。逐項打勾,不通過就寫在備註欄。

⑤ 本站沒有計數器硬體,不是跳過不驗,是沒有這個受測對象。 驗收單上請註明「本站無此配置」,不要留空白讓人以為漏測。

📌 改通道名稱時,畫面上方會跳一個藍色徽章「💾 儲存中 N」 —— 那是還沒送完的筆數。 等數字歸零再離開該頁,否則最後幾筆可能還在路上。 (v6.0.78 之前它會顯示成「💾 bH N」,bH 是漏掉的語系鍵,已修 —— WI-207。)

#⑥ 的建議做法：一次操作驗三件事

階段 7 拔電源之前,順手把網路故障切換一起驗掉(WI-197 的修正尚未經實機確認)。 先開一個終端機掛著看：

watch -n 5 'curl -s $DUT/api/diag | python3 -m json.tool | grep -E "resetReason|bootDetail|bootCount"'

步驟 4 的 resetReason=UNEXPECTED／bootDetail 空 是正確的,不是異常 —— 硬體斷電不會留下重開原因的字條(BKPSRAM intent marker 的預期行為), 這正好和軟體重開的 SOFTWARE/api-reboot 分得出來。

⚠️ 長按 reset 不等於斷電。2026-08-26 那次是以長按 reset 完成的, 乙太 PHY／WiFi 模組沒有真正斷電,冷啟動路徑仍未涵蓋 —— 這台家族史上有冷開機競爭問題,所以這次請真的拔電源。

#驗完之後

全部打勾 → 階段 8 結案。 有任何一項沒過 → 寫進驗收單的未通過欄,並取得業主書面同意,或不予交付。

#開始前：環境準備與連線設定

驗收過程會用到命令列工具，先裝好再到現場，不要在業主面前才發現少東西。

# Node（跑自動化測試）
brew install node

# 測試套件與瀏覽器核心
cd <專案>/web
npm install
npx playwright install chromium

# MQTT 命令列工具（發布／訂閱，驗證資料真的送出去）
brew install mosquitto

# Node（跑自動化測試）— 或到 nodejs.org 下載安裝檔
winget install OpenJS.NodeJS.LTS

# 測試套件與瀏覽器核心
cd <專案>\web
npm install
npx playwright install chromium

# MQTT 命令列工具（發布／訂閱，驗證資料真的送出去）
winget install EclipseFoundation.Mosquitto
# 安裝後若找不到指令，把 C:\Program Files\mosquitto 加入 PATH

設備的 IP 與 UID 要等裝好之後才會知道（階段 3.2 會拿到）。 現在先把檔案建好、把已知的填上；DUT 和 UID_DEV 留空，裝好設備再回來補。

每次開新終端機都要載入這些設定（後面所有指令都靠它們）：

📦 現成檔案下載：mqenv.zip

這是一個加密壓縮檔，僅供內部人員使用。 解壓密碼不公開於本文件， 請向專案負責人索取。裡面是已經填好本站實際連線參數的 mqenv.sh， 解開後放到家目錄即可直接 source ~/mqenv.sh 使用，省去手動填值。

外部讀者請依下方範本自行建立，把 <...> 換成你自己環境的值。

macOS / Linux 存成 ~/mqenv.sh，每開終端機 source ~/mqenv.sh； Windows 存成 mqenv.ps1，每開 PowerShell 執行 . .\mqenv.ps1（前面有一個點加空白）：

# ── 設備 ──
export DUT=http://<設備IP>
export TOK=<設備管理token>
export UID_DEV=<設備UID，見設定頁>
export PREFIX=mes/gateway/$UID_DEV

# ── 雲端(版本歷史／備份驗收要用,與設備 token 不同) ──
export CLOUD=https://<雲端網址>
export CLOUD_TOK=<雲端token>

# ── MQTT ──
mq_sub(){ mosquitto_sub -h <broker主機> -p 8883 -u <帳號> -P <密碼> --insecure "$@"; }
mq_pub(){ mosquitto_pub -h <broker主機> -p 8883 -u <帳號> -P <密碼> --insecure "$@"; }

# 存成 mqenv.ps1，每開 PowerShell 執行： . .\mqenv.ps1   （點 + 空白 + 路徑）
# ── 設備 ──
$DUT       = "http://<設備IP>"
$TOK       = "<設備管理token>"
$UID_DEV   = "<設備UID，見設定頁>"
$PREFIX    = "mes/gateway/$UID_DEV"

# ── 雲端(版本歷史／備份驗收要用,與設備 token 不同) ──
$CLOUD     = "https://<雲端網址>"
$CLOUD_TOK = "<雲端token>"

# ── MQTT ──
function mq_sub { mosquitto_sub -h <broker主機> -p 8883 -u <帳號> -P <密碼> --insecure @args }
function mq_pub { mosquitto_pub -h <broker主機> -p 8883 -u <帳號> -P <密碼> --insecure @args }

⚠️ 兩個實測踩過的坑，都會給出誤導性的錯誤訊息：

① 用 --insecure，不要去指定憑證檔。 本系統的 MQTT 走 TLS 但不驗憑證（設備出廠預設 tlsInsecure=true，業主指定）， 所以命令列也該用 --insecure —— 行為與設備一致，而且不依賴任何檔案路徑，換電腦一樣能跑。

反例（實測踩過）：--capath /etc/ssl/certs 會回 Error: Protocol error。 那個目錄在 macOS 上確實存在，所以肉眼看不出是參數錯，而錯誤訊息會把人導向 「broker 或網路壞掉」的方向。改用 --cafile /etc/ssl/cert.pem 雖然能動， 但那條路徑不保證每台電腦都有 —— 依賴它只是把問題延後。

② 用函式包，不要用 export MQ="-h ... -u ..." 這種「把一串參數塞進變數」的寫法。 macOS 預設是 zsh，而 zsh 不會對未加引號的變數做詞彙拆分 —— 整串會被當成單一參數， 報 Unknown option '-h ...'。同樣的寫法在 bash 可以、zsh 不行。函式兩種 shell 都能用。

PREFIX 不要用手拼。 若本站啟用了 MQTT 命名空間（projectName / env）， 實際前綴就不是 mes/gateway/<UID>。設備裝好後用這條確認真正的前綴：

curl -s -H "Authorization: Bearer $TOK" $DUT/api/config | python3 -c "
import sys,json
d=json.load(sys.stdin); m=d.get('mqtt') or {}
proj,env=m.get('projectName') or '',m.get('env') or ''
print('  UID        :',d.get('uid'))
print('  projectName:',proj or '(空)')
print('  env        :',env or '(空)')
print('  → 實際前綴 :', f'{proj}-{env}/gateway/'+(d.get('mac') or '').replace(':','').lower() if proj or env else 'mes/gateway/'+str(d.get('uid')))
"

兩者留空 = legacy 模式，前綴才是 mes/gateway/<UID>。 前綴錯了的症狀是「訂閱端一筆都收不到」，而設備那邊看起來一切正常 —— 很難查。

確認連得到再往下：

curl -s -H "Authorization: Bearer $TOK" $DUT/api/system | python3 -m json.tool | head -12

curl.exe -s -H "Authorization: Bearer $TOK" $DUT/api/system | python -m json.tool | head -12

通過：看得到 version / boardModel，且 version 與交付文件一致。

#開始前：本站硬體表

驗收的每一個數字都要對得上實際接的東西，否則後面每一步都在猜。

電流環有兩種接法，驗收步驟不同，先確認實際是哪一種：

1. 帶 RS485 的電流計（如 Finder 6M）→ 走階段 5，設 Slave ID 與型號模板。
2. 4–20mA 類比訊號直接進類比輸入 → 本版尚未涵蓋。 若本站確實是這種接法，先與專案負責人確認量程換算方式，不要照 RS485 的步驟做。

#階段 R：歸零 —— 把設備恢復成出廠狀態

#🟢 全新未開封的設備：整個階段 R 跳過，直接到「這台機器走哪一條路」

全新機本來就是空的，沒有東西可以清。做歸零不會出錯，但是白費五分鐘。

以下只適用於「動過的機器」 —— 展示機、測試機、退回重配的機器。這類機器必須先歸零，否則舊設定會混進新現場，日後查問題時分不清哪些是這次設的。

#先理解：設備上有兩塊儲存區

「我重燒過韌體了，應該乾淨了吧」是錯的 —— 設定原封不動還在。

#三個層級

⚠️ L1 是交機時最容易踩的坑。 它看起來設定都清光了，但授權憑證還留著 —— 設備重開後會自己把授權狀態還原回去，下一手會拿到一台帶著上一手憑證的機器。交機一律用 L2。

#驗收標準

R.1 確認機器來歷

# 先看它身上有沒有東西 —— 有設定就是動過的
curl -s -H "Authorization: Bearer $TOK" $DUT/api/config | python3 -c "
import sys,json
d=json.load(sys.stdin)
print('  設備名稱  :',d.get('deviceName'))
print('  RS485 設備:',len([x for x in (d.get('modbusDevices') or []) if x.get('name')]),'台')
print('  Wi-Fi SSID:',(d.get('wifi') or {}).get('ssid') or '(空)')
"

# 先看它身上有沒有東西 —— 有設定就是動過的
curl.exe -s -H "Authorization: Bearer $TOK" $DUT/api/config | python -c "
import sys,json
d=json.load(sys.stdin)
print('  設備名稱  :',d.get('deviceName'))
print('  RS485 設備:',len([x for x in (d.get('modbusDevices') or []) if x.get('name')]),'台')
print('  Wi-Fi SSID:',(d.get('wifi') or {}).get('ssid') or '(空)')
"

通過：全新（全部為空）→ 跳過本階段；有任何殘留 → 往下做 R.2。 沒過：連不上、讀不到 → 來歷不明一律當成動過，執行 L3。

R.2 歸零前備份（如果這台上面有還需要的東西）

# ① 叫設備推上去
curl -s -X POST -H "Authorization: Bearer $TOK" $DUT/api/configserver/push
sleep 10

# ② 確認設備這一側沒問題(cloudToken 空白是最常見的失敗)
curl -s -H "Authorization: Bearer $TOK" $DUT/api/configserver | python3 -c "
import sys,json
d=json.load(sys.stdin); c=(d.get('push') or {}).get('cloud') or {}
print('  雲端位址   :',d.get('cloudUrl') or '(空)')
print('  Cloud Token:','(空!)' if not d.get('cloudToken') else '已填')
print('  上次推送   :',c.get('result'),'HTTP',c.get('httpCode'))
"

# ③ 真正的驗收點:跟【雲端】要快照清單,看得到剛推的那一筆
curl -s -H "Authorization: Bearer $CLOUD_TOK" \
  "$CLOUD/api/devices/$UID_DEV/snapshots?limit=5" | python3 -c "
import sys,json
s=json.load(sys.stdin)
print('  快照筆數:',len(s))
for x in s[:5]: print('   -',x.get('filename'))
"

# ① 叫設備推上去
curl.exe -s -X POST -H "Authorization: Bearer $TOK" $DUT/api/configserver/push
Start-Sleep 10

# ② 確認設備這一側沒問題(cloudToken 空白是最常見的失敗)
curl.exe -s -H "Authorization: Bearer $TOK" $DUT/api/configserver | python -c "
import sys,json
d=json.load(sys.stdin); c=(d.get('push') or {}).get('cloud') or {}
print('  雲端位址   :',d.get('cloudUrl') or '(空)')
print('  Cloud Token:','(空!)' if not d.get('cloudToken') else '已填')
print('  上次推送   :',c.get('result'),'HTTP',c.get('httpCode'))
"

# ③ 真正的驗收點:跟【雲端】要快照清單,看得到剛推的那一筆
curl.exe -s -H "Authorization: Bearer $CLOUD_TOK" `
  "$CLOUD/api/devices/$UID_DEV/snapshots?limit=5" | python -c "
import sys,json
s=json.load(sys.stdin)
print('  快照筆數:',len(s))
for x in s[:5]: print('   -',x.get('filename'))
"

通過：② 的「上次推送」是 OK / HTTP 200,而且 ③ 列得出快照, 檔名長得像 snapshot.<一長串數字>.v5.json。 沒過：確定不需要保留就直接往下。歸零之後就真的沒了,這一步不要含糊。

⚠️ ③ 一定要打雲端,不能打設備。 設備端所有 /api/configserver... 開頭的 GET —— 含 /versions、/history —— 回的都是同一包設定,永遠沒有清單。 拿它來驗會誤以為「查過了」,但你只驗到「推得上去」,沒驗到「讀得回來」, 而這一段的全部意義就在後者。

R.3 執行 L2「恢復原廠」

curl -s -X POST -H "Authorization: Bearer $TOK" $DUT/api/system/factory-reset

curl.exe -s -X POST -H "Authorization: Bearer $TOK" $DUT/api/system/factory-reset

也可以在設定頁按「恢復原廠」按鈕，效果相同。 ⚠️ 這會格式化整個設定區（設定 + 網路帳密 + 授權憑證全清），且無法復原。執行前確認 R.2 已完成。

#🛑 歸零之後,雲端還原「不會自己成功」—— 必須先做這一步

恢復原廠連 Cloud Token 一起清掉。而設備去雲端抓設定時,token 是空的就 不會送出授權標頭,雲端直接回 401。結果是:

• 雲端後台顯示還原成功、「已排入佇列」
• 指令確實送到設備、也被消耗掉
• 設備什麼都沒做,而且不會有任何錯誤提示

所以要還原,順序一定是:先填回 Cloud Token,再觸發還原。 走設定頁 §4.1 填,或用指令:

bash

# 注意:JSON 不能有空格 —— 韌體是字串比對,有空格會靜默失敗
curl -s -X POST -H "Authorization: Bearer $TOK" -H "Content-Type: application/json" \
  -d "{\"enabled\":true,\"cloudUrl\":\"$CLOUD\",\"cloudToken\":\"$CLOUD_TOK\"}" \
  $DUT/api/configserver

# 讀回確認再往下,不要憑「回了 success」就相信
curl -s -H "Authorization: Bearer $TOK" $DUT/api/configserver | python3 -c "
import sys,json;d=json.load(sys.stdin)
print('  cloudUrl  :',d.get('cloudUrl') or '(空)')
print('  cloudToken:','已填' if d.get('cloudToken') else '(空!)')"

填好之後才觸發還原(見 §R.5)。實測時間:排入後約 2 分鐘設備心跳取件, 下載完會自行重開,再約 20 秒設定回來。

(此缺陷已開卡 WI-194。修好之前,這一步都必須手動做。)

通過（8320 且未接網路線）：設備自行重開並開出 Wi-Fi 熱點 —— 它已經不記得任何網路了。 通過（8310，或 8320 插著網路線）：這類機器不會開熱點，也不該期待它開。 改用下面這條判準：重開後用 §2B.2 掃描找到它，開啟網頁應看到設定全空 （RS485 清單、規則、通道皆為空）。 沒過：8320 拔掉網路線重開後仍自動連上原本的 Wi-Fi → 沒清乾淨（可能只做到 L1），改用 L3。

R.4 確認歸零結果

先確定要打哪個位址 —— 這一步最容易打錯:

情況	位址
8320 且未接網路線(已開熱點)	連上熱點後用 http://192.168.3.1
8310,或接著網路線的 8320	不會開熱點,用 §2B.2 掃到的新 IP

下面用 $DUT 代表該位址,先把它設成上表對應的值。

# 通道與規則各有自己的端點,不在 /api/config 裡面
for ep in tcpio rules signals actions; do
  printf '  %-8s %s\n' "$ep" "$(curl -s -H "Authorization: Bearer $TOK" $DUT/api/$ep)"
done
curl -s -H "Authorization: Bearer $TOK" $DUT/api/config | python3 -c "
import sys,json
d=json.load(sys.stdin)
print('  RS485 設備:',len([x for x in (d.get('modbusDevices') or []) if x.get('name')]),'台')
print('  Wi-Fi SSID:',(d.get('wifi') or {}).get('ssid') or '(空)')
"

foreach ($ep in 'tcpio','rules','signals','actions') {
  "  {0,-8} {1}" -f $ep, (curl.exe -s -H "Authorization: Bearer $TOK" "$DUT/api/$ep")
}
curl.exe -s -H "Authorization: Bearer $TOK" $DUT/api/config | python -c "
import sys,json
d=json.load(sys.stdin)
print('  RS485 設備:',len([x for x in (d.get('modbusDevices') or []) if x.get('name')]),'台')
print('  Wi-Fi SSID:',(d.get('wifi') or {}).get('ssid') or '(空)')
"

通過：五項全空,長得像這樣 ——

  tcpio    {"count":0,"channels":[]}
  rules    {"rules":[],"ruleCount":0}
  signals  {"signals":[],"signalCount":0}
  actions  {"actions":[],"actionCount":0}
  RS485 設備: 0 台
  Wi-Fi SSID: (空)

沒過：任何一項還留著舊資料 → 沒清乾淨，重做 L3。不要帶著殘留設定往下走，那會讓後面每一個異常都多一種可能原因。

⚠️ 不要拿 /api/config 裡的 tcp 欄位來判斷通道。那個欄位是 {"port":5000} —— 監聽埠,不是通道清單,通道有幾條它都長一樣。 真正的清單只在 GET /api/tcpio。同理,規則/訊號/動作也都不在 /api/config 裡。

#⚠️ 歸零之後打開網頁,你會看到「資產救援」頁 —— 這是正常的

L2 會格式化整個 QSPI,連網頁介面本身(index.html／app.js／styles.css／ 語系檔／log.html／workflow.html)一起清掉。所以歸零後的設備:

• API 完全正常 —— 上面 §R.4 那些 curl 全部照跑不誤
• 但沒有可用的網頁 UI —— / 會回「MES Gateway — 資產救援」頁, /app.js、/styles.css、/log.html、/workflow.html 全部 404

不要以為機器壞了。 網頁介面是靠上傳 .mesb 帶回來的 —— 交機流程往下走到 §2C 上傳正式版韌體時就會恢復。

⚠️ 但如果你是「清錯了要救回來」:§R.5 的雲端還原只還原設定,不還原網頁資產。 設定回來了、畫面還是救援頁 —— 這時要另外推一次 .mesb(救援頁上就有上傳鈕)。

R.3 的判準刻意選「會不會開熱點」，因為那是設定真的被清光的外部證據 —— 它已經不記得任何網路了。比「畫面看起來是空的」可靠得多。

R.5 從雲端還原(只在「清錯了、要救回來」時做;正常交機不需要)

前提:§R.3 的 🛑 區塊已完成 —— Cloud Token 已填回並讀回確認。

# ① 列出可用快照,挑一筆(檔名長得像 snapshot.<一長串數字>.v5.json)
curl -s -H "Authorization: Bearer $CLOUD_TOK" \
  "$CLOUD/api/devices/$UID_DEV/snapshots?limit=10" | python3 -c "
import sys,json
for x in json.load(sys.stdin): print('  ',x.get('filename'))"

# ② 【重要】先確認設備沒有待推送,否則還原會被蓋掉(見下方警告)
curl -s -H "Authorization: Bearer $TOK" $DUT/api/configserver | python3 -c "
import sys,json;d=json.load(sys.stdin);c=(d.get('push') or {}).get('cloud') or {}
print('  needsPush :',d.get('needsPush'),'  ← 必須是 False')
print('  上次推送  : ',c.get('ageS'),'秒前')"

# ③ 觸發還原(把 <檔名> 換成上面挑的那一筆)
curl -s -X POST -H "Authorization: Bearer $CLOUD_TOK" \
  "$CLOUD/api/devices/$UID_DEV/snapshots/<檔名>/rollback"

# ④ 等設備心跳取件(約 2 分鐘),它會自己下載並重開。輪詢到不是 0 為止
for i in $(seq 1 12); do
  sleep 20
  printf '  %s ruleCount=' "$(date +%H:%M:%S)"
  curl -s -H "Authorization: Bearer $TOK" $DUT/api/rules | python3 -c "
import sys,json;print(json.load(sys.stdin).get('ruleCount'))"
done

通過：規則/訊號/動作/RS485/SSID 全部回到歸零前的數量 —— 用 §R.4 那條指令再跑一次比對。 沒過(最常見)：ruleCount 一直是 0 → 十之八九是 Cloud Token 沒填。 回 §R.3 的 🛑 區塊確認,然後重新觸發一次還原 —— pendingCommand 是一次性的,失敗那次已經被消耗掉,不會自己重試。 查證方法:GET $DUT/api/log 找 [CS-Cloud] Command: download_update 與 [ConfigServer] (Cloud) Downloading update from …。兩行都有 = 設備確實在做事。 ⚠️ 該日誌是環形緩衝、會被 [ALIVE] 洗掉,要在觸發後幾十秒內去看。

#🛑 千萬不要「剛改完設定就馬上觸發還原」

還原的做法是把快照寫進雲端的設定檔,再叫設備來下載。而設備的自動推送 (autoPush)會把它自己當下的設定推上同一個檔案 —— 只要這兩件事撞在一起, 還原內容就被蓋掉,設備下載回來的是它自己剛推上去的東西。

實測:填完 Cloud Token 後立刻觸發還原 → 12 秒後設備推送 → 還原被覆蓋 → 看起來「還原成功但設定沒變」。

而 §R.3 的 🛑 區塊正好要你先填 Cloud Token —— 填 token 就是改設定,會排一次推送。 所以順序必須是:

1. 填回 Cloud Token
2. 等到 needsPush 變回 False(通常十幾秒,用上面第 ② 步確認)
3. 才觸發還原

三個環節都會回報成功(rollback success、push OK HTTP 200、下載也真的完成), 錯的只有順序 —— 所以最容易誤判成「還原功能壞了」。

(此缺陷已開卡 WI-195。)

#第一部：安裝與設定

#階段 0：開工前現場條件確認

#這台機器走哪一條路？先分流

兩個問題決定你接下來要做什麼，走錯會白費半小時：

怎麼確認機型？機身標籤有寫；設備能連上之後也可以從畫面或 API 確認（boardModel）。

8310 沒有 Wi-Fi，永遠不會開出熱點。 文件裡凡是提到「連上設備的熱點」， 對 8310 都不適用 —— 它一律走網路線。這是最常見的誤解來源。

#階段 1：空機燒入韌體（拓荒包）

全新設備出廠時沒有我們的韌體，要先燒一個「拓荒包」進去。拓荒包是一個精簡版， 它只做一件事：讓你能連上設備、設定網路，然後把正式版韌體上傳進去。

為什麼分兩段？ 正式版韌體很大，第一次只能靠 USB 燒；但正式版更新頻繁， 每次都接 USB 不實際。拓荒包很少改動，燒一次就好，之後的版本都用網頁上傳。

1.1 安裝工具（每台電腦只需做一次）

brew install arduino-cli
arduino-cli core update-index
arduino-cli core install arduino:mbed_opta

winget install ArduinoSA.CLI
arduino-cli core update-index
arduino-cli core install arduino:mbed_opta

Windows 使用者請至 Arduino CLI 官網下載執行檔並加入環境變數。

1.2 取得拓荒包

curl -O https://opta.smms.com.tw/api/firmware/download/mes-gateway-bootstrap.bin

curl.exe -O https://opta.smms.com.tw/api/firmware/download/mes-gateway-bootstrap.bin
# 注意是 curl.exe —— PowerShell 的 curl 是 Invoke-WebRequest 的別名，行為不同

通過：檔案下載完成且大小合理（數百 KB）。 也可以自己建：在專案目錄執行 bash scripts/build_bootstrap.sh， 產出在 release/mes-gateway-bootstrap.bin。

1.3 用 USB 接上設備，找出它的 Port

arduino-cli board list

通過：清單中出現標示 Opta 或 mbed 的項目，記下它的 Port （macOS 長得像 /dev/cu.usbmodem212201，Windows 像 COM3）。 沒過：沒看到任何裝置 → 換一條能傳資料的 USB 線。只能充電的線不會被電腦看到。

1.4 燒錄

arduino-cli upload -b arduino:mbed_opta:opta \
  -p /dev/cu.usbmodem212201 \
  -i mes-gateway-bootstrap.bin

arduino-cli upload -b arduino:mbed_opta:opta `
  -p COM3 `
  -i mes-gateway-bootstrap.bin
# Port 是 COM 開頭（例如 COM3），不是 /dev/cu.*；續行符號是反引號 ` 不是反斜線

把 -p 後面換成 1.3 查到的 Port。 通過：指令回報成功，設備自動重開。 沒過：權限錯誤 → 確認沒有其他程式（Arduino IDE、序列埠監控）佔用該 Port。

1.5 等首次開機完成

通過：心跳燈開始規律閃爍 —— 亮滅各約 0.5 秒，1 秒一個週期。

⚠️ 心跳燈是哪一顆、什麼顏色,取決於機型 —— 盯錯燈會以為機器沒活過來:

機型	心跳燈
8320(有 Wi-Fi)	機身 USER LED,亮藍色
8310(無 Wi-Fi)	沒有藍燈硬體,改用琥珀色(紅+綠同時亮)

純紅 = 故障、純綠 = DFU,兩者都不是心跳。

⚠️ 快閃（約 0.2 秒一個週期）不是故障。 它代表「MQTT 已啟用但還沒連上」， 在剛設好 MQTT、還沒連上 broker 的期間出現是正常的。 全新設備還沒設 MQTT，看到的會是慢閃。

沒過：全新設備第一次開機要建立檔案系統，可能要 1–2 分鐘，期間絕對不要斷電。 超過 3 分鐘心跳燈仍完全沒有動靜（不閃也不亮）→ 回到 1.4 重燒。

#階段 2A：連上設備 —— 無線機型（8320）

剛燒好的設備還不知道你的網路，所以它會自己開一個 Wi-Fi 熱點等你進去設定。

同樣的情況也發生在做完「階段 R 歸零」之後 —— 網路帳密被清光，設備就回到這個狀態。 這是正常的，不是故障。

2A.1 用手機或筆電連上設備開出的熱點

通過：連上後取得 192.168.3.x 網段的 IP。 沒過：找不到熱點 → 設備可能還記得舊的 Wi-Fi 而直接連上了現場網路， 改用 §2B.2 的掃描工具找它的 IP。

2A.2 瀏覽器開 http://192.168.3.1

通過：看到**「🧭 拓荒包 · MES Gateway 開荒」**頁面，上面有設備 UID、網路設定、 以及「上傳 .mesb」按鈕。 這個畫面和正式版完全不同，看到它是正確的 —— 代表拓荒包燒成功了。

2A.3 在拓荒頁填入現場 Wi-Fi 帳號密碼並儲存，設備會重開

通過：設備重開後不再開熱點，改為連上現場網路。 沒過：又開出熱點 = 帳密錯誤或訊號不足。重連熱點再試一次。

2A.4 找出設備在現場網路上的新 IP → 見 §2B.2（兩種機型共用）

#階段 2B：連上設備 —— 有線機型（8310）

8310 沒有 Wi-Fi，不會開熱點。它一開機就用網路線去要一個 IP（DHCP）， 所以問題不是「怎麼連上它」，而是**「它拿到哪個 IP」**。

2B.1 接上網路線，等 30 秒讓它取得 IP

2B.2 找出設備的 IP（兩種機型都適用）

專案內附一支掃描工具：

把下面這段存成 find-gateway.sh（放哪都可以），chmod +x find-gateway.sh 後執行：

#!/usr/bin/env bash
# 找出網段上的 MES Gateway。判準是「誰以我們的方式回應 API」，不是 MAC ——
# 設備支援軟體 MAC 覆寫，實測過 API 回報 A8:61:0A、arp 表卻是 50:26:EF。
SUB=${1:?用法: ./find-gateway.sh 192.168.1}
TOKEN=${2:-<設備管理token>}
echo "掃描 $SUB.1-254 …"
for i in $(seq 1 254); do
  ( probe=$(curl -s -m 3 "http://$SUB.$i/api/system" 2>/dev/null)
    case "$probe" in *Unauthorized*|*boardModel*)
      info=$(curl -s -m 3 -H "Authorization: Bearer $TOKEN" "http://$SUB.$i/api/system" 2>/dev/null)
      v=$(printf '%s' "$info" | sed -n 's/.*"version":"\([^"]*\)".*/\1/p')
      m=$(printf '%s' "$info" | sed -n 's/.*"boardModel":"\([^"]*\)".*/\1/p')
      echo "  OK  $SUB.$i   ${m:-（token 不符，無法讀型號）}   ${v:+v$v}" ;;
    esac ) &
done
wait
echo "掃描結束"

執行：./find-gateway.sh 192.168.1（換成你現場的網段前三碼）

# 直接貼進 PowerShell 7+ 執行，無需額外工具或檔案
$SUB   = "192.168.1"                 # 換成你現場的網段前三碼
$TOKEN = "<設備管理token>"
1..254 | ForEach-Object -Parallel {
  $ip = "$using:SUB.$_"
  try {
    $r = Invoke-WebRequest -Uri "http://$ip/api/system" -TimeoutSec 3 `
           -SkipHttpErrorCheck -ErrorAction Stop
    if ($r.Content -match 'Unauthorized|boardModel') {
      $info = Invoke-WebRequest -Uri "http://$ip/api/system" -TimeoutSec 3 `
                -Headers @{ Authorization = "Bearer $using:TOKEN" } `
                -SkipHttpErrorCheck -ErrorAction SilentlyContinue
      $m = if ($info.Content -match '"boardModel":"([^"]*)"') { $Matches[1] } else { "（token 不符）" }
      $v = if ($info.Content -match '"version":"([^"]*)"')    { "v" + $Matches[1] } else { "" }
      "  OK  $ip   $m   $v"
    }
  } catch {}
} -ThrottleLimit 64
# PowerShell 5.1 沒有 -Parallel／-SkipHttpErrorCheck，請改用 PowerShell 7+

把 192.168.1 換成你現場的網段前三碼（不知道的話，看自己電腦的 IP 前三碼）。

通過：印出類似 OK <網段>.46 Opta WiFi (8320) v<版本>， 這就是設備的 IP、機型和韌體版本。 沒過：什麼都沒找到 → 見下方「找不到設備時」。

這支工具是靠「誰以我們的方式回應 API」來認人，不是靠 MAC。 設備支援軟體 MAC 覆寫 —— 實測過一台設備 API 回報 A8:61:0A:…、 網路上的 arp 表卻是 50:26:EF:…，用 MAC 前綴去找會漏掉。

找不到設備時，依序試：

1. 網段填錯：確認你電腦的 IP。ipconfig getifaddr en0（macOS）或 ipconfig（Windows）
2. 查路由器的 DHCP 用戶端清單 —— 最可靠，直接列出所有連上的裝置
3. 設備沒拿到 IP：確認網路線兩端都插好、對方交換器埠有燈
4. 8320 而且從未設定過：它在 AP 模式，回到 §2A

2B.3 瀏覽器開 http://<找到的IP>

通過：看到「🧭 拓荒包 · MES Gateway 開荒」頁面（若還在拓荒包階段）， 或完整的五頁籤設定畫面（若已裝正式版）。

#階段 2C：把正式版韌體裝上去

拓荒包只是讓你能連上設備。正式版功能都還沒有 —— 沒有 RS485、沒有規則、沒有 MQTT。

2C.1 取得正式版韌體（.mesb 檔）

向專案負責人索取，或從雲端韌體清單下載當次交付指定的版本。

.mesb 是「韌體 + 網頁資源」打包成的單一檔案，用它更新可以一次到位。

2C.2 在拓荒頁按「上傳 .mesb」，選擇該檔案

通過：上傳完成後設備自動重開，約 2–3 分鐘後重新連上， 這時畫面變成完整的五個頁籤（總覽／配置／規則／設備／設定）。 沒過：上傳中斷 → 確認電腦與設備在同一網段、中途不要關瀏覽器。 拓荒包不會被破壞，失敗可以重來。

2C.3 確認版本

curl -s -H "Authorization: Bearer $TOK" $DUT/api/system | python3 -m json.tool | head -8

curl.exe -s -H "Authorization: Bearer $TOK" $DUT/api/system | python -m json.tool | head -8

通過："version" 與交付文件指定的版本一致。 沒過：版本不符 → 上傳到舊檔案了，回到 2C.1。 版本必須對得上，否則這份驗收單不成立。

#階段 3：網路設定收尾

3.1 確認設備連在正式網路上、IP 穩定

現場建議用固定 IP 或 DHCP 保留，否則設備重開後 IP 可能改變， 上位系統就找不到它了。

3.2 記錄設備 IP 與 UID，填進本單開頭，並更新環境變數

curl -s -H "Authorization: Bearer $TOK" $DUT/api/config | python3 -c "
import sys,json
d=json.load(sys.stdin)
print('  UID :',d.get('uid'))
print('  MAC :',d.get('mac'))
"

curl.exe -s -H "Authorization: Bearer $TOK" $DUT/api/config | python -c "
import sys,json
d=json.load(sys.stdin)
print('  UID :',d.get('uid'))
print('  MAC :',d.get('mac'))
"

後續維運都靠這兩個值找設備，一定要記下來。

#階段 4：雲端備份設定

本階段的目的不是「有備份」，而是證明備份讀得回來。這兩件事不一樣，而且差別很危險 —— 備份可能只壞一半：推得上去、讀不回來。

⚠️ 驗 4.2/4.3 之前先做一個實際的設定變更(隨便改一個沒用到的通道名稱就好)。 雲端對內容相同的推送會去重 —— 設定沒變時推送照樣回成功,但不會產生新快照, 看起來就像推送失敗。走查時因此誤判過一次。

另外:設備端的雲端設定要查 /api/configserver,/api/config 裡沒有這個區塊 —— 拿 /api/config 去看會什麼都讀不到,誤以為 Token 沒填。

4.3 才是真正的驗收點。 實際發生過：推送成功、清單打不開，不特地點開就不會發現。

想用指令驗而不點畫面 —— 用 §R.2 的第 ③ 條(打雲端的 /api/devices/$UID_DEV/snapshots)。不要打設備的 /api/configserver —— 那條永遠不會吐清單,詳見 §R.2 的警告。

#階段 5：物理 I/O —— RS485 設備

先把「設備是誰、值從哪來」定義好。沒有這一層，後面的連動與 MQTT 上行都沒有素材可用。

5.1 掃描匯流排，確認實體設備都在

掃描是非同步的：POST 只是「按下開始」，馬上就返回，結果要另外輪詢。 它會逐一試 9600 / 19200 / 4800 / 2400 × 8N1 / 8E1 / 8N2，要跑數十秒到數分鐘。

# ① 觸發掃描（body 不需要，韌體不看）
curl -s -X POST -H "Authorization: Bearer $TOK" $DUT/api/modbus/scan

# ② 每 10 秒輪詢一次結果，直到掃描結束
curl -s -H "Authorization: Bearer $TOK" $DUT/api/modbus/scan | python3 -m json.tool

# ① 觸發掃描（body 不需要，韌體不看）
curl.exe -s -X POST -H "Authorization: Bearer $TOK" $DUT/api/modbus/scan

# ② 每 10 秒輪詢一次結果，直到掃描結束
curl.exe -s -H "Authorization: Bearer $TOK" $DUT/api/modbus/scan | python -m json.tool

⚠️ 掃描期間整台設備會「停住」約 1 分鐘 —— 那是正常的,不是當機。

停住的不只是網頁。實測(v6.0.78)單次掃描把主迴圈壓住 65 秒:

[SLOW LOOP] total=65532ms segs: ... scan=65202 ...

這 65 秒內:

• 網頁與 API 拒連 —— 收到 Connection reset by peer 或整個逾時
• 實體 I/O 不會動 —— 呼吸燈停住、DI 不被輪詢、規則不執行

它正逐一試 7 種鮑率 × 同位元 × 32 個 slave ID,而且是同步輪詢。 看門狗有逐台餵,所以不會重開(實測 bootCount 全程不變)。

因此:不要在掃描期間測按鈕,也不要因為呼吸燈停了就判定設備掛掉。 輪詢每 15 秒問一次,拒絕連線就當成「還在掃」,最長等 5 分鐘。

(這個成本已開卡追蹤 —— WI-209:掃描應切片化,或縮小預設掃描範圍, 至少 UI 按下去時要先告知「約 1 分鐘,期間設備不回應」。)

通過：輪詢結果中列出的 Slave ID 與硬體表一致。

注意回應的鍵是 devices(不是 results)—— 每一筆長這樣:{"slaveId":1,"baud":9600,"found":true,"alreadyAdded":true}。 常見誤判：POST 立刻回 {"success":true,"scanning":true} —— 那只代表「開始掃了」， 不是掃描結果。看到它就以為完成，會誤判成「一台都沒掃到」。 注意：掃到只代表「設備活著」，不代表讀得到值 —— 讀值還需要暫存器設定正確。

5.2 逐台加入 —— ⚠️ 必須用網頁新增，不能用 CLI

這一步是本文件唯一「不提供 CLI」的步驟，而且是刻意的。 型號的暫存器模板（要讀哪個位址、怎麼解讀）只存在於網頁端， 是瀏覽器幫你填好之後才送出去的。用 curl 直接 POST 會建出一台 沒有任何暫存器的設備 —— 它在清單上看得到、online 也是 true， 但永遠讀不到值，而且不會有任何錯誤訊息。

操作路徑：

設備頁 → RS485 設備 → ＋新增 →

選了型號之後，暫存器會自動帶入 —— 看到下方「自訂暫存器」清單被填滿， 才代表模板套上了。如果那個清單是空的，不要儲存，重選一次型號。

一次只加一台，加完立刻做 5.3 確認讀得到值，再加下一台。 全部加完才一起測，出問題會分不清是哪一台。

若回報 Slave ID already in use → 該 ID 已被佔用（包含閘道器自己的 slaveId），換一個。

5.3 確認讀得到值 —— 唯一可信的判準

電流計類（Finder：電壓／電流／功率是固定欄位）：

curl -s -H "Authorization: Bearer $TOK" $DUT/api/poll | python3 -c "
import sys,json
d=json.load(sys.stdin)
for p in d.get('power',[]):
    print(f\"  {p.get('name')}  online={p.get('online')}  V={p.get('voltage')}  A={p.get('current')}\")
"

計數器類（SF965：值在自訂暫存器，不在 power 陣列裡）：

curl -s -H "Authorization: Bearer $TOK" $DUT/api/modbus | python3 -c "
import sys,json
d=json.load(sys.stdin)
print('  暫存器目前值:', d.get('registers'))
"

通過：電流計 online=True 且數值合理；計數器的暫存器值會隨現場觸發而增加。 power 陣列只有電力類欄位（電壓／電流／功率），計數器的值不會出現在那裡 —— 拿電流計的指令去驗計數器，會看到一排 0 而誤判成故障。

這段指令能跑完不報錯，本身就是一項驗證 —— 若回應不是合法 JSON，Python 會直接拋錯。

分辨「沒人答」還是「答了但解不開」：

curl -s -X POST -H "Authorization: Bearer $TOK" -H "Content-Type: application/json" \
  -d '{"slaveId":4,"functionCode":3,"regAddress":0,"count":2}' $DUT/api/modbus/probe

curl.exe -s -X POST -H "Authorization: Bearer $TOK" -H "Content-Type: application/json" `
  -d '{"slaveId":4,"functionCode":3,"regAddress":0,"count":2}' $DUT/api/modbus/probe

回 0 bytes = 沒人答（線路／位址／電源）；有 byte 但解不開 = 撞號或格式錯。

5.4 現場觸發計數器，看畫面數字是否跟著跳

通過：面板顯示值與網頁顯示值一致，觸發一次就加一。這是業主最直觀的驗收點，請當場示範。 沒過：讀到 0 → 依序查接線極性 → Slave ID → 鮑率 → 該台有沒有電。數值有但對不上面板 → 型號模板選錯。

5.5 全部加完後重開設備，再確認一次

curl -s -X POST -H "Authorization: Bearer $TOK" $DUT/api/system/reboot
# 等約 60 秒後重跑 5.3

curl.exe -s -X POST -H "Authorization: Bearer $TOK" $DUT/api/system/reboot
# 等約 60 秒後重跑 5.3

通過：重開後設備清單完整、數值正常。這一步證明設定真的寫進去了，不只是畫面上有。 沒過：重開後設定不見 → 立即停止驗收並回報，不可帶病上線。

#階段 6：I/O 連動

6.1 看目前實體 I/O 狀態

curl -s -H "Authorization: Bearer $TOK" $DUT/api/io | python3 -m json.tool

curl.exe -s -H "Authorization: Bearer $TOK" $DUT/api/io | python -m json.tool

通過：看得到 di / do 陣列，現場觸發輸入時對應位置會變。

6.2 直接驅動輸出，確認實體會動（不經規則，單純驗硬體）

curl -s -X POST -H "Authorization: Bearer $TOK" -H "Content-Type: application/json" \
  -d '{"index":2,"value":true}' $DUT/api/io/do      # DO3 = index 2（0 起算）
sleep 2
curl -s -X POST -H "Authorization: Bearer $TOK" -H "Content-Type: application/json" \
  -d '{"index":2,"value":false}' $DUT/api/io/do

curl.exe -s -X POST -H "Authorization: Bearer $TOK" -H "Content-Type: application/json" `
  -d '{"index":2,"value":true}' $DUT/api/io/do      # DO3 = index 2（0 起算）
Start-Sleep 2
curl.exe -s -X POST -H "Authorization: Bearer $TOK" -H "Content-Type: application/json" `
  -d '{"index":2,"value":false}' $DUT/api/io/do

先確認硬體會動，再談規則 —— 否則規則不動時分不清是規則錯還是輸出壞。 欄位是 index／value，不是 channel／state。打錯欄位名會回 400 並附提示。

#第二部：情境驗收

前面驗的是「裝好了」，這一部驗的是照情境會動。每個情境都標註出廠測試中守著同一件事的測項編號 —— 驗收與出廠測試看的是同一組行為，不是兩套標準。

#情境 A：I/O 互動

前置：A1／A3 要驗的「規則」必須先建立。 規則不會憑空存在， 而且它需要兩個先決條件 —— 一個輸入群組、一個輸出群組。

⚠️ 你需要建【兩個】輸入群組，不是一個。 A1 要實體 DI 當來源、A2 要 MQTT 命令當來源，兩者不能共用同一個群組。下面 A.0-1 請做兩次。

A.0-1 建立輸入群組（觸發條件）

配置頁 → 📡 輸入群組 → 右上角 + → 名稱（例：按鈕1按下）→ + 加設備 → 選來源 → 設比較條件 → 儲存

按鈕叫 + 加設備，不是「新增來源」。

⚠️ 「觸發類型」這一欄決定 A1 的後半段會不會成立 —— 務必看懂再選

新增輸入群組的畫面上有一個「觸發類型」下拉，預設是 Always。它決定訊號在什麼 時機才算「觸發」，直接影響規則會不會執行：

原因在韌體的規則比對：if (rule->triggerOnTrue != signalValue) continue;。 選 Rising 時只有 signalValue == true 的那一刻會觸發，於是 觸發條件 = 信號為 False 的那條規則永遠不會被執行。

「按鈕按下」直覺上會讓人選 Rising —— 那正是這一題的陷阱。

例外：脈衝式輸入要選 Rising + 輸出用「切換」。 觸控式按鈕這類只給短脈衝（1 → 幾秒內自動回 0）的輸入，不是準位， 要搭配輸出模式「切換」才會有一按一放的效果。

A.0-2 建立輸出群組（要做什麼）

配置頁 → 輸出群組 → 右上角 + → 名稱（例：開燈1）→ + 加設備 → 選 DO 通道與動作模式 → 儲存

輸出模式：直接＝跟隨、切換＝每次觸發翻面、脈衝＝定時、關閉＝強制 OFF。

⚠️ 不要一口氣連續建立多筆。 每建好一筆，等清單重新整理出現該筆之後再建下一筆。 連續快速新增會讓前一筆被無聲覆蓋，而且兩次都回成功（見 WI-199）。

A.0-3 建立規則(把兩者綁起來)

規則頁 → 新增 →

⚠️ 兩個下拉都必須真的選到東西。 畫面會擋： 「請先選擇『觸發信號 (輸入群組)』與『執行動作 (輸出群組)』。未綁定的規則永遠不會觸發。」 若下拉是空的、顯示「請先新增輸入群組」，表示 A.0-1／A.0-2 還沒做完。

存完重新整理頁面再看一次 —— 確認兩個欄位仍顯示正確的選項，而不是又變回空白。

A1 只成功一次不算通過 —— 間歇問題只有重複才看得出來。 A3 兩個方向都要驗：「停用了還會動」= 業主以為關掉、機器卻自己跑（安全問題）；「重新啟用回不來」= 現場只能重開機碰運氣。

⚠️ A3 的假 FAIL 陷阱（Change 觸發專屬，實測踩到過）

若輸入群組的觸發類型是 Change，而你在規則停用期間已經送過一次觸發值 （例如 MQTT 送了 1），那麼重新啟用後再送一次相同的值不構成變化 → 不觸發 → 輸出不動。

這不是「重新啟用失敗」，是測試步驟本身沒有製造變化。

正確做法：重新啟用之前先把訊號送回原值（送 0），再送 1。 實體 DI 同理 —— 先把開關撥回原位再撥一次。

MQTT topic 前綴用 UID，不是設定頁顯示的那個。 設備「設定」頁的 topicPrefix 可能顯示成 mes/gateway/001 之類的短代號， 但實際訂閱／發佈用的是 UID：mes/gateway/<24 碼 UID>/...。 一律以本文件開頭的 PREFIX=mes/gateway/$UID_DEV 為準；照設定頁的顯示值發命令會石沉大海。 要確認的話，訂閱 mes/gateway/# 看設備實際發出來的 topic 長什麼樣。

#情境 M：MQTT 的三種通道模式 —— 先搞清楚差別

新增 TCP 通道、協定選 MQTT 之後，會出現一個「模式」下拉，三個選項的用途完全不同。 選錯的話畫面上不會報錯，但行為完全不是你要的。

一句話分辨： 要「有沒有發生」→ Legacy。要「是多少」→ Parser。要「送出去」→ Converter。

M.1 — Legacy 入向：收到指定訊息就觸發

目的：上位系統送一個命令，設備就動作。不關心數值是多少，只關心「這件事發生了沒」。 例：{"cmd":"start"} 一到就啟動某個輸出。

設定：配置頁 → TCP 通道 → ＋新增 → 協定 MQTT、方向 輸入、 模式 ⚡ 收取並觸發動作 (Legacy) →

mq_pub -t "$PREFIX/cmd/start" -m '{"cmd":"start"}'      # 應觸發
mq_pub -t "$PREFIX/cmd/start" -m '{"cmd":"other"}'      # 不應觸發

mq_pub -t "$PREFIX/cmd/start" -m '{"cmd":"start"}'      # 應觸發
mq_pub -t "$PREFIX/cmd/start" -m '{"cmd":"other"}'      # 不應觸發

通過：送 start → 通道狀態變成成立（總覽頁看得到，或綁規則後輸出動作）； 送 other → 完全沒有反應。 沒過：兩個都觸發 → 比對值沒填，變成「收到就觸發」。 兩個都不觸發 → JSON 欄位名打錯，或 Topic 不符（大小寫要完全一致）。

M.2 — Legacy 的「留空」語意（這是最容易誤解的地方）

# 把「比對值」清空後再送一次
mq_pub -t "$PREFIX/cmd/start" -m '{"cmd":"whatever"}'

# 把「比對值」清空後再送一次
mq_pub -t "$PREFIX/cmd/start" -m '{"cmd":"whatever"}'

通過：比對值留空時，任何內容都會觸發 —— 這是設計，不是故障。 為什麼要驗這個：現場常見「我明明設了條件，怎麼什麼都會動」， 十之八九就是比對值留空。當場示範一次，業主就懂了。

M.3 — Parser 入向：從 JSON 抽出數值

目的：上位系統送一包 JSON，設備要把其中一個數字取出來， 之後才能拿它做門檻比較（例：溫度 > 80 就報警）或塞進 Converter 發佈。

設定：新增通道 → 協定 MQTT、方向 輸入、模式 📥 收取並擷取數值 (Parser) → Topic 填 <你的 $PREFIX>/data/temp → 在解析欄位區 新增至少一個欄位 （欄位名對應 JSON 的鍵，例 temp）。

介面會擋：「請至少新增一個解析欄位。」沒新增就存不了。

mq_pub -t "$PREFIX/data/temp" -m '{"temp":25.5,"hum":60}'
sleep 3
curl -s -H "Authorization: Bearer $TOK" $DUT/api/tcpio | python3 -c "
import sys,json
for c in (json.load(sys.stdin).get('channels') or []):
    if c.get('name'): print(f\"  {c.get('name')}  目前值={c.get('currentValue')}\")
"

mq_pub -t "$PREFIX/data/temp" -m '{"temp":25.5,"hum":60}'
Start-Sleep 3
curl.exe -s -H "Authorization: Bearer $TOK" $DUT/api/tcpio | python -c "
import sys,json
for c in (json.load(sys.stdin).get('channels') or []):
    if c.get('name'): print(f\"  {c.get('name')}  目前值={c.get('currentValue')}\")
"

通過：該通道的 currentValue 變成 25.5（不是 0、不是 1）。 這是 Parser 與 Legacy 的關鍵差別 —— Legacy 只會給你「成立／不成立」， Parser 給的是真正的數字。 沒過：值一直是 0 → 解析欄位名與 JSON 的鍵不符（大小寫要一致）。 值變成 1 → 模式選成 Legacy 了。

M.4 — Parser 的數值拿去做規則判斷:能到什麼程度(這裡有一個硬限制)

#🛑 先講清楚,免得現場白試半小時

Parser 抽出來的數字,不能拿去設數值門檻。 規則引擎讀 TCP 通道時只讀它的 布林狀態(值 ≠ 0 → 成立、值 = 0 → 不成立),不比較那個數字本身。

所以「溫度 > 80 就報警」這種需求,目前這條路做不到 —— 要嘛請上位系統自己判斷後送一個 0/1 過來,要嘛走 RS485 暫存器那條路(那條支援數值門檻)。

韌體會當場擋下來,不會讓你存進一個永遠不成立的條件:

json

{"error":"condition can never be true",
 "reason":"TCP IO channel sources are boolean (0/1); the parsed numeric value is not compared",
 "hint":"use op '==' with threshold 1 to mean 'non-zero'"}

設定：配置頁 → 📡 輸入群組 → 新增 → 來源選 M.3 那個 Parser 通道 → 比較條件設 = 1(意思是「非零」)→ 儲存 → 綁一條規則到某個輸出。

mq_pub -t "$PREFIX/data/temp" -m '{"temp":0}'      # 值為 0  → 不成立
sleep 4
mq_pub -t "$PREFIX/data/temp" -m '{"temp":35.0}'   # 值非 0  → 成立
sleep 4
mq_pub -t "$PREFIX/data/temp" -m '{"temp":0}'      # 回到 0  → 復歸

mq_pub -t "$PREFIX/data/temp" -m '{"temp":0}'      # 值為 0  → 不成立
Start-Sleep 4
mq_pub -t "$PREFIX/data/temp" -m '{"temp":35.0}'   # 值非 0  → 成立
Start-Sleep 4
mq_pub -t "$PREFIX/data/temp" -m '{"temp":0}'      # 回到 0  → 復歸

通過：0 → 不成立、35 → 成立、再回 0 → 復歸。 同時 /api/tcpio 的 currentValue 要跟著變(0 → 35 → 0)—— 數值有被抽出來,只是規則只看它是不是 0。 沒過：一直不成立 → 見下方「來源要填 channelId」。

#⚠️ 兩個會讓你白忙的細節

① 來源的「index」是 channelId,不是通道在列表裡的第幾個。 用 API 建輸入群組時,sources[].index 要填 GET /api/tcpio 回傳的 channelId (例 81),填成陣列位置(1)的話會查不到通道,條件永遠不成立且沒有錯誤訊息。 走網頁介面不會踩到這個 —— 它會幫你填對。

② 來源型別要用 7(TCP 通道),不要用 9。 型別 9(CH_TCPIO)送得進去、HTTP 200、列表上看得到,但規則引擎沒有處理這個型別 —— 條件永遠不成立,而且上面那道「永遠不成立」的守衛也擋不到它(它只檢查型別 7)。 實測:型別 9 配 > 30,送 25.5 / 35.0 / 99.9 進去,訊號三次都是 False。 (已開卡 WI-196。同樣走網頁介面不會踩到。)

#情境 B：MQTT Converter —— 兩個軸，四種組合

Converter 有兩個彼此獨立的設定軸，搞混就會得到「資料太多」或「該來的沒來」。

下表格子裡的編號 = 底下對應的測試步驟編號。B3 不在這張表裡 —— 它驗的是「這個開關到底歸不歸你控制」（可逆性），跨在兩個象限之上。

先開一個終端機常駐訂閱，以下所有情境都在它上面看結果：

mq_sub -t "$PREFIX/#" -v | while read -r line; do
  echo "$(date +%H:%M:%S)  $line"
done

mq_sub -t "$PREFIX/#" -v | while read -r line; do
  echo "$(date +%H:%M:%S)  $line"
done

B1 — 電流環定期回報（持續 × 連續） ｜ 出廠對應 CV.3

目的：不論值有沒有變，每隔固定秒數都要有一筆，讓 MES 能畫連續趨勢圖、也能當「設備還活著」的心跳。此時「重複」是刻意要的。

設定路徑（介面上沒有「來源」下拉，值是用 JSON 模板的變數插進去的）：

配置頁 → TCP 通道 → ＋新增 → 協定 MQTT、方向 輸出、模式 Converter → 展開綠色「Converter 設定」區 →

⚠️ 變數的欄位名必須用英文,寫中文會靜默得到 0。

韌體 resolveRs485Field() 只認這些名稱: voltage／current／power／reactive／apparent／pf／freq／thd／kwh／kwhpos／kwhneg

中文名(例如 電流)只有在剛好等於某個自訂暫存器的名稱時才解得出來。 型號模板設備(Finder 6M、SF965 等)沒有自訂暫存器,於是解析失敗 → 靜默回 0.0。

這會產生最危險的假 PASS:訊息每 N 秒準時抵達、JSON 格式正確、topic 正確 —— 唯獨值是憑空捏造的 0.00。實測對照:

${rs485.5.電流}    → {"current":0.00}  {"current":0.00}  {"current":0.00}   ← 恆為 0
${rs485.1.current} → {"current":0.31}  {"current":0.30}  {"current":0.30}   ← 真實量測

判準:真實量測會微幅跳動,恆定的 0.00 幾乎必然是變數沒解出來。 看到整排 0.00 時,先確認欄位名與 Slave ID,不要當成「現場真的沒電流」。 | 🔁 變更時才發 | 不勾 |

變數名稱可按介面上的「📌 可用變數參考」展開查；填好後按「👁 預覽填充結果」， 看到真實數值才存 —— 預覽是空的就代表變數名錯了，存下去會發出空值。

通過：60 秒內約 12 筆，即使電流沒變也照發。 沒過：完全收不到 → 通道沒啟用，或主題字串大小寫不符。

B2 — 關掉重複資料（持續 × 不重複） ｜ 出廠對應 CV.4

目的：業主抱怨資料量太大。值沒變就不要送，資料量從「每 5 秒一筆」降到「有變化才一筆」。

設定：同一通道 → 勾選「🔁 變更時才發」 → 儲存。

⚠️ 類比量測(電流、電壓、溫度)光勾這個不會變成 0 筆 —— 必須同時設死區。

這類訊號永遠在微幅跳動,對韌體來說「值一直在變」,所以每次檢查都算變更、照發不誤。 死區的作法就是在模板變數後加小數位修飾詞:${rs485.1.current:1}。

實測(Finder 6M 電流環,實際電流約 0.3A,間隔 5 秒):

設定	65~70 秒內筆數
不勾「變更時才發」	~13 筆(每 5 秒必發)
勾了,模板 ${rs485.1.current}(2 位小數)	8 筆 — 值在 0.30/0.31/0.32 之間跳,擋不掉
勾了 + ${rs485.1.current:1}(1 位小數)	0 筆 ✅

所以開關型的數位訊號(計數、狀態)勾了就夠;類比量測一定要配死區。 先勾了發現還在發,不是壞掉,是還沒設死區。

通過：設好死區後,值不變的 60 秒內 0 筆；讓負載變動 → 立刻 1 筆。 沒過：仍持續收到相同值 → 先確認①勾的是這一個通道(這是逐通道設定)、②模板有沒有加小數位修飾詞。

B3 — ★ 證明「重複資料能再回來」（可逆性驗證）

目的：業主真正擔心的不是「現在會不會重複」，而是**「這件事到底歸不歸我控制」。 只證明「勾了就不重複」不夠 —— 那可能只是剛好值沒變。必須證明取消勾選後重複會確實回來**，才能說明這個開關真的有效、而且是唯一的控制點。

設定：取消勾選 → 觀察 60 秒 → 再勾回來 → 再觀察 60 秒。

通過：取消 → 重複資料立刻回來（約 12 筆/分）；勾回 → 再度歸零。來回兩次都符合。 沒過：取消勾選後仍然沒有資料 → 那 B2 的「0 筆」可能根本不是勾選造成的，而是通道停掉了。這一步就是為了排除這種假通過。

B4 前置 — 先建立閘門，否則送訊號不會有任何反應

發到 cmd/signal/1 只是把數值寫進韌體的一個暫存位置。要讓它真的當閘門，必須先綁定：

1. 配置頁 → 📡 輸入群組 → ＋新增 → 名稱「開工閘門」→ 新增來源 → 類別選 📨 MQTT 命令訊號 (cmd/signal) → 選 cmd/signal/1 → 比較條件 ≥ 0.5 → 儲存

⚠️ 比較條件一定要用 ≥ 0.5,不要用 = 1。 兩者在只送 0/1 時看起來一樣, 但 B5 會送 5、15 這種秒數 —— 用 = 1 的話那些值不滿足條件,閘門直接關閉, B5 會收到 0 筆而看起來像功能壞掉。走查時實際踩到過。

2. 回到 配置頁 → TCP 通道 → 點開該 Converter 通道 → 🔒 門控信號 選「開工閘門」→ 儲存

沒做這一步的話：門控欄位維持「（無門控，持續推送）」， 你送 1 送 0 都不會有任何差別 —— 而且沒有任何錯誤訊息。 這是 B4／B5／B6 全部失效的最常見原因。

B4 — MQTT Trigger 啟動 Converter（啟動式 × 連續） ｜ 出廠對應 CV.3

目的：離峰時段不佔頻寬、不產生無用資料。上位系統開工時送一個訊號才開始回報，收工再送一個就停。

mq_pub -t "$PREFIX/cmd/signal/1" -m '0'   # 閘門關
# 觀察 30 秒 → 應為 0 筆

mq_pub -t "$PREFIX/cmd/signal/1" -m '1'   # 閘門開
# 觀察 60 秒 → 應照設定間隔持續收到

mq_pub -t "$PREFIX/cmd/signal/1" -m '0'   # 閘門關
# 觀察 30 秒 → 應為 0 筆

mq_pub -t "$PREFIX/cmd/signal/1" -m '1'   # 閘門開
# 觀察 60 秒 → 應照設定間隔持續收到

沒過：閘門關著仍在發 → 閘門來源綁錯。

B4b — 啟動式 × 不重複（兩個條件是「且」的關係） ｜ 出廠對應 CV.4

目的：這是計數器最該用的組態。閘門開著時，每發生一次計數就送一筆； 停機（閘門關）或沒有新計數時，完全不送。資料量剛好等於「該回報的事件數」。

設定：在 B4 的閘門仍綁著的情況下，把該通道的 🔁 變更時才發 勾起來。

mq_pub -t "$PREFIX/cmd/signal/1" -m '1'    # 閘門開著
# 不要觸發現場設備，觀察 60 秒

通過：閘門開著但值沒變 → 0 筆；現場觸發一次讓值改變 → 立刻 1 筆； 送 0 關閉閘門後，再怎麼觸發都 0 筆。 沒過：閘門關著卻仍在發 → 門控沒綁上（回 B4 前置）。 值沒變卻一直發 → 勾選沒生效，或模板沒限小數位（見情境 C）。

B5 — 用訊號內容直接調整回報頻率 ｜ 出廠對應 WI-143

目的：不同工單需要不同取樣密度。上位系統送數字就能改頻率，不必派人進設定頁。

mq_pub -t "$PREFIX/cmd/signal/1" -m '5'    # 每 5 秒一筆
mq_pub -t "$PREFIX/cmd/signal/1" -m '0'    # 停止

mq_pub -t "$PREFIX/cmd/signal/1" -m '5'    # 每 5 秒一筆
mq_pub -t "$PREFIX/cmd/signal/1" -m '0'    # 停止

沒過：此功能需閘門來源為 MQTT 型別。不使用則標「不適用」。

B6 — ★ 重新觸發要有反應（關再開要補發） ｜ 出廠對應 CV.4

目的：操作員收工關掉、隔天開工再打開，若值剛好沒變就什麼都收不到 —— 他會以為系統壞了。所以重新打開時必須補一筆目前值。

mq_pub -t "$PREFIX/cmd/signal/1" -m '0'   # 關
sleep 10
mq_pub -t "$PREFIX/cmd/signal/1" -m '1'   # 再開（期間不要動負載）

mq_pub -t "$PREFIX/cmd/signal/1" -m '0'   # 關
Start-Sleep 10
mq_pub -t "$PREFIX/cmd/signal/1" -m '1'   # 再開（期間不要動負載）

通過：重新打開後立刻補發一筆目前值，即使值完全沒變。 沒過：不補發 → 現場最常見的抱怨來源。

CT.1 — 計數器：一次計數 = 一筆訊息

目的：計數值只有事件發生時才變，勾「🔁 變更時才發」後資料量剛好等於事件量，對帳最直觀。不勾的話停機期間會把同一個數字重發上千遍。

通過：現場觸發一次 → 面板 +1 → 網頁 +1 → 訂閱端剛好 1 筆；停止觸發後 60 秒 → 0 筆。 沒過的分辨：面板有跳、網頁沒跳 → 型號模板或 Slave ID；網頁有跳、訂閱沒收到 → Converter 通道設定。

#情境 C：本站設備該用哪一種組態

上面四格不是選擇題，是依設備特性對號入座。

編號對照:B4 是「閘門 × 不勾變更時才發」、B4b 是「閘門 × 勾選」。 B3 不是象限,它是可逆性驗證(見情境 B)。挑組態時看的是象限編號,別把 B3 當組態。

⚠️ 電流環最容易出錯的地方。 業主若說「勾了還是一直有資料」，十之八九不是勾選失效， 而是模板沒限小數位 —— 量測雜訊本身就一直讓字串改變，於是每次檢查都判定「值有變」。 Converter 判斷「有沒有變」是比對整包填好的 JSON 字串，不是數值容差，所以限小數位才是正解。 請當場觀察實際跳動幅度再決定取幾位。

#情境 D：設定值 —— 三關保證

設定「畫面上有」不等於「真的存進去了」。每一項設定都要過三關。

D1 的重點：不要相信「儲存成功」的提示，要親眼看到值。 回報成功但值沒進去，是最難察覺的失敗形式。

三關的指令：

# D1／D2 —— 存檔後讀回（D2 在瀏覽器按 F5 對照）
curl -s -H "Authorization: Bearer $TOK" $DUT/api/config | python3 -c "
import sys,json
d=json.load(sys.stdin)
print('RS485 設備:',[x['name'] for x in d.get('modbusDevices',[]) if x.get('name')])
"

# D3 —— 重開機後再跑一次上面那條，逐項比對
curl -s -X POST -H "Authorization: Bearer $TOK" $DUT/api/system/reboot

# D1／D2 —— 存檔後讀回（D2 在瀏覽器按 F5 對照）
curl.exe -s -H "Authorization: Bearer $TOK" $DUT/api/config | python -c "
import sys,json
d=json.load(sys.stdin)
print('RS485 設備:',[x['name'] for x in d.get('modbusDevices',[]) if x.get('name')])
"

# D3 —— 重開機後再跑一次上面那條，逐項比對
curl.exe -s -X POST -H "Authorization: Bearer $TOK" $DUT/api/system/reboot

⚠️ 設備清單在 /api/config 的 modbusDevices，不是 /api/modbus-devices。 後者回的是匯流排狀態（mode／baudRate／…），沒有設備清單 —— 用錯會看到「0 台」而誤判設定不見了。

#自動化整批驗證

#🤖 先跑 acceptance_run.py —— 人工驗收之前的前置

bash

python3 scripts/acceptance_run.py --dut http://<設備IP> --token <admin token>
python3 scripts/acceptance_run.py --skip-reboot     # 不想讓它重開設備時

這支把本文件所有可自動化的測項串成一次不中斷的執行: 階段 0 / 2B.2 / 3 / 4 / 5 / 6、情境 M(M.1–M.4)、情境 B(B1–B6)、情境 D(D1–D3)、階段 8.1。 任何一項失敗就整體失敗,而且它不做任何修復 —— 工作是如實回報,不是把問題藏起來。

素材一律 AC- 前綴、測完自清,結束前會驗證設備回到起始狀態。約 13 分鐘。

為什麼要有它:2026-08-26 的走查是散在幾十次互動裡邊跑邊修完成的, 記錄裡還有「先失敗後修好」的項目 —— 那證明不了「這套流程能不中斷地走完」。 業主人工驗收之前,必須先有一次從頭到尾、單一韌體版本、沒有中途修東西的乾淨通過。

它不涵蓋(本質上需要人):0.1 供電接地目視、階段 R 歸零(破壞性)、 階段 1 空機燒拓荒包、情境 A.1 實體撥開關、5.4 現場觸發計數器、 階段 7 實體斷電、8.2 拍照、8.3 簽名。這些仍要照本文件人工執行。

情境逐項驗完後，跑一次自動化閘門收尾：

這份驗收單與出廠測試是對齊的。 每個情境的「出廠對應」欄位指向出廠測試規範 (內部文件 docs/testing/qa-factory-test.md)的測項編號(CV.* / EN.* / ST.*)—— 兩邊看的是同一組行為,不是兩套標準。

本走查(2026-08-25/26)挖到的缺陷,已固化成 npm run test:regression (RG.1–RG.7)。2026-08-27 起七項全數綠燈,已併進 test:gate:full。 對應的產品缺陷(WI-199/200/202/203/205/206)都已修進韌體 6.0.74。

RG.5 會重開設備,預設略過;要跑帶 RG_ALLOW_REBOOT=1。已於 2026-08-27 單獨驗過。

⚠️ 順帶提醒:當時實驗證明過,舊版閘門在缺陷存在時仍然全綠 (注入 WI-202 的壞值讓整份 TCP IO 設定在網頁上消失,factory-pages 依舊 6/6 通過)。 閘門全綠不等於沒問題 —— 這也是為什麼要有人照著這份單子實際走一遍。

cd <專案>/web
EXPECT_FW=<版本> DUT_URL=$DUT ADMIN_TOKEN=$TOK npm run test:gate

cd <專案>\web
EXPECT_FW=<版本> DUT_URL=$DUT ADMIN_TOKEN=$TOK npm run test:gate

35 項，約 2 分鐘。全數通過才算通過。

⚠️ 在客戶現場跑之前先讀這段：

• ST.14 預設期待「Finder slave 1 + 1 個擴充模組」（那是我們實驗室的組態）。 本站硬體不同的話這項一定會紅，那不是設備的問題。 請改帶本站的實際組態：EXPECT_RS485='<slaveId>:<型號>:<名稱>' EXPECT_EXPANSIONS=<數量>， 或先跳過 ST.14 再單獨人工確認。
• 它不是嚴格唯讀 —— 過程中會寫入 deviceName 再還原。 正常跑完不留痕跡，但中途 Ctrl-C 中斷會在設備上留下測試值， 中斷後請回頭確認設備名稱是否正確。

#階段 7：斷電復原 —— 業主最該在意的一段

現場一定會停電。這一段驗的是「電回來以後，它會不會自己回到工作狀態」，不需要任何人到場。

「MQTT 自行恢復」不能用「送一個命令看它動不動」草率驗過。 走查時實際踩到: 送 cmd/signal/1 = 1 想看燈亮 —— 但燈送之前就已經是亮的(WI-161 會在重開後 還原閘門狀態,規則重新觸發),送完還是亮,這個測試什麼都沒證明。

正確做法是製造狀態轉換,而且雙向:

bash

mq_pub -t "$PREFIX/cmd/signal/1" -m '0'   # 觀察輸出應【關閉】
mq_pub -t "$PREFIX/cmd/signal/1" -m '1'   # 觀察輸出應【開啟】

出向則要看到新鮮訊息:訂閱 $PREFIX/#,連線瞬間湧入的那批是 broker 的 retained 舊訊息,不算數;要等到幾秒後才抵達的那一筆(例如 cmd/_ping)才證明 設備現在真的在發。走查實測:連線當下 6 筆 retained,16 秒後才收到一筆現發的 ping。

#階段 8：結案

#現場排錯速查

#文件修訂紀錄