一條物聯網設備控制命令的一生

-----概述------

為能有效地對設備進行管理，設備的產品模型中定義了物聯網平台可向設備下發的命令，應用服務器可以調用物聯網平台開放的API接口向單個設備或批量設備下發命令，或者用戶通過物聯網平台直接向單個設備下發命令，以實現對設備的遠程控制。

華為物聯網平台有兩種命令下發機制：

• 立即下發：不管設備是否在線，平台收到命令后立即下發給設備。如果設備不在線或者設備沒收到指令則下發失敗。支持給本應用的設備和被授予權限的其它應用的設備下發命令。

  立即下發適合對命令實時性有要求的場景，比如路燈開關燈，燃氣表開關閥。使用立即下發時，命令下發的時機需要由應用服務器來保證。

• 緩存下發：物聯網平台在收到命令后先緩存，等設備上線或者設備上報數據時再下發給設備，如果單個設備存在多條緩存命令，則進行排隊串行下發。支持給本應用的設備和被授予權限的其它應用的設備下發命令。

  緩存下發適合對命令實時性要求不高的場景，比如配置水表的參數。

對於使用LWM2M/CoAP協議的設備，建議用戶使用緩存下發模式，工作模式設置為PSM模式（系統默認值）。如需使用立即下發模式（工作模式設置為DRX或eDRX模式），需要在設備上報數據后立即下發命令才能成功。

對於集成了Agent Lite SDK或使用原生MQTT協議的設備，物聯網平台僅支持立即下發模式。

-----業務流程-----

LWM2M/CoAP協議設備場景

物聯網平台提供立即下發和緩存下發兩種機制。應用服務器向物聯網平台下發命令時，攜帶參數expireTime（簡稱TTL，表示最大緩存時間）。如果不帶expireTime，則默認expireTime為48小時。

• expireTime=0：命令立即下發。

• expireTime>0：命令緩存下發。

命令立即下發流程

1. 應用調用華為物聯網平台提供的接口，下發請求到物聯網平台，攜帶expireTime參數為0。消息樣例如下：

   Method: POST
   request: https://server:port/iocm/app/cmd/v1.4.0/deviceCommands
   Header:
   "app_key: ******"
   "Authorization:Bearer******"
   Content-Type:application/json
   Body:
   {
     "deviceId": "********",
     "command": {
       "serviceId": "Brightness",
       "method": "SET_DEVICE_LEVEL",
       "paras": {
         "value": "1",
         }
     },
     "callbackUrl": "http://127.0.0.1:9999/cmd/callbackUrl",
     "expireTime": 0,
     "maxRetransmit": 1
   }

2. 物聯網平台調用編解碼插件對命令請求進行編碼后，會通過LWM2M協議定義的設備管理和服務實現接口的Execute操作下發命令，消息體為二進制格式。

3. 物聯網平台向應用返回201 Created，攜帶命令狀態為SENT。（如果設備不在線或者設備沒收到指令則下發失敗，命令狀態為FAIL）

4. 設備收到命令后返回ACK響應。

5. 若應用下發命令時攜帶了"callbackUrl"，物聯網平台推送狀態通知消息給應用，攜帶命令狀態為DELIVERED。消息樣例如下：

   Method: POST
   request:
   Body:
   {
     "deviceId": "6543214c-72bb-4131-9e14-fad974123456",
     "commandId": "108a9c71462a48e09426e06e844d47ba3",
     "result": {
       "resultCode": "DELIVERED",
       "resultDetail": null
     }
   }

6. 設備執行命令后通過205 Content響應返回命令執行結果。

7. 若應用下發命令時攜帶了"callbackUrl"，物聯網平台會調用編解碼插件對設備響應進行解碼，然后推送狀態通知消息給應用，攜帶命令狀態為SUCCESSFUL。消息樣例如下：

   Method: POST
   request:
   Body:
   {
     "deviceId": "6543214c-72bb-4131-9e14-fad974123456",
     "commandId": "108a9c71462a48e09426e06e844d47ba",
     "result": {
       "resultCode": "SUCCESSFUL",
       "resultDetail": null
     }
   }

命令緩存下發流程

1. 應用調用華為物聯網平台提供的接口，下發請求到物聯網平台，攜帶expireTime參數大於0。

2. 物聯網平台將命令寫入緩存隊列，並上報201 Created，攜帶命令狀態為PENDING。

3. 設備上線或設備上報數據到平台。

4. 物聯網平台調用編解碼插件對命令請求進行編碼后，根據協議規范下發命令給設備。

5. 若應用下發命令時攜帶了"callbackUrl"，物聯網平台推送狀態通知消息給應用，攜帶命令狀態為SENT。

6. 后續流程請參考“命令立即下發”的步驟4到步驟7。

