對接總覽
讀完你會知道：平台上有哪三種對接對象、一台新設備從燒錄到上線的六個步驟、哪些東西不用寫死在韌體裡。
這份文件說明一台設備或一個應用要怎麼接上 Kinio 平台。所有品牌共用同一套平台，品牌只影響帳號歸屬與介面外觀。不熟的名詞（AID、mTLS、directory、Thing、shadow）在文末的「名詞表」各有一句說明。
三種對接對象
| 對象 | 身分 | 走什麼 |
|---|---|---|
| 原生設備（用 Kinio 韌體） | AID + 憑證（mTLS） | MQTT 5 或 v3 WSS 到 device gateway |
| 既有設備（v1/v2 舊平台、其他品牌的原廠設備） | 原本的 DID / MAC，不發 AID | 原協定打相容層，平台把它映成同一種 Thing |
| 應用 / 服務（App、網頁、第三方系統） | 使用者的 token（OAuth client） | HTTPS REST + WSS |
平台裡所有東西都是 Thing：一台攝影機、NVR 的一個通道、一個插座、一個 gateway 子設備都是 Thing，能力用同一套模型描述。你不需要為了不同世代的設備寫兩套 App。
一台新設備上線的六步
- 燒錄韌體。韌體裡沒有身分，只知道一個位址：
directory的主機名。 - 取得 AID：在本站的「AID」頁下單，指定交給成員（開發、小批量）或交給工廠（量產）；見「AID 與憑證」。
- 設備拿到身分：交給工廠的那批在產線燒進設備；交給成員的留在平台，配對一台還沒有 AID 的設備時由平台送進去。
- 設備連線：先問 directory「我該連哪裡」，拿到這個環境的端點集，再用憑證做 mTLS 連上 device gateway。
- 使用者配對：App 開配對 session，設備用 AID 私鑰簽一段隨機字串證明自己持有身分，平台把設備綁進家戶。
- 開始運作：設備回報狀態、送事件、收指令（含 OTA）。
之後設備就只做三件事：回報狀態（shadow）、送事件、收指令（含 OTA）。
你不需要寫死的東西
設備韌體裡只寫死 directory 的主機名。API、MQTT broker、媒體中繼、OTA 來源全部是 pairing 時派發的，之後也能用設定更新。連 directory 本身都能透過 OTA 換掉。
這是刻意的：換機房、加區域、搬環境都不需要重燒韌體。
環境
| 環境 | 用途 | 你會拿到 |
|---|---|---|
| dev | 開發與驗證 | 測試用 AID（sandbox CA 簽）、可自由重置 |
| prod | 正式出貨 | 正式 AID（production CA 簽） |
環境是綁在家戶上，不是綁在帳號。同一個帳號可以同時有 dev 與 prod 家戶，在 App 裡切家戶就等於切環境，不用重新登入、不用重新配對。
接下來
- 身分怎麼運作：AID 與憑證
- 設備怎麼講話：設備協定
- 能力怎麼描述：能力模型
- App 怎麼接：應用端 API
- 韌體怎麼更新：OTA 與韌體格式
- 沒有板子先試：用模擬器先跑（說明）
名詞表
| 名詞 | 一句話 |
|---|---|
| AID | 設備在平台上的身分證；每台一顆，含憑證與私鑰 |
| mTLS | 雙向 TLS：設備用自己的憑證證明身分，平台也證明自己 |
| CSR | 憑證簽章請求：設備把公鑰交給平台簽，私鑰不出設備 |
| directory | 告訴設備「該連哪個環境的哪些主機」的服務 |
| Thing | 平台裡的一個被管理的東西：一台設備、NVR 的一個通道、一個子設備 |
| shadow | 設備狀態的雲端副本：設備回報的（reported）與 App 想要的（desired） |