裝置 REST API

📅 最後更新：2026-06-16 ｜ 🛠 對應韌體：v5.9.249 ｜ 📌 負責人：KC

Opta（MES Gateway）韌體在 TCP 埠 80 上以 HTTP/1.1 提供約 50+ 個 REST endpoint。所有路由都是在 src/main.cpp 的網路 loop 內以 firstLine.indexOf(...) 字串比對方式分派；handler 實作分佈於 ApiHandlers_Core.cpp、ApiHandlers_Connectivity.cpp、ApiHandlers_Modbus.cpp、ApiHandlers_Logic.cpp、OtaHandler.cpp。

v5.1 起為 Unified Network Architecture——同一份韌體同時支援乙太網路與 WiFi。v5.6 整合 TCP IO Channel 與非同步 RS485 掃描。v5.9.125+ 新增 MQTTS（useTls / caCert）支援。

#認證機制

韌體採用 Token-based RBAC。Token 由 POST /api/tokens 建立，可透過下列任一方式攜帶：

• HTTP Header：Authorization: Bearer <token>
• Query 參數：?token=<token>

僅 /api/system 在 dispatcher 層強制檢查（v5.9 之後因 login modal 用此 endpoint 驗證 token），其餘 endpoint 由各自 handler 內呼叫 checkAuth(req, PERM_*) 把關，未通過則回 401 Unauthorized JSON：

{"error": "Unauthorized"}

#權限等級

- 表示 dispatcher 直接放行（如 /api/io、/api/config GET、/、/favicon.ico 等）。

#Endpoint 總覽

#系統 / 診斷

#設定

#I/O

#規則 / 訊號 / 動作 / 虛擬通道

*GET 不檢查 auth，POST 需 ADMIN。

#Modbus / RS485

#TCP IO / Converter（轉換器）

#連線 / MQTT / WiFi

WiFi 與 /api/network/apmode 僅在編譯時定義 USE_WIFI 才會啟用。

#雲端 / Config Server

#Token 與認證

#統計與電力

#License

#OTA（空中更新）

#Debug

#詳細範例

#系統健康狀態 — GET /api/system

此 endpoint 是前端 heartbeat / login 驗證用。從 v5.9（WI-115k）起 dispatcher 強制 PERM_READONLY——login modal 直接拿這個端點驗 token 是否合法，否則先前任意密碼都回 200 會被誤判成功。

回應主要欄位：

{
  "apMode": false,
  "version": "5.9.130",
  "board": "Arduino Opta",
  "uptime": 123456,
  "memory": {
    "totalRAM": 523624,
    "freeRAM": 453880,
    "usedRAM": 69744,
    "usagePercent": 13.4
  },
  "flash": {
    "totalFlash": 786432,
    "usedFlash": 781000,
    "qspiFlash": 16777216
  },
  "mac": "AA:BB:CC:DD:EE:FF",
  "licensed": true,
  "licensedFeatures": ["rule_engine", "mqtt", "tcp_io"],
  "bootTries": 1,
  "systemStatus": "OK"
}

⚠️ flash.usedFlash 接近 786432（partition 上限）時要警覺——v5.9.113 之後 build 已穩定 ≥ 99.3% 使用率，新功能加進來前要先評估 binary size，否則 OTA 會被 /api/ota/trigger 的 413 Payload Too Large 擋下（見 WI-115g）。

apMode = true 是前端切換到 Provisioning Wizard 的主要 trigger。

#設定 — GET /api/config

完整節點設定 dump，主要 block：

{
  "firmwareVersion": "5.9.130",
  "deviceName": "opta-line-3",
  "mac": "AA:BB:CC:DD:EE:FF",
  "network": {
    "ethDhcp": true,
    "ethIp": "192.168.1.100",
    "ethGateway": "192.168.1.1",
    "ethSubnet": "255.255.255.0",
    "wifiDhcp": true,
    "wifiIp": "...",
    "wifiGateway": "...",
    "wifiSubnet": "...",
    "interfaceMode": 0
  },
  "wifi": { "ssid": "MyAP", "passwordLen": 16 },
  "tcp": { "port": 80 },
  "mqtt": {
    "enabled": true,
    "broker": "mqtt.example.com",
    "port": 8883,
    "clientId": "opta-abc",
    "username": "device",
    "password": "********",
    "topicPrefix": "factory/lineA/",
    "publishPeriodicIo": true,
    "useTls": true,
    "caCert": "-----BEGIN CERTIFICATE-----\nMIIDxz...==\n-----END CERTIFICATE-----\n"
  },
  "rs485": { "baudRate": 9600, "masterMode": true, "slaveId": 1 },
  "inputMode": [0, 0, 0, 0, 0, 0, 0, 0],
  "inputOp":   [0, 0, 0, 0, 0, 0, 0, 0],
  "inputThreshold": [3.3, 3.3, 3.3, 3.3, 3.3, 3.3, 3.3, 3.3],
  "inputNames": ["DI1", "DI2", "..."],
  "doNames":    ["DO1", "DO2", "DO3", "DO4"],
  "expansions": [...],
  "qspiMounted": true,
  "modbusDevices":   [...],
  "modbusRegisters": [...],
  "rs485Buses":      [...]
}

