設備協定

讀完你會知道：設備用哪兩種傳輸連上平台、topic 怎麼分、哪些訊息一定要處理。

設備用 mTLS 連上 device gateway，兩種傳輸擇一，兩邊的語意完全一樣：

傳輸	什麼時候用
MQTT 5	新韌體的預設
WSS	想用一條 WebSocket 收發 JSON 幀時（幀格式見本頁下面的說明）

端點不是寫死的：pairing 完成時平台會派發一組端點給設備，之後可以透過設定更新。

MQTT topic

所有 topic 都以自己的 device_id（憑證 CN）為前綴，設備只能碰自己的。

Topic	方向	內容
`kinio/devices/{device_id}/shadow/update`	設備 → 雲	`{state:{reported:{…}}, version?, client_token?}`；reported 只收能力模型裡的 key
`kinio/devices/{device_id}/shadow/update/accepted` \	`rejected`	雲 → 設備	上一則的結果
`kinio/devices/{device_id}/shadow/update/delta`	雲 → 設備	desired 與 reported 不同的葉子
`kinio/devices/{device_id}/shadow/get`	設備 → 雲	要整份文件 → `get/accepted` \	`rejected`
`kinio/devices/{device_id}/events`	設備 → 雲	`{type, payload, ts}`
`kinio/devices/{device_id}/commands`	雲 → 設備	`{command_id, op, id?, payload}`
`kinio/devices/{device_id}/commands/ack`	設備 → 雲	`{command_id, status, reason?, result?}`（status：ok / accepted / UPPER_SNAKE 錯誤碼）
`kinio/devices/{device_id}/presence`	last will（retained）	`{online:false}`

Shadow 的語意與 AWS IoT Core 相容，從 IoT Core 移植的程式碼改動很小。

Shadow 是狀態的單一真相

一台設備一份 shadow，分兩半：

reported：設備說自己現在怎樣。
desired：平台（使用者或規則）希望它變成怎樣。

設備開機後先報一次完整 reported，之後只報變動的部分。收到 delta 就去收斂，收斂後把新值報回來。不要只回 ack 不報 reported —— 平台以 reported 為準，沒報就會一直算你沒收斂。

文件形狀是兩層：{cluster: {attr: value}}。

{
  "state": {
    "reported": {
      "on_off": { "on": true },
      "kinio_system": { "fw_version": "1.2.0", "wifi_signal_percent": 78 },
      "kinio_motion": { "enabled": true }
    }
  }
}

在線狀態以連線為準

平台用連線 session 判斷設備在不在線，不靠心跳上報。斷線就是離線，重連就是上線。presence 的 retained 訊息是給第三方訂閱用的，不是平台的判斷依據。

事件

事件是「發生過的事」，和 shadow（現在的狀態）分開：移動偵測、按門鈴、SD 卡錯誤、OTA 進度。

{ "type": "motion.detected", "ts": "2026-09-23T10:04:12Z", "payload": { "zone": 2 } }

事件會進時序資料庫並觸發通知規則。不要把事件拿來當狀態用（例如每秒送一則 still_online），會被限流。

指令

平台下發的指令帶 command_id，設備做完要 ack 同一個 id。指令會去重：同一個 command_id 收到兩次，做一次就好。

常見指令在能力模型裡定義，例如 kinio_system 的 reboot、factory_reset、ota_start。

日誌

設備的 log 走 MQTT 的 log topic，預設只送 warn 以上。debug 等級要平台開啟，而且有存活時間，到期自動關掉，避免忘記關造成流量與費用。

錯誤處理的三條規則

連不上就退避重試，不要固定間隔猛打。建議指數退避加抖動，上限幾分鐘。
憑證錯誤不要重試。被拒絕通常代表憑證被撤銷或時間不對，重試沒用，要記錄下來等人處理。
開機先對時。憑證驗證吃系統時間，時間錯會一直失敗。沒有 RTC 的板子要在連線前先做一次網路對時。