集成Agent Lite SDK設備/原生MQTT設備場景

對於集成Agent Lite SDK或使用原生MQTT協議接入的設備，物聯網平台只支持立即下發模式，設備不在線時命令下發失敗。

1. 應用調用華為物聯網平台提供的接口，下發請求到物聯網平台。消息樣例如下：

   Method: POST
   request: https://server:port/iocm/app/cmd/v1.4.0/deviceCommands
   Header:
   "app_key: ******"
   "Authorization:Bearer******"
   Content-Type:application/json
   Body:
   {
     "deviceId": "********",
     "command": {
       "serviceId": "Brightness",
       "method": "SET_DEVICE_LEVEL",
       "paras": {
         "value": "1",
         }
     },
     "callbackUrl": "http://127.0.0.1:9999/cmd/callbackUrl",
     "expireTime": 0,
     "maxRetransmit": 1
   }

2. 物聯網平台根據協議規范下發命令給設備。

   MQTT設備必須先訂閱平台指定的Topic才能收到平台下發的命令，消息樣例如下：

   { 
   "msgType": "cloudReq", 
   "serviceId": "Brightness", 
   "mid": 2016, 
   "cmd": "SET_DEVICE_LEVEL", 
   "paras": { 
    "value": "1"
    } 
   }

3. 物聯網平台向應用返回202 Accepted，攜帶命令狀態為SENT。

4. 設備收到命令后返回ACK響應。

5. 若應用下發命令時攜帶了"callbackUrl"，物聯網平台推送狀態通知消息給應用，攜帶命令狀態為DELIVERED。消息樣例如下：

   Method: POST
   request:
   Body:
   {
     "deviceId": "6543214c-72bb-4131-9e14-fad974123456",
     "commandId": "108a9c71462a48e09426e06e844d47ba",
     "result": {
       "resultCode": "DELIVERED",
       "resultDetail": null
     }
   }

6. 設備執行命令后返回命令執行結果，消息樣例如下：

   response: Status 
   Code: 200 OK

7. 若應用下發命令時攜帶了"callbackUrl"，物聯網平台會調用編解碼插件對設備響應進行解碼，然后推送狀態通知消息給應用，攜帶命令狀態為SUCCESSFUL。消息樣例如下：

   Method: POST
   request:
   Body:
   {
     "deviceId": "6543214c-72bb-4131-9e14-fad974123456",
     "commandId": "108a9c71462a48e09426e06e844d47ba",
     "result": {
       "resultCode": "SUCCESSFUL",
       "resultDetail": null
     }
   }

-----命令執行狀態說明-----

整個命令下發流程中命令執行狀態以及狀態變化機制如下圖所示。

等待（PENDING）

• NB-IoT設備采用緩存下發模式下發命令時，如果設備未上報數據，物聯網平台會將命令進行緩存，此時任務狀態為“等待”狀態。

• NB-IoT設備采用立即下發模式下發命令時，無此狀態。

• MQTT設備下發命時令，無此狀態。

超期（EXPIRED）

• NB-IoT設備采用緩存下發模式下發命令時，如果在設置的超期時間內，物聯網平台未將命令下發給設備，則狀態變更為“超期”。超期時間會根據北向接口中攜帶的expireTime為准，如果未攜帶，默認48h。

• NB-IoT設備采用立即下發模式下發命令時，無此狀態。

• MQTT設備下發命時令，無此狀態。

取消（CANCELED）

如果命令下發任務為“等待”狀態時，用戶人工取消了命令下發任務，則任務狀態變更為“取消”。

已發送（SENT）

• NB-IoT設備采用緩存下發模式下發命令時，設備上報數據，物聯網平台會將緩存的命令發送給設備，此時狀態會由“等待”變為“已發送”。

• NB-IoT設備采用立即下發模式下發命令時，如果設備在線，狀態為“已發送”。

• MQTT設備下發命時令，如果設備在線，狀態為“已發送”。

超時（TIMEOUT）

NB-IoT設備收到命令后，物聯網平台在180秒內未收到設備反饋的收到命令響應，此時狀態會變為“超時”。MQTT設備無此狀態。

已送達（DELIVERED）

物聯網平台收到設備反饋的已收到下發命令響應后，狀態變為“已送達”。

成功（SUCCESSFUL）

如果設備在執行完命令后，會給物聯網平台反饋命令執行成功的結果，將任務狀態變更為“成功”。

失敗（FAIL）

• 如果設備在執行完命令后，會給物聯網平台反饋命令執行失敗的結果，將任務狀態變更為“失敗”。

• NB-IoT設備采用立即下發模式下發命令時，如果設備離線，狀態為“失敗”。

• MQTT設備下發命令時，如果設備離線，狀態為“失敗”。