v5.9.125+：MQTT block 新增 useTls 與 caCert。caCert 在 wire format 上把實際換行字元轉成字面 \n，前端送回時必須維持 JSON-escape 形式。

#設定 — POST /api/config

需 PERM_ADMIN。只送要改的欄位，handler 內以 indexOf("\"key\":value") 字串比對；JSON 必須是 compact 格式（key/value 之間沒有空格），否則會靜默失敗。

{
  "deviceName": "opta-line-3",
  "mqtt": {
    "enabled": true,
    "broker": "mqtt.example.com",
    "port": 8883,
    "useTls": true,
    "caCert": "-----BEGIN CERTIFICATE-----\\n...\\n-----END CERTIFICATE-----\\n"
  }
}

回應：

• 200 OK：{"success": true, "message": "Config updated and saved"}
• 400 Bad Request：{"error": "No valid fields to update"}
• 401 Unauthorized：{"error": "Unauthorized"}

寫入時透過 NetworkStateManager::requestSafeSave() 延後到 WiFi state machine 安全空檔，避免跟 supplicant transition 衝突。MQTT 相關欄位改動會自動重連 broker。

#切換數位輸出 — POST /api/io/do

需 PERM_CONTROL。

{ "index": 0, "value": true }

或同時設定多顆（舊版）：

{ "values": [true, false, false, true] }

Pulse 模式（pulse: true, duration: <ms>）目前 handler 預留但尚未實作。

回應：

• 200 OK：{"success": true, "index": 0, "value": true}
• 400 Bad Request：index 越界 {"error": "invalid index"}

#Modbus 掃描 — POST /api/modbus/scan

需 PERM_ADMIN。RS485 掃描是 非同步 的：POST 啟動 → 持續 GET 輪詢結果 → 必要時 DELETE 取消。

# 啟動
curl -X POST -H "Authorization: Bearer $TOKEN" \
     http://opta.local/api/modbus/scan -d '{"busId":0}'
# → 202 {"status":"scanning"}

# 輪詢
curl -H "Authorization: Bearer $TOKEN" http://opta.local/api/modbus/scan
# 完成：{"devices":[{"slaveId":1,"name":"TDA-08B","registers":[...]}]}

# 取消
curl -X DELETE -H "Authorization: Bearer $TOKEN" http://opta.local/api/modbus/scan

掃描期間 RS485 bus 會被自動 lock 阻止 polling，掃完自動釋放。也可手動 POST /api/modbus/lock 在做手動寫入時暫鎖匯流排。

#MQTT 測試 — POST /api/mqtt/test

需 PERM_ADMIN。可帶 body 用指定設定測試；省略則用目前設定。

{
  "broker": "mqtt.example.com",
  "port": 8883,
  "username": "test",
  "password": "test",
  "useTls": true,
  "caCert": "-----BEGIN CERTIFICATE-----\\n...\\n"
}

回應：

• 200 OK：{"success": true, "message": "Test message published"}
• 400 / 500：{"success": false, "error": "..."}

MQTTS 自簽 broker 注意（v5.9.125~130）：mbedTLS 不認 IP-type SAN，broker cert 必須同時放 IP:x.x.x.x 與 DNS:x.x.x.x，否則 handshake 會在 verify 階段失敗。

#Token 管理

列表（GET /api/tokens） — PERM_READONLY：

[
  { "index": 0, "name": "frontend",  "permission": "ADMIN",    "createdAt": 1737000000, "lastUsedAt": 1737900000 },
  { "index": 1, "name": "factory-rd", "permission": "CONTROL", "createdAt": 1737100000, "lastUsedAt": 0 }
]

建立（POST /api/tokens） — PERM_ADMIN：

{ "name": "ops-readonly", "permission": "READONLY" }

回應 僅此一次 包含明文 token：

{ "success": true, "token": "tok_...", "name": "ops-readonly", "permission": "READONLY" }

撤銷（DELETE /api/tokens） — PERM_ADMIN：

{ "index": 1 }

#License 啟用流程

License 採 device → cloud → device 三段式：

1. POST /api/license/activate → 標記 pending，回 {"status":"pending"}
2. 雲端（opta.smms.com.tw）約 30 秒一次 heartbeat 收 verdict
3. GET /api/license 取得當下狀態：

