Asynchronous Command Delivery

Introduction

Asynchronous command delivery is used for IoTDA or applications to deliver commands to devices using LwM2M over CoAP to access IoTDA. Two modes are available.

Immediate Delivery of Asynchronous Commands

Figure 1 Command delivery for devices using LwM2M over CoAP

An example of the corresponding steps is as follows:

1. An application calls the API Deliver an Asynchronous Command to send a command to the platform. The send_strategy parameter in the command request is set to immediately. Example message:

   POST https://{endpoint}/v5/iot/{project_id}/devices/{device_id}/async-commands
   Content-Type: application/json
   X-Auth-Token: ********
   
   {
     "service_id" : "WaterMeter",
     "command_name" : "ON_OFF",
     "paras" : {
       "value" : "ON"
     },
      "expire_time": 0,
      "send_strategy": immediately
   }

2. The platform uses the codec to encode the command request, and sends the command through the Execute operation of the device management and service implementation interface defined in the LwM2M protocol. The message body is in binary format.
3. The platform sends a 200 OK message carrying the command status SENT to the application. (If the device is offline or the device does not receive the command, the delivery fails and the command status is FAILED.)
4. The device returns an ACK message after receiving the command.
5. If the application has subscribed to command status change notifications, the platform pushes a message to the application by calling the API Pushing a Command Status Change Notification. The command status carried in the message is DELIVERED. Example message:

   Method: POST
   request:
   Body:
   {
       "resource": "device.commmad.status",
       "event": "update",
       "event_time": "20200811T080745Z",
       "notify_data": {
           "header": {
               "app_id": "8d4a34e5363a49bfa809c6bd788e6ffa",
               "device_id": "5f111a5a29c62ac7edc88828_test0001",
               "node_id": "test0001",
               "product_id": "5f111a5a29c62ac7edc88828",
               "gateway_id": "5f111a5a29c62ac7edc88828_test0001",
               "tags": []
           },
           "body": {
               "command_id": "49ca40af-7e14-4f7b-b97b-78cdd347a6b9",
               "created_time": "20200811T080738Z",
               "sent_time": "20200811T080738Z",
               "delivered_time": "20200811T080745Z",
               "response_time": "",
               "status": "DELIVERED",
               "result": null
           }
       }
   }

6. After the command is executed, the device returns the command execution result in a 205 Content message.
7. If the application has subscribed to command status change notifications, the platform uses the codec to decode the command response and sends a push message to the application by calling the API Pushing a Command Status Change Notification. The command status carried in the message is SUCCESSFUL. Example message:

   Method: POST
   request:
   Body:
   {
       "resource": "device.commmad.status",
       "event": "update",
       "event_time": "20200811T080745Z",
       "notify_data": {
           "header": {
               "app_id": "8d4a34e5363a49bfa809c6bd788e6ffa",
               "device_id": "5f111a5a29c62ac7edc88828_test0001",
               "node_id": "test0001",
               "product_id": "5f111a5a29c62ac7edc88828",
               "gateway_id": "5f111a5a29c62ac7edc88828_test0001",
               "tags": []
           },
           "body": {
               "command_id": "49ca40af-7e14-4f7b-b97b-78cdd347a6b9",
               "created_time": "20200811T080738Z",
               "sent_time": "20200811T080738Z",
               "delivered_time": "20200811T080745Z",
               "response_time": "20200811T081745Z",
               "status": "SUCCESSFUL",
               "result": {
                   "resultCode":"SUCCESSFUL",
                   "resultDetail": {
                       "value": "ON"
                   }
               }
           }
       }
   }

Delayed Delivery of Asynchronous Commands

Figure 2 Delayed command delivery for devices using LwM2M over CoAP

1. An application calls the API Deliver an Asynchronous Command to send a command to the platform. The send_strategy parameter in the command request is set to delay.
2. The platform adds the command to the cache queue and reports a 200 OK message. The command status is PENDING.
3. The device goes online or reports data to the platform.
4. The platform uses the codec to encode the command request and sends the command to the device according to the protocol specifications.
5. If the application has subscribed to command status change notifications, the platform pushes a message to the application by calling the API Pushing a Command Status Change Notification. The command status carried in the message is SENT.
6. The subsequent flow is the same as 4 to 7 described in the immediate delivery scenario.

LwM2M/CoAP Device Command Execution Status

The figure below illustrates the command execution status and the table below describes the status change mechanism.

Figure 3 LwM2M/CoAP command delivery status

APIs

• Deliver an Asynchronous Command
• Query a Command with a Specific ID