設備命令topic 簇
MQTT物聯網套件支援應用通過API直接向設備發送單播命令，設備可以通過設備命令topic 簇獲取消息並進行消息應答
設備命令交互流程見下圖：
設備命令topic 簇topic 列表如下：
| 系統topic | 用途 | QoS | 可訂閱 | 可發佈 |
|---|---|---|---|---|
| $sys/{pid}/{device-name}/cmd/request/{cmdid} | 系統向設備下發命令 | 0 | √ | |
| $sys/{pid}/{device-name}/cmd/response/{cmdid} | 設備回復命令應答 | 01 | √ | |
| $sys/{pid}/{device-name}/cmd/response/{cmdid}/accepted | 系統回復"設備命令應答成功" | 0 | √ | |
| $sys/{pid}/{device-name}/cmd/response/{cmdid}/rejected | 系統回復"設備命令應答失敗" | 0 | √ |
- 當應用調用通過命令API創建設備命令時，設備必須處於在線狀態設備需提前訂閱系統topic 以獲取該命令消息
- 設備可以通過發佈消息至系統topic 的方式，進行設備命令結果應答
- 設備進行命令應答之後，平台發送命令應答結果通知，設備需提前訂閱系統topic 以獲取該消息
- API返回為同步返回，即，當設備進行命令應答之後，或者當應答超時後，系統返回API請求結果，見命令API詳情
設備命令下發
應用可通過API 創建下發命令，平台會將該命令消息發佈至系統topic：
$sys/{pid}/{device-name}/cmd/request/{cmdid}，若設備訂閱了該topic則可獲取該命令消息，用戶可自訂消息內容
cmdid 為平台為該命令自動創建的唯一標識
命令消息內容由應用與設備協商確定，平台將該消息存放於publish payload中進行數據透傳
推薦設備採用萬用字元方式進行命令請求消息訂閱：如$sys/{pid}/{device-name}/cmd/request/+
設備命令回復
設備接收該命令後，可通過發佈消息至topic：$sys/{pid}/{device－ name}/cmd/response/{cmdid} 進行該命令結果的應答，用戶可自訂應答數據內容
- cmdid 為平台為命令下發時攜帶的唯一標識，設備應答某一條具體命令時，應將cmdid置於topic 路徑中
- 命令應答內容由應用與設備協商確定，設備需將該消息存放於publish payload中進行上報
- 應答報文payload 中，數據長度必須小於1k
設備命令回復時，支援QoS1，若publish QoS＝1，則平台回復publish ack
命令回復結果通知
平台接收該應答，會通過cmdid 存儲該應答數據，並通過系統topic 進行處理結果通知
- 命令應答成功時，系統通過topic $sys/{pid}/{device-name}/cmd/response/{cmdid}/accepted 發佈空消息
- 命令不可重複應答，重複應答的消息將會通過拒絕，通過系統topic$sys/{pid}/{device-name}/cmd/response/{cmdid}/rejected
- 返回消息推薦設備採用萬用字元方式進行命令應答結果消息訂閱：如：$sys/{pid}/{device－name}/cmd/response/+/+
應答錯誤碼
當設備進行命令應答出錯時，平台會通過topic $sys/{pid}/{device－ name}/cmd/response/{cmdid}/rejected 發佈錯誤消息
其中，錯誤碼清單如下：
| 錯誤碼 | 錯誤說明 | Remarks |
|---|---|---|
| 99 | maximum payload size exceeded | 設備回復的命令回應長度超過限制 （1k） |
| 100 | internal error | 伺服器內部錯誤 |
| 112 | cmd response timeout | 設備在超時時間後回復命令 |
| 113 | cmd id not found | 未找到對應的命令ID（命令ID錯誤或者命令重複應答） |
錯誤消息示例如下：
{
"err_code": 99,
"err_msg":"maximum payload size exceeded"
}