{
  "status": "active",
  "licenseId": "LIC-2026-xxx",
  "features": ["rule_engine", "mqtt", "tcp_io"],
  "expiryDate": 1764547200,
  "lastKnownTime": 1745000000
}

重要：/api/license GET handler 不會主動 POST activate，避免跟 server「rejected → pending 重申」邏輯衝突（前端 polling 會把 rejected 推回 pending 永遠跑不出 PENDING 迴圈）。Verdict pull 是 cloud→device，使用者顯式 activate 才是 device→cloud。

#OTA 觸發 — POST /api/ota/trigger

需 PERM_ADMIN。Body 帶 url（必要）與 version（建議，作為 guard）：

{ "url": "https://opta.smms.com.tw/firmware/opta_v5.9.131.bin", "version": "5.9.131" }

回應：

WI-115c：拒絕 same-version OTA——重複 swap 同一份 firmware 會踩到 bootloader fallback 邏輯，被丟去 DFU。
WI-115g：partition 上限 786432 bytes，留 6KB 緩衝設 780,000 bytes 為硬上限。超過請改用 USB DFU。

#時間同步 — POST /api/time/sync

需 PERM_ADMIN，從瀏覽器同步 RTC（WI-079）。

{ "timestamp": 1748044800 }

回應：

• 200 OK：{"status":"success","timestamp":1748044800}
• 400 Bad Request：timestamp 比 lastKnownTime 還舊會被拒。

#非同步 Config Server 測試

POST /api/configserver/test 觸發後立刻回 {"status":"testing"}；client socket 關閉後韌體才在 loop() 跑實際連線（避免佔用 outbound socket）。輪詢 GET /api/configserver/test：

{
  "status": "done",
  "success": true,
  "latency": 142,
  "version": "v2.2.10",
  "error": ""
}

#批次輪詢 — GET /api/poll

合併 system + io + virtual + stats 為單一 response，減少前端輪詢成本。內部依序呼叫各 handler 並省略 HTTP header（printHeader = false），最後組成單一 JSON 物件，欄位即四個子 handler 的合併。

#HTTP 狀態碼

錯誤一律走 JSON：

{ "error": "register_not_found", "message": "registerIdx out of range for this device" }

Modbus handler 另有 sendErr(httpCode, statusText, errorCode, message) 統一包裝，常見 errorCode：

• register_not_found
• register_not_writable（Register mode != 1）
• device_not_found
• bus_locked

#近期變更（v5.9.x 重點）

#實作備註

1. 無 router framework：所有 endpoint 在 main.cpp:1657–2071 以 else if (firstLine.indexOf("METHOD /path") >= 0) 串接，順序決定優先權——較長的路徑（例如 /api/configserver/test）必須排在較短前綴（/api/configserver）之前。新增 endpoint 時注意這個順序陷阱。
2. Auth 分佈：除 /api/system 在 dispatcher 即驗，其餘 endpoint 在各 handler 一進入就呼叫 checkAuth(req, PERM_*)，失敗回 401。
3. Streaming uploads：/api/upload 與 /api/ota/upload 不把 body 載進記憶體，邊收邊寫 QSPI / partition；OTA upload 期間 localConfig.unmount() → 寫入 → remount()。
4. Async pattern：Config server test、OTA version list、Modbus scan、License activate 都用「先回 202/pending → 在 loop() 跑工作 → 後續 GET 輪詢結果」模式，避免阻塞單一 client socket。
5. JSON 寫回：所有 JSON response 都標 Content-Type: application/json、Connection: close，多數不帶 Content-Length（chunked-style，由 FIN 標 EOF），client 必須讀到 socket 關閉才算完整。
6. Config POST 字串比對：handler 用 indexOf("\"key\":value")，JSON 必須 compact 無空格——Python json.dumps 預設帶空格會靜默失敗，務必加 separators=(",", ":")。
7. USE_WIFI 編譯切換：WiFi 與 AP mode 相關 endpoint 用 #ifdef USE_WIFI 包住；Ethernet-only build 不會註冊這些路由，request 會回 404。
8. Content-Length 用 byte 數：handler 依 Content-Length 讀 body，中文 UTF-8 每字 3 bytes；client 若用字元數會截斷 body（POST 回 success 但欄位沒套用）。
9. 保留 MQTT topic {prefix}/cmd/_ping（v5.9.130+）：韌體 self-ping 健康檢查專用，外部請勿佔用。
10. MQTT-Chain 工作流：/api/signals、/api/actions、/api/rules、/api/tcpio、/api/converter/* 可組成有狀態工作流（state 經 MQTT loopback）。完整 schema、欄位、雷區見 ../specs/spec-mqtt-chain-workflow.md。

#延伸閱讀