此文是对 kb2022 系统里硬件接入的說明。完成接口文檔可以在此查看。
核心功能
在新系統中，硬件可以被簡單的看作是一個遠程播放器，它的核心功能是向服務器訂閱一個節目單，這個接口會在設備需要播放時，通知設備一個房間號碼(room)，在播放結束時通知一個空字符串的房間號碼。硬件只需要無腦的在得到房間號(room)時去房間接收實時的 mp3幀 流並轉發給聲卡播放即可。
服務器已經爲設備處理好了應該播放的任務等級和過濾等，設備不需要再進行判斷，收到房間號去接收mp3幀 轉給聲卡，收到空白字符串房間號停止播放即可。
此外爲了節省流量，服務器支持一套緩存算法，客戶端可以可選的去實現它。這在重複播放同一音樂多次時相當有幫助！你可以房間接收接口中查看詳細規則。
回傳狀態
設備可以在自己空閒的時間將自己的狀態回報給服務器，這通過調用服務器提供的 SetFields 接口來完成，SetFields 的內容是一個鬆散的 json ，服務器僅僅只是將其存儲而不做處理(由最終給用戶的前端ui自行按需處理)，這樣可以在不修改服務器的前提下動態的增加和刪除要回傳的內容，你可以在此查看目前已定義的回傳內容！
設備可以選擇在回傳狀態前先獲取服務器的狀態以確定是否要回傳，這可以通過調用服務器提供的 GetFields 來獲取服務器目前記錄的狀態值。
擴展功能
除了最主要的核心播放功能外，設備還支持一些擴充功能。如果把核心播放功能想象成一個遠程播放器，那控制功能可以類比成一個排隊的遠程遙控器。
最終用戶可以操作這個遙控器調整一些設備的參數，對於這些操作服務器會將其存儲成爲一個任務隊列保存。並且在有了新的任務時會將任務id通知給設備，這和核心功能中訂閱的是同一個接口，它除了房間號還用於通知這個最後的任務id (last)。
任務 id 是一個自增的 uint64，即使每秒消耗1萬個id也要 100年才能耗盡，所以不用擔心它被耗盡！設備應該在自己空閒時，按照從小到大的順序來處理這些任務，並記錄自己已經處理結束的任務，以便可以在斷電重啓等情況下可以繼續處理後續沒處理的任務。
設備可以調用服務器提供的 Command 來獲取自己未完成的任務，當任務處理完成後無論成功還是失敗(失敗也是一種處理完成的結果)都應該調用服務器提供的 Complete 來通知服務器設備已經處理完這個任務了，這樣服務器會將處理結果通知給用戶。此外如果一個任務處理時間較長，你也可以調用 Complete 設置特定的參數，來讓服務器和用戶知道處理進度！
任務的具體內容和回傳類似，也是由鬆散的 json 組成的，這樣前端和設備可以自由的增加刪除任務而服務器不需要做出修改，服務器僅僅是將用戶和設備連接，在它們之間互相傳遞消息罷了！你可以在此查看已有的任務定義。
通信協議
- 服務器採用了無狀態的 http 作爲標準接口，所以任何接口都可以獨立調用與測試，只要滿足 http 協議即可，訂閱和mp3流使用了 websocket 來提供支持。
- 此外服務器實際是由 grpc 完成的，故所有接口也可以使用 grpc 調用。
- 大多數嵌入式設備不支持 http 和 grpc，爲此我設計了一個 tcp 代理協議，嵌入式設備也通過提供的 代理協議訪問接口，代理協議按照固定的方式代理訪問 http 接口。你可以在此查看代理協議的詳細定義，此外它也提供了一個 docker 供客戶端測試協議！