Help Center> IoT Device Access> User Guide> Message Communications> Command Delivery> Command Delivery for Devices Using LwM2M over CoAP
Updated on 2023-01-18 GMT+08:00

Command Delivery for Devices Using LwM2M over CoAP

For devices using LwM2M over CoAP, the IoT platform provides two delivery mechanisms: immediate delivery and delayed delivery. The parameter send_strategy in the command delivered from an application to the platform specifies the delivery mechanism.

  • If send_strategy is immediately, the command is delivered immediately.

  • If send_strategy is delay, the command is cached before being delivered.

Immediate Delivery

This section describes the process of immediate command delivery.

  1. An application calls the API Delivering 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

This section describes the process of delayed command delivery.

  1. An application calls the API Delivering 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.

Asynchronous Command Delivery

The platform supports command delivery to an individual device using LwM2M over CoAP by calling the API Delivering an Asynchronous Command or creating a command delivery task on the console. This section describes how to create a command delivery task on the console.

Method 1:

  1. Access the IoTDA service page and click Access Console.
  2. In the navigation pane, click Products. In the product list displayed, click View in the row of a product to access its details. For details on how to create a product, see Creating a Product.
  3. On the Online Debugging tab page, click Add Test Device. In the dialog box displayed, set device parameters and click OK.

    Parameter

    Description

    Device Type

    Select Physical device.

    Device Name

    Customize a name, for example, TestDevice.

    Node ID

    Enter the IMEI of a device using LwM2M over CoAP.

    Registration Mode

    Select Unencrypted. (The non-encryption mode is selected for demonstration. In commercial scenarios, the encryption mode is recommended.)

  4. In the test list, click Debug.

  5. Select the command to deliver and set the command parameters. You can choose to send the command immediately or after a delay.

  6. In the navigation pane, choose Devices > All Devices, click View in the row of the device to which the command is delivered, and click the Commands tab. On this tab page, you can view the creation time of the command delivery task, the time at which the platform sent the command, the time at which the command was delivered, and the command status. This information helps you learn the command execution status.

In addition, you can call the API Querying a Command with a Specific ID to query the status and content of delivered commands on the platform.

Method 2

  1. Access the IoTDA service page and click Access Console.
  2. In the navigation pane, choose Devices > All Devices. In the device list, click View in the row of a device to access its details.
  3. On the Commands tab page, click Deliver Command in the upper right corner. In the dialog box displayed, select the command to deliver and set the command parameters. You can choose to send the command immediately or after a delay.

Command Execution Status

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

Status

Description

PENDING

  • For a device using LwM2M over CoAP in delayed delivery mode, the platform caches a command if the device has not reported data. The command status is PENDING.
  • This status does not exist for devices using LwM2M over CoAP in immediate delivery mode.

EXPIRED

  • For a device using LwM2M over CoAP in delayed delivery mode, if the platform does not deliver a command to the device within a specified time, the command status is EXPIRED. The expiration time is subject to the value of expireTime carried in the command request. If expireTime is not carried, the default value (24 hours) is used.
  • This status does not exist for devices using LwM2M over CoAP in immediate delivery mode.

SENT

  • For a device using LwM2M over CoAP in delayed delivery mode, the platform sends a cached command when receiving data reported by the device. In this case, the command status changes from PENDING to SENT.
  • For a device using LwM2M over CoAP in immediate delivery mode, if the device is online when the platform delivers a command, the command status is SENT.

TIMEOUT

If the platform does not receive a response within 180 seconds after delivering a command to a device using LwM2M over CoAP, the command status is TIMEOUT.

DELIVERED

If the platform receives a response from a device, the command status is DELIVERED.

SUCCESSFUL

If the platform receives a result indicating that the command is executed, the command status is SUCCESSFUL.

FAILED

  • If the platform receives a result indicating that the command execution failed, the command status is FAILED.
  • For a device using LwM2M over CoAP in immediate delivery mode, if the device is offline when the platform delivers a command, the command status is FAILED.