#v6.0.83 — 2026-08-28 — WI-211b 通知改 QoS 0 + 週期重發兜底 + 壓制窗 1 秒

v6.0.82 上機後業主回報「進步很多,只卡了一次」。追那一次:

t=49817  ⛔ 卡 1009ms  最大段 mqtt=1007ms   ← 先卡
t=49818  🔌 MQTT 重新連線                    ← 才斷線

1007ms 這個數字在先前多份 log 裡反覆出現(1006/1007/1008)—— 又是固定逾時的指紋。 翻函式庫:MQTTClient.h:75 uint32_t timeout = 1000;。

真因是網路延遲,不是爆發:QoS 1 每則發送都要等 broker 回 PUBACK,broker 在 網際網路上,只要那一秒剛好塞車、ack 沒回來 → 函式庫判定失敗 → 連線被當成死的 → 重連。 佇列沒滿、合併正常運作 —— 這一次純粹是外部延遲。

#業主的提案與最終決定

業主問:「採取 QoS 0,然後發送的時候發兩次呢?」

發兩次幫助有限 —— 兩份相隔幾毫秒的複本會一起死在同一條斷掉的連線上, 而連線斷掉正是 QoS 0 唯一會發生的遺失情境。它擋不到唯一會發生的那種遺失, 卻讓通知量與主迴圈阻塞加倍。

正解是週期重發現況:涵蓋所有遺失原因,成本每分鐘一則,而且給下游一個 有界的過時上限 —— 那才是能寫進合約的東西。業主採納。

#三個改動

1. rules/*/trigger 改 QoS 0 —— 沒有 ack 要等,1 秒逾時的故障模式直接消失。 對一個設計上就可丟的通知(設備已刻意合併中間值),付 ack 的代價換保證本身就不一致。
2. 週期重發:每 60 秒把每個狀態類 topic 的現況原樣重送一次(期間有更新則不重送)。 已被週期推送的資料(RS485 值)會不斷刷新時間戳,自然不會觸發 —— 機制自我調節。
3. 壓制窗 500ms → 1000ms:發送次數再減半。

另修:訂閱的日誌誤印成發送 QoS(Subscribed to ... (QoS 1))—— 實際訂閱用的一直是 subQos(=2,正確),只是 v6.0.82 做變數改名時把那行的變數換錯了。行為無誤,日誌誤導。

#實測(同一台 .77,30 個事件 5 秒內)

週期重發實測:最後一次發送的 +66 秒,兩個 topic 的現況都自動重送。

#v6.0.82 — 2026-08-27 — WI-210/211 快速切換打掉 MQTT:QoS 配合語意 + 同 topic 合併 + payload 夾帶歷史

業主人工驗收時快速切換 Toggle 開關十幾次,呼吸燈進入快閃(=MQTT 斷線中,不是重開)。 追下去是一條完整的故障鏈:每條規則觸發都發一則通知 → 邊緣模式不節流 → 灌爆 16 格佇列 → 每則 TLS 發送阻塞主迴圈 265400ms → 連線撐不住 → 重連風暴(握手 1.64.4 秒且逐次變長) → 若持續約 90 秒,self-ping 連兩次無 echo → 設備自我重開。

同一個故障鏈 main.cpp:2620 的註解已描述並修過一半 —— 但只節流位準模式, 明確寫著「邊緣觸發不節流,每個事件都有意義不可丟」。那句是破口:對慢速事件成立, 但人手快切或現場抖動的接點的邊緣密度足以複製同一個故障(本站 debounceMs=0)。

業主定下的原則:「控制是現場的問題,訊息可以晚到。」 依此重做發送路徑。

#一、QoS 配合資料語意(最大的槓桿)

defaultQos 寫死 2,而 setDefaultQos() 全庫從來沒有人呼叫過 —— config.mqtt.qos 早就有欄位、有存檔、Converter 也在用,就是沒接到管理器上。

發出去的絕大多數是「最後狀態」:重複送達會被下一筆覆蓋,無害 —— 需要的是「一定會到」,不是「恰好一次」。用 QoS 2 等於付兩趟往返買一個用不到的保證。

→ 發送預設 QoS 1、訂閱維持 QoS 2(命令不可重複執行),兩者皆可在網頁設定。

#二、同 topic 合併 + 每 topic 最小發送間隔 500ms

同一個 topic 還在佇列裡就直接取代,並移到隊尾 —— 移到隊尾是關鍵: 狀態由「哪個 topic 最後更新」表達,原地取代會讓先進佇列的舊 topic 晚於後更新的送出, 下游停在錯的最終狀態。

最小間隔同樣必要:沒有它,drainQueue() 每 50ms 排空,佇列永遠只有 0~1 筆, 「同 topic 取代」等於不存在 —— 實測 20 則全數飛出,零合併。

單次變化不受影響(該 topic 若 500ms 內沒送過就立刻送),只有連續變化才被壓。

#三、payload 夾帶歷史(opt-in,預設關)

{"v":"A2-MQTT滅","t":1787839126,"h":[[354,"A2-MQTT滅"]]}

v=最後狀態、t=本批起點 epoch 秒(0=時鐘未同步)、h=[相對毫秒, 當時狀態]。 每筆帶時間與狀態。用相對毫秒 + 單一絕對錨點,是因為 payload 硬上限 128 bytes, 且時鐘未同步時仍要可用。超過 8 筆標 trunc:true,誠實告知不完整。

合併因此從有損變無損 —— 中間過程不是丟掉,是換個位置帶走。 預設關閉:開啟會把 payload 從裸值變 JSON,既有解析端會爆。升級不會自動開啟。

#實測(同一台 .77,30 個事件 5 秒內)

#量測方法踩到的兩個坑

• 用 mosquitto_pub 逐次呼叫做「爆發」是假的:每次都是新行程 + 完整 TLS 握手, 實際只有 2~3 則/秒,比壓制窗還慢,合併根本不會被觸發。要用 -l 單一連線連續送。
• 先前用 QoS 2 進向做壓力測試,測到的是進向握手成本,不是出向通知成本 —— 業主的情境是純出向(撥開關),兩者不可混為一談。

另:MQTT 設定改為每 3 秒收斂到管理器。原本只在建立連線時套用, 使用者在網頁改了 QoS 或歷史夾帶卻沒重連,設定永遠不生效(實測踩到)。

#v6.0.79 — 2026-08-27 — WI-208b 雲端每次心跳重送舊授權,設備每次白驗簽兩次

業主在 v6.0.78 上回報「呼吸燈大概 115 次會卡一次」。心跳燈每 500ms 翻一次 (一次呼吸 = 1 秒),所以那是約 115 秒一次 —— 對得上雲端心跳的 127 秒週期。

實測把每次卡頓與 log 事件對起來,關聯性零例外:

t=3019 ☁️ CS-Cloud Connecting → t=3029 📜 license/state rejected → t=3029 ⛔ 卡 1334ms
t=3146 ☁️                     → t=3153 📜                        → t=3153 ⛔ 卡 1340ms
t=3341 ☁️                     → t=3350 📜                        → t=3350 ⛔ 卡 1341ms
t=3407 ☁️                     → t=3414 📜                        → t=3414 ⛔ 卡 1338ms

因果鏈:設備心跳連雲端 → 雲端回頭發一則 license/state → 該 token 序號固定 (tokenId=1786621672)且永遠被判 stale 丟掉 → 但丟掉之前付了兩次驗簽: licenseTokenAcceptAndStore() 驗一次(663ms),它內部為了讀「既有序號」呼叫 licenseTokenStoredTokenId() 又完整驗簽一次(663ms)—— 只為了取 4 個 byte。 663 × 2 = 1326ms,與實測的 1330ms 完全吻合。

三項修正:

1. 收訊前先看序號,不新就不驗。新增 licenseTokenPeekTokenId(),只解析標頭、 零密碼學運算。序號不比手上的新 → 驗了也是拒,直接丟。
2. 既有序號改用快取(licenseTokenStoredTokenIdCached())。序號只在存入新 token 時改變,沒有理由每次重算。
3. 只有真的存了新 token 才重評門控。原本無條件 invalidate + refresh, 等於每則被拒的訊息再多付一次驗簽。

⚠️ 同時修掉一個 v6.0.78 引入的正確性 bug:WI-208 的三個快取變數被寫成 header 裡的 static —— 那是「每個 .cpp 各一份」,而 licenseGateInvalidate() / licenseGateRefresh() 是 inline(外部連結),連結器只留一份定義並綁到其中一個 .cpp 的變數。結果兩者可能在動不同的變數:實測 v6.0.78 收到 license/state 後 明明呼叫了 invalidate,卻完全沒有重驗。 那不只是效能問題 —— 存入新 token 後門控不會重新評估,撤銷授權會延遲到重開才生效。 改為 extern + 在 main.cpp 定義(比照同檔既有的 g_licenseEnforce)。 教訓:header 裡的 static 配 inline 函式,是 ODR 陷阱。

實測(v6.0.79,544 秒觀測窗、涵蓋 8 次雲端心跳):

net 卡頓 0 次 → 0.00%
[WI-145] license/state 略過(序號不新,未驗簽) tokenId=1786621672 已存=1786621672

主迴圈凍結的完整歷程:6.8%(v6.0.74)→ 1.7%(v6.0.78)→ 0.00%(v6.0.79,net 段)。 /api/license 全程 status=ACTIVE, licensed=true。

根因仍在雲端:publishLicenseState 每次心跳都重送一則設備早就拒絕過的舊 token。 設備端現在擋得很便宜,但雲端不該一直發。已記在 WI-208 卡上,未修。

#v6.0.78 — 2026-08-27 — WI-208 授權門控每 30 秒凍結主迴圈 663ms(＋WI-207 語系鍵)

業主回報「藍色呼吸燈會卡住,卡住的時候按鈕就延遲、甚至沒反應」。用 WI-163 的段別儀器 量了 210 秒:net 段卡頓 15 次、合計 14.4 秒 —— 主迴圈有 6.8% 的時間完全凍結, 期間呼吸燈不更新、DI 不被輪詢,實體按鈕的動作就這樣被吃掉。卡頓時長只有兩種且極度規律 (661~671ms / 約 2050ms),是固定成本的指紋而非負載。

net 段裡有兩個 30 秒任務且在同一輪迭代,靠時間軸分不開,故先上臨時儀器各自量測:

lic=659/665/663/662ms   ← licenseGateRefresh()
wifiStat=0ms            ← 診斷用 WiFi.status()
failoverStatMax=0ms     ← 沒有時間閘門、每 loop 都戳的那個

兩處 WiFi.status() 都是 0ms —— 原本最被懷疑的它是無罪的(程式碼裡那段註解描述的是 已經修好的舊病)。再拆一層:load=1ms verify=663ms,成本全在驗簽。

修正:門控 verdict 是 (token 內容, hwUid, nowSec) 的純函式。前兩者只在存 token 時改變 (那些路徑改為呼叫 licenseGateInvalidate() 強制重驗),nowSec 只能讓「未到期」翻成 「到期」。因此改為到期驅動 —— 只在「還沒驗過」或「先前有效且已跨過 expiresAt」時 才真的重驗;到期/簽錯/UID 錯都是終局,標記後不再重算。NTP 首次同步成功時一併失效快取, 避免「校時前誤判到期並鎖死」。

⚠️ 第一版(未出版的 6.0.76)完全沒生效:本站是永久授權(expiresAt=0), 而判斷式寫成 nowSec < expiresAt → nowSec < 0 永不成立 → 照樣每 30 秒重驗。 expiresAt == 0 的語意是「永不到期」,韌體原本的算式 (out.expiresAt != 0 && ...)早就寫明了。終局判定補上這條才真正生效。

實測:主迴圈凍結 6.8% → 約 0.8%(net 段),665ms/30s 的卡頓完全消失, /api/license 仍為 status=ACTIVE, licensed=true。

同版順帶修掉 WI-207:io.saving 這個 i18n 鍵三個語系檔全缺,而 t() 查不到時回傳 鍵本身(truthy),讓 || "儲存中" 這個 fallback 變成死碼 —— 存檔佇列徽章因此顯示 「💾 bH 1」而不是「💾 儲存中 1」。三份語系檔補齊,實機確認已對到「儲存中」。

尚未解決:net 段仍有約 1.3 秒的偶發卡頓,與對外 TLS([CS-Cloud] Connecting) 同時發生,屬「對外連線在主迴圈裡做」的老家族,要動架構才能根治。

#v6.0.74 — 2026-08-26 — WI-197 回復重開的標記寫錯方向

intentReset() 在有線回復路徑上標的是 net-failover —— 但那次重開是「WiFi → 有線」, 與 failover 的「有線 → WiFi」方向相反。同一台設備連續兩次相鄰重開因此標記相同, 事後看 bootDetail 分不出它是掉線還是恢復。v6.0.1 建 BKPSRAM intent marker 的初衷, 正是因為 Opta(MCUboot)開機前會清掉 RCC->RSR、硬體 reset 旗標救不回來,只能靠自己 留字條 —— 字條寫錯方向,這個機制在這條路徑上就等於白做。回復路徑改標 net-recovery。 全庫三處寫入該字串,另兩處(452/472)是名副其實的 failover,不動;確認無任何地方解析 這個字串,改名安全。

#v6.0.73 — 2026-08-26 — WI-206 Parser「值類型」下拉三個選項全部對錯韌體列舉

韌體 ParserValueType 是 BOOL=0 / NUMBER=1 / STRING=2,而網頁下拉是 0=數值 / 1=字串 / 2=布林 —— 三個都錯,沒有一個對。使用者選「數值」送出 0, 韌體當成布林,任何非零數字都變成 1.0。而 Parser 的主要用途就是抽數值、 新增解析欄位的預設 type 又正好是 0 —— 不動下拉、直接用預設的人一定中獎。 拿到的 1.0 看起來像個正常的值、不會報錯,後續拿去做門檻比較或塞進 Converter 發佈, 送出去的就是一串恆為 1 的假資料。

修的是前端不是韌體列舉:parserType 是已落盤的持久化契約,改列舉會讓既有設備上 已存的值被重新解讀成別的型別。同時把新增解析欄位的預設由布林改為數值。 遷移影響:既有通道行為不變,但畫面顯示的型別會變成它一直在做的那個 —— 升級後請回頭檢查 Parser 通道的型別設定。

#v6.0.72 — 2026-08-26 — WI-200 直接控制 API 涵蓋擴充板輸出(順帶修好一個從沒被測到的舊 bug)

POST /api/io/do 舊碼只認主機 DO 0-3,送擴充板一律回 Invalid index —— 但規則引擎 明明驅動得了擴充輸出。同一個能力規則路徑有、直接控制的 API 沒有,出廠測試與現場調機 想單獨點一路擴充輸出只能繞道「改輸出群組 → 借規則 → 發 MQTT → 再改回去」。 現在接受擴充 index(16+ch / 32+ch…),錯誤訊息附合法範圍,模組不在時明確報錯。

順帶:沿用共用的 modbusTcpWriteDO() 時發現它的擴充分支本身是壞的 —— auto ext = OptaController.getExpansion(i); (DigitalExpansion*)&ext 是對區域暫存副本 取址再向下轉型。也就是說 Modbus TCP 寫擴充輸出一直沒有作用,而且從沒被任何測項 涵蓋到。規則引擎那份用的是 getExpansionPtr(實測會動),兩份實作走樣多時。 統一成已驗證有效的那條路 —— 這也修好了 Modbus TCP 那一側。

#v6.0.71 — 2026-08-26 — WI-203 存 Converter 模板後長度一併落盤

saveTemplate() 把模板文字 fwrite 進 /cfg/tmpl/{idx}.json(立刻落地),同時更新 config 的 converterTemplateLen —— 但只在記憶體,沒有 setConfigDirty()。 長度要靠之後某次別的設定存檔順帶刷進去;而網頁的儲存順序是先 POST /api/tcpio (會刷盤)、再 POST /api/converter/template,剛好讓長度更新落在刷盤之後 → 重開後讀回舊值。舊值若恰好是 0,GET /api/tcpio 的內聯模板匯出(WI-133,供跨機 複製整組帶走換算公式)會變成空字串,而檔案裡明明有內容 —— 靜默遺失公式。

#v6.0.70 — 2026-08-26 — 三個「回應說一套、實際做另一套」的缺陷

WI-205(高,破壞性)— 被拒絕的規則 POST 會毀掉既有規則 POST /api/rules 的解析直接寫進 config->rules[idx],WI-174 守衛在解析之後才檢查 並回 400,而且不回滾。舊碼的緩解只有 if (idx >= config->ruleCount) rule->enabled = false; —— 只涵蓋新槽位。覆蓋既有規則時既不回滾也不停用,結果:一個回 400 的請求把使用者 原本的規則銷毀,並留下一條 sig=0/act=0 卻 enabled=true 的死規則。使用者收到 400 會合理推論「我的操作沒生效」—— 實際上它生效了,而且是破壞性的。 修法:進 handler 時整份備份,拒絕路徑完整還原。拒絕就是什麼都沒發生。

WI-202(高)— 一個引號讓整頁設定人間蒸發 22 處使用者可編輯的字串欄位未做 JSON 跳脫。名稱或設定值裡出現一個 ",整包 API 回應 就變成不合法 JSON,網頁 JSON.parse 失敗後靜默 render 成空清單 —— 使用者看到 「尚無 TCP IO 通道」,以為自己沒有設定過。HTTP 仍是 200,畫面上沒有任何錯誤。 含 WiFi SSID、MQTT 設定、規則與群組名稱、TCP IO 各欄位。 currentStrValue 的值來自進來的 MQTT payload —— 任何能發訊息到該設備訂閱 topic 的人,payload 帶一個引號就能讓設定頁消失。 寫入端同步修:parseStr 用 indexOf("\"") 找「下一個引號」、不認跳脫,值含引號就被 截斷在跳脫序列中間(實測壞資料 {\ 正是如此)。新增 jsonExtractString()。 讀寫兩端是一對,只修一邊都不夠。

這個跳脫 helper 是 WI-191 為了同一種事故建立的(/api/poll 設備名被截斷 → 整頁數值消失)。專案已經吃過一模一樣的虧、修好了一處,兄弟端點卻從沒跟上。

WI-199(中高)— 連續快速新增規則會靜默覆蓋前一條 saveRule 在 save mutex 外用本地快取 rules.length 算新規則 index,而存檔後的 loadRules() 沒有 await、不在 mutex 內。連續新增時第二次在第一次的刷新回來之前 取得 mutex → 算出同一個 index → 第二條覆蓋第一條,兩次都回 200。 修法:index 改在 mutex 內、await loadRules() 之後才算;刷新也改成 await。 saveGroup 同源一併修。

#v6.0.69 — 2026-08-25 — WI-193 插線不自動切回有線 / WI-194 恢復原廠後雲端還原被 401 擋掉

兩個缺陷都是「同一個保護只做在部分路徑上」,而漏掉的那條剛好是現場最常見的。

WI-193 — AUTO 模式「開機時就沒線」不會進入有線回復監看 interfaceMode=AUTO 的註解是「有線優先 + WiFi 備援」,但介面選擇只在 NetworkStateManager::initializeNetwork() 跑一次。執行期的 failover 狀態機確實寫了 回切有線的路(FO_WIFI_ACTIVE → FO_RECOVERY_PENDING → 重開走 Ethernet),但唯一入口 enterRecoveryMonitoring() 只在 if (isFailoverBoot) 下被呼叫 —— 也就是只認 「曾在有線上、線被拔掉 → 重開」那一條。開機時就沒插線而 fallback 到 WiFi 的機器 不設旗標,_foState 停在 FO_IDLE,而 FO_IDLE 的監看條件是 _activeNetwork==NET_ETHERNET —— 跑在 WiFi 上永遠不成立。實測:插上網路線 11.8 小時完全無反應,人工重開才切過去。 修法:啟用條件改成守性質 —— 「AUTO 模式且現在跑在 WiFi 上」。WIFI_ONLY 與 AP 模式排除。

WI-194 — 恢復原廠之後,雲端還原永遠失敗且無聲 L2 恢復原廠會把 cloudToken 清成空字串,而 downloadConfigFrom() 在 token 為空時 不送 Authorization,雲端該端點要求授權 → 401。雲端那側一切正常(rollback 回 success、pendingCommand 送達並被消耗),於是「後台顯示還原成功、設備什麼都沒做、 兩邊都沒有錯誤提示」—— 而且正好命中人最需要還原的那一刻。 推送與心跳早就有「token 空就改用 licenseId」的 fallback,只有下載漏掉。 修法:補上同一段 fallback(雲端 middleware/auth.js 本來就接受 license token,不需改); 下載失敗改印出目標與 HTTP 狀態碼,401 額外提示去填 Cloud Token。

同時發現、尚未修(已開卡):

• WI-195 — autoPush 會在數秒內覆蓋掉雲端剛寫入的還原,使還原變成無效操作。
• 發佈程序文件的 .mesb 資產清單漏了 log.html.gz(實際應為 8 個),已更正。
• L2 恢復原廠會連 QSPI 網頁資產一起清掉,設備只剩「資產救援」頁 —— 已寫進驗收單 §R.4。

#v6.0.68 — 2026-08-21 — WI-192 WiFi 連上卻沒拿到 IP(0.0.0.0)的有上限自救

設備開機快於上游網路就緒時,會連上 WiFi 但拿不到 DHCP,停在 0.0.0.0 不會自己恢復。 加入偵測與自救重開。第一版節奏設計錯誤 —— 會剛好在 router 準備好的那一刻放棄, 改為 5 分鐘首次寬限 + 加倍退避 + 移除次數上限。

#v6.0.67 — 2026-08-21 — WI-191 JSON 字串未跳脫,一個壞名稱會讓整個畫面空白

設備名稱/通道名稱等自由文字未做 JSON 跳脫,含有引號或反斜線的名稱會產出不合法 JSON, 前端解析失敗 → 整頁空白。修:輸出前一律跳脫。

#v6.0.66 — 2026-08-21 — WI-190 存檔序列化不完整會把設定連同備份一起毀掉

現場事故(2026-08-20 22:05:18,序列埠 log 完整記錄): 設定檔從 6332 bytes 變成 2108 bytes,主檔與備份在同一秒被同一份殘缺內容填滿, 設備等同回到無設定狀態 —— 隔天現場 RS485 四台掃描得到卻一台都讀不到值,因為 「已設定的設備」是 0 台。

失效機制: ArduinoJson v7 的 JsonDocument 記憶體不足時不會報錯,只是裝不下。 serializeJson 仍吐出格式完全合法、CRC 完全正確的 JSON,只是內容少一大半。 於是它通過了下游每一道檢查 —— configJsonIsValid() 只驗格式與 CRC,不驗完整性。 接著「備份不可用 → 用本次內容重建」把唯一的好備份也覆蓋掉,救援路徑自我摧毀。 WI-180b 的兩道防護前後矛盾:上一行才判定「主檔內容不完整」,下一行就拿同一份內容重建備份。

修正:

1. 存檔前對帳 —— doc.overflowed() 加上「宣告數量 vs 實際寫出筆數」比對(rules/actions/tokens)。 對不上就拒絕存檔,主檔與備份都不動。 取捨:不存 → 這次修改沒生效,使用者會發現;存下去 → 設定全毀,沒有人會發現。
2. 重建備份前先驗證新內容本身;沒過就不重建 —— 壞的備份仍勝過用壞內容覆蓋。

教訓:「格式正確」不等於「內容完整」。 唯一可靠的判準是拿序列化結果跟記憶體裡 真正持有的數量對帳。

#韌體 Changelog 指南（WI-114）

從 cloud server 5.9.50 起，每次上傳韌體都必須夾帶 changelog。 沒帶或太短（< 10 chars）會被 cloud 直接 400 拒絕。 設計目的：避免 manifest / git log / wiki 等多處紀錄碎片化。

#為什麼這樣設計？

單一來源原則：

release_firmware.py        →    Upload API (header)    →    Cloud Manifest    →    Admin UI
  --changelog ...               X-Firmware-Changelog-B64    firmware.json          顯示
  (or auto-git-log)             (base64-encoded UTF-8)      changelog field         /api/firmware

• 唯一寫入點 = release_firmware.py
• 唯一儲存 = cloud /app/firmware/<version>.json manifest 的 changelog 欄位
• 唯一顯示 = admin UI 韌體列表展開
• 不維護獨立 markdown / wiki / git 抓取（會跟 manifest 不同步）

#三種使用方式

#A) 直接字串（單行 / 短描述）

python3 scripts/release_firmware.py --bump patch --upload https://opta.smms.com.tw \
  --changelog "WI-114: 強制 changelog upload + admin UI 展開"

#B) 從檔案讀（多行 markdown）

最推薦的方式 — CHANGELOG.md 跟 commit 一起入 git：

# 寫一個 CHANGELOG.md（隨手寫，Markdown 格式）
cat > CHANGELOG.md <<EOF
## v5.9.50 — 2026-05-05

### Features
- WI-114: Cloud changelog 強制夾帶（單一來源防碎片化）
- Cloud admin UI 韌體列表加展開區塊

### Bug Fixes
- 修正 X-Firmware-Changelog header 多行字元編碼

### 升級注意
- 新版 cloud 拒絕沒 changelog 的 upload
EOF

# 用 @ 字首把檔讀進去
python3 scripts/release_firmware.py --bump patch --upload https://opta.smms.com.tw \
  --changelog @CHANGELOG.md

#C) 從 stdin 讀（CI / pipe）

git log v5.9.49..HEAD --pretty='- %s' --no-merges \
  | python3 scripts/release_firmware.py --bump patch --upload https://opta.smms.com.tw \
      --changelog @-

#D) 自動從 git log 產生（沒帶 --changelog 時）

python3 scripts/release_firmware.py --bump patch --upload https://opta.smms.com.tw
# 不帶 --changelog 時：
#   1. 嘗試 `git log v<prev>..HEAD --pretty='- %s' --no-merges`
#   2. 若 v<prev> tag 不存在，fallback 到最近 5 個 commits
#   3. 全部失敗 → 互動式 prompt 強制要求輸入

#編寫慣例（建議）

不強制，但 admin 看 changelog 時的可讀性很重要：

## v<version> — <YYYY-MM-DD>

### Features
- WI-XXX: short description
- 關鍵新功能或 endpoint

### Bug Fixes
- 修了什麼

### 升級注意 / Breaking Changes
- 客戶端需要做什麼動作（重 login？重新校時？）

### 內部變更
- refactor / 文件 / 工具

### Deploy notes
- ⚠️ Cloud 需要重啟 docker container？
- ⚠️ 此版本之後不允許降級？

對應「升級注意」段落，下次可考慮在 manifest 加 breakingChanges: bool 讓 admin UI 標紅醒目（sprint-28 候選）

#Cloud API 變動（v5.9.50+）

#POST /api/firmware/upload

新 header（推薦）：

X-Firmware-Changelog-B64: <base64-encoded UTF-8 string>

• 支援多行（\n）+ 中文 / 日文 / 任何 UTF-8
• 解碼後 trim 至少 10 字元

舊 header（向後相容）：

X-Firmware-Changelog: <plain string, URL-encoded>

• 適合單行短描述
• 不建議帶 newline / CJK

400 失敗回應：

{
  "error": "Changelog required",
  "message": "Send X-Firmware-Changelog-B64 (base64 UTF-8, recommended for multi-line/CJK) or X-Firmware-Changelog header. Min 10 chars after decode.",
  "examples": {
    "base64": "echo -n \"WI-114: bug fixes\" | base64",
    "cli": "release_firmware.py --changelog \"...\" or --changelog @CHANGELOG.md"
  }
}

#GET /api/firmware

回傳列表，每筆含完整 changelog 欄位（可能多行 UTF-8）。

#既有韌體（5.9.49 以前）

Backfill 一次性處理：在 cloud 升 5.9.50 之前，sprint-27 已執行：

// 對 changelog 缺失或太短的 manifest 補上
m.changelog = "(legacy, no changelog record — see git log v5.9.X)";

4 筆被補（5.9.8 / 5.9.40 / 5.9.41 / 5.9.42），其餘 9 筆原本就有有意義的 changelog。

Admin UI 對 (legacy 開頭的 changelog 顯示為灰色斜體，方便辨識

#Troubleshooting

#Q1: release_firmware.py 沒帶 --changelog，又沒 git tag？

腳本順序：

1. git log v<prev>..HEAD — 嘗試找 prev tag（沒有 tag 表示沒打 release tag）
2. 若失敗，fallback git log HEAD~5..HEAD
3. 若仍失敗（lab 機器沒 git），互動式 prompt 強制輸入

如果連互動式 prompt 也沒人輸入，最終 sys.exit(1) — 不會白編譯 + 丟個沒記錄的 binary 上去。

#Q2: 我已經 build 好 .bin 了，可以直接 curl upload 嗎？

可以，但要自己處理 base64：

CHANGELOG=$(cat CHANGELOG.md | base64)
curl -X POST https://opta.smms.com.tw/api/firmware/upload \
  -H "Authorization: Bearer admin-token" \
  -H "Content-Type: application/octet-stream" \
  -H "X-Firmware-Version: 5.9.50" \
  -H "X-Firmware-Changelog-B64: $CHANGELOG" \
  --data-binary @release/mes-gateway-v5.9.50-20260505.bin

#Q3: Changelog 改完了想覆寫 manifest？

目前沒 PUT/PATCH endpoint。兩種選擇：

• 直接 SSH 到 cloud 改 /app/firmware/<version>.json（admin 可做）
• 重新跑 release_firmware.py（會以新時間戳產出新 .bin，舊的還在）

未來如果有需求，可以加 PATCH /api/admin/firmware/:filename/changelog endpoint（sprint-28 候選）

#Q4: changelog 欄位 size 上限？

Cloud server 沒設限（manifest JSON 寫多大都可以）。實務上保持在 5KB 內，admin UI 才好看。

#近期版本重點（v6.0.41 ~ v6.0.65 — 穩定性補強與「靜默失敗」清剿）

這一段的主題可以用一句話概括:把「回成功但其實沒發生」的路徑一條條堵掉。 這類缺陷比功能壞掉更難查 —— 畫面正常、API 回 200,只有行為不對。

#韌性 / 不再自己把自己弄死

#靜默失敗清剿

#網頁 / 使用者體驗

#⚠ 已知特性(非缺陷,但要讓業主知道)

• 控制延遲:典型 < 200 ms,但 p99 約 2~3 秒(實測極值 3.7 秒),每分鐘都會發生。 成因是單核單迴圈 + 主迴圈裡的阻塞式 TLS。詳見 docs/testing/qa-latency-characteristics.md
• 還原舊快照會帶回當時的 cloudToken:若那份快照的 token 為空,雲端備份會變成 「推得出去、讀不回來」。畫面有明確提示,出廠測試 ST.15 / BK.3 會攔截

#近期版本重點（v6.0.37 ~ v6.0.40 — 主迴圈卡死時，記下「卡在哪一段」）

🟡 影響範圍:診斷能力為主;v6.0.38 另含一項 HTTP 解析的穩定性修正。 一般使用者不會看到行為差異,但設備若再發生 UNEXPECTED 重開,原因會直接寫在設備管理頁上。

問題:v6.0.36 把誤殺修掉之後,剩下的 UNEXPECTED 重開就是「真的卡死」了 —— 但卡在哪裡看不到。 [SLOW LOOP] 這行是在一輪主迴圈跑完才印的,而真正把設備卡死的那一輪永遠跑不完, 所以最關鍵的那筆資料按定義不存在。實測 .46 兩次超過 30 秒的卡死,翻遍設備 log 看到的最大值只有 4.5 秒 —— 全是無關的雜訊。

實機驗證(.250,-D WEDGE_TEST 測試韌體):在網頁伺服器段內故意讓主迴圈忙碌卡死 45 秒 ——

Content-Length 修正的回歸測試:2/3/4 位數長度的 POST body 各送一次,回傳內容與送出完全一致; 765,608 bytes 的 OTA(6 位數長度)亦正常完成。

#近期版本重點（v6.0.36 — 看門狗誤殺:對外 TLS 連線一慢就自己重開）

🔴 影響範圍:所有連雲端 / 連 MQTT broker 的設備,不分 8310 / 8320、不分有線 / WiFi。 這是業主長期回報「設備不定時自己重開、API 不穩定」的其中一個根因。

問題:硬體看門狗(IWDG)的期限是 8 秒,但一次對外 TLS 握手可以合法地花上 10 秒以上。 createWebClient() 的 setSocketTimeout(5000) 只管「單次 socket 收送」,而 TLS 握手要好幾個 來回、每一段各自可以吃滿 5 秒。逾時預算比看門狗還長,所以只要雲端或 broker 剛好慢一下, 設備就會在一件完全正常的工作中途被自己的看門狗打死。

實測證據(v6.0.35,兩台設備一整夜):4 次 UNEXPECTED 重開,指紋完全一致 —— 全部發生在一次對外 TLS 連線開始後的 10~11 秒:

設備並沒有當機 —— 它在做一件正常的事,只是做得比 8 秒久。

兩側都驗過(改的是安全機制本身,只驗「不再誤報」不夠 —— 若改壞了等於把看門狗拆掉, 而且症狀靜默:要等現場某台真的卡死、永遠不恢復才會有人發現):

回歸測試方式:PLATFORMIO_BUILD_FLAGS="-D WEDGE_TEST" pio run -e opta,燒錄後 GET /api/debug/wedge?ms=45000。該端點以 #ifdef WEDGE_TEST 保護,正式版編不進去。

代價:真正當機的自動復原從 8 秒變成最長 38 秒。換掉的是「每隔幾小時被誤殺一次」。 更長時間的迴圈卡死另有 v5.9.250 的 gateway 探測自救(>3 分鐘自重開)接手。

現場自我檢查:設備管理頁看「重開原因」,若出現 UNEXPECTED 而設備當時明明在正常運作, 且重開時間點對得上雲端心跳或 MQTT 重連,即為此缺陷。升級至 v6.0.36 以上即解。

#近期版本重點（v6.0.32 — WiFi 上線後未掛回 QSPI:開機卡死 / 網頁失效 / 授權無法還原）

🔴 影響範圍:interfaceMode=AUTO、未插網線、靠 WiFi 上線的設備(WIFI_ONLY 與純有線不受影響)。 此缺陷自 WI-124/125 落實 QSPI 並存時就存在(當時只改了 WIFI_ONLY 路徑),於 v6.0.32 修正。 ⚠️ v6.0.21 已因此自 stable 降回 dev;stable 目前為 v6.0.9。

現場自我檢查:若設備網頁打開後版面全亂(無樣式)、或重開後停在啟動階段連不上, 且該設備是「WiFi 連線 + 未插網線」,即為此缺陷。升級至 v6.0.32 以上即解; 無法連線者需以 USB DFU 燒錄。

#近期版本重點（v6.0.20 — 通知列改為文件流內，取代 v6.0.19 的浮動版）

v6.0.19 把右下角 toast 改成浮動的置頂通知列,但實機量到它壓住頁首的 🔄 按鈕 —— 等於把 死區從右下角搬到上面。根因:容器可以 pointer-events:none,但卡片本身必須可互動(✕ 要能按), 所以只要是浮動定位就一定會蓋住底下的東西。v6.0.19 請勿發佈給客戶,用本版取代。

#近期版本重點（v6.0.19 — 設定持久化修正 + 網頁操作阻塞修正）

三個症狀來自業主端回報:「勾選存不住」「密碼送不出去」「通知還在就不能按」。 前兩者是真 bug,第三者的真因與通知機制無關 — 是 CSS 命中測試。dev channel 先行。

⚠️ 本表在 v6.0.12 之後、v6.0.19 之前(v6.0.13 ~ v6.0.18)尚未補記,待回填。

#近期版本重點（v6.0.10 ~ v6.0.12 — MQTT 在線可觀測性:LWT + RS485 設備狀態事件 + UI 離線呈現）

📡 針對「客戶機台/控制器非 24h 在線(夜間斷電)」的觀測盲點。dev channel 先行,134 驗證後 promote stable。 v6.0.11/12 為 134 dogfood 即時修正:

#近期版本重點（v6.0.9 — 出廠預設 9600 + 「載入失敗仍可儲存」防呆 + 掃描涵蓋 4800/2400）

🛡️ 源於現場事故:cfg 載入失敗時通訊埠 modal 以預設值 19200 渲染、且變更確認被繞過,按儲存把 19200 靜默寫進設備 → RS485 全離線。本版根治整族「載入失敗 → 顯示預設值 → 儲存 = 靜默改設定」。

#近期版本重點（v6.0.8 — SF965 原生解碼 + 移除/新增暫存器保證）

🔢 徹底解決 SF965 計數值的小數/整數與設備增刪串台問題。與 6.0.x 向後相容。

#近期版本重點（v6.0.7 — RS485 離線行為改善）

🔌 針對「工廠下班/午休關機 → RS485 slave 離線」的兩個困擾。與 6.0.x 向後相容。

#近期版本重點（v6.0.6 — 畫面更新健壯化 + 模板 :N 說明）

🩺 針對「Opta API 偶爾失敗導致畫面難判斷狀況」。與 6.0.x 向後相容(app.js + index.html,無新韌體邏輯)。

#近期版本重點（v6.0.5 — Converter 存檔穩定性 + 模板小數位數修飾詞）

🔧 修 Converter 模板存檔失敗、總覽 RS485 區塊消失;新增模板變數小數位數控制。與 6.0.x 向後相容。

#近期版本重點（v6.0.4 — MQTT 連線測試 TLS 修正 + 小 UI）

🔧 修「設定頁 MQTT 測試連線在 TLS 時必失敗(直接存檔卻成功)」。與 6.0.x 向後相容。

#近期版本重點（v6.0.2 — RS485 同型號多台防串台）

🔧 修 WI-153 crosstalk 家族「重開機後復發」的根因。與 6.0.x 向後相容。

#近期版本重點（v6.0.1 — 遠端診斷：網頁 Serial Log + 開機原因）

🩺 遠端維運：針對「設備只能經 VPN 進入、現場無法插 USB 看 serial」的痛點。與 6.0.0 向後相容。

#近期版本重點（v6.0.0 — WI-155 多專案 × 多環境平台化）

🚩 v6.0.0 里程碑：自 5.9.285 起跳大版號,整合 WI-155 全系列(對外 MQTT 命名空間 + MAC 身分)。 與 5.9.x 向後相容(未設命名空間即沿用 legacy mes/gateway/{uid})。權威 per-version changelog 仍在 cloud manifest。

#近期版本重點（v5.9.241 ~ v5.9.244 — 8310 機型支援）

ℹ️ 權威 changelog 仍在 cloud manifest（單一來源，見上）。本段為文件側快速索引，方便對照本批 8310 相關改動， 對應 sprint cards WI-149 ~ WI-152。

注意：AP 模式需要 WiFi，只有 8320 能進；8310 無 WiFi 進不了 AP（會 fallback）。User button 開機長按：0-5s 正常 / 5-10s AP / 10s+ 原廠重置。

#相關程式（原始碼,非本站文件）

• scripts/release_firmware.py — 打包腳本（含 resolve_changelog）
• config-server/modules/firmware.js — Cloud upload endpoint
• config-server/public/index.html — Admin UI 韌體列表