Command Delivery, Property Setting, and Property Query

The processes of command delivery, property setting, and property query are the same. After an application sends a command to a device, the application waits for a message carrying the command execution result from the device. This document uses command delivery as an example. For details on how to set and query properties, see the APIs Modifying Device Properties and Querying Device Properties.

1. An application calls the API Delivering a Device Command to send a command to the platform. Example message:

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

2. The platform sends the command to the device according to the protocol specifications.
   The MQTT device can receive commands delivered by the platform only after subscribing to the topic corresponding to the API Delivering a Command. Example message:

   Topic: $oc/devices/{device_id}/sys/commands/request_id={request_id} 
   Data format:
   {
     "object_device_id": "{object_device_id}",
     "command_name": "ON_OFF",
     "service_id": "WaterMeter",
     "paras": {
       "value": "ON"
     }
   }

3. After executing the command, the device returns the command execution result through the API Delivering a Command. Example message:

   Topic: $oc/devices/{device_id}/sys/commands/response/request_id={request_id}
   Data format:
   {
       "result_code": 0,
       "response_name": "COMMAND_RESPONSE",
       "paras": {
           "result": "success"
       }
   }

4. The platform synchronously sends a response to the HTTP command. Example message:

   Status Code: 200 OK
   Content-Type: application/json
   
   {
     "command_id" : "b1224afb-e9f0-4916-8220-b6bab568e888",
     "response" : {
       "result_code" : 0,
       "response_name" : "COMMAND_RESPONSE",
       "paras" : {
         "result" : "success"
       }
     }
   }

Message Delivery

MQTT device messages can be delivered immediately or after a delay. When a device is online, messages are delivered immediately. When a device is offline, messages are cached and delivered after the device goes online.

• Delayed Delivery

  This section describes the delayed delivery process of MQTT messages.

  

  1. An application calls the API Delivering a Device Message to send a message to the platform. Example message:

     POST https://{Endpoint}/v5/iot/{project_id}/devices/{device_id}/messages
     Content-Type: application/json
     X-Auth-Token: ********
     
     {
       "message_id": "99b32da9-cd17-4cdf-a286-f6e849cbc364",  
       "name": "messageName",  
       "message": "HelloWorld",   
       "topic": "messageDown"
     }

  2. The platform sends a 201 Created message carrying the message status PENDING to the application.
  3. The platform pushes the message result to the application through the API Pushing a Device Message Status Change Notification. Example message:

     Topic: $oc/devices/{device_id}/sys/messages/down  
     Data format:
     {  
         "resource": "device.message.status",  
         "event": "update",  
         "notify_data": {   
           "message_id": "string",   
           "name": "string",    
           "device_id": "string",    
           "status": "PENDING",   
           "timestamp": "string"  
          }
      }

  4. The device goes online.
  5. The device subscribes to the message delivery topic, which is used to receive messages. For details on the subscribed topic, see 6.
  6. The platform sends the message to the device according to the protocol specifications. The MQTT device can receive messages delivered by the platform only after subscribing to the topic corresponding to the API Delivering a Message. Example message:

     Topic: $oc/devices/{device_id}/sys/messages/down  
     Data format:
     {
         "object_device_id": "{object_device_id}",
         "name": "name",
         "id": "id",
         "content": "hello"
     }

  7. The platform pushes the final result of the message to the application. For details on the message structure, see 3.

• Immediate Delivery

  This section describes the immediate delivery process of MQTT messages.

  

  1. An application calls the API Delivering a Device Message to send a message to the platform. Example message:

     POST https://{Endpoint}/v5/iot/{project_id}/devices/{device_id}/messages
     Content-Type: application/json
     X-Auth-Token: ********
     
     {
       "message_id": "99b32da9-cd17-4cdf-a286-f6e849cbc364",  
       "name": "messageName",  
       "message": "HelloWorld",   
       "topic": "messageDown"
     }

  2. The platform sends the message to the device according to the protocol specifications. The MQTT device can receive messages delivered by the platform only after subscribing to the topic corresponding to the API Delivering a Message. Example message:

     Topic: $oc/devices/{device_id}/sys/messages/down  
     Data format:
     {
         "object_device_id": "{object_device_id}",
         "name": "name",
         "id": "id",
         "content": "hello"
     }

  3. The platform pushes the message result to the application through the API Pushing a Device Message Status Change Notification. Example message:

     Topic: $oc/devices/{device_id}/sys/messages/down  
     Data format:
     {  
         "resource": "device.message.status",  
         "event": "update",  
         "notify_data": {   
           "message_id": "string",   
           "name": "string",    
           "device_id": "string",    
           "status": "string",   
           "timestamp": "string"  
          }
      }

Message Delivery Status

Synchronous Command Delivery to an Individual MQTT Device

The platform supports command delivery to an individual MQTT device by calling the API Delivering a Device Command or creating a command delivery task on the console. This section describes how to create a command delivery task on the console.

1. Log in to the IoTDA 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.

   

   

   • The commands can be delivered only after being defined in the product model.
   • MQTT devices support only synchronous command delivery. To asynchronously deliver commands to devices using LwM2M over CoAP, see Asynchronous Command Delivery.

Currently, historical messages can be queried using APIs, but historical command delivery tasks cannot. The following table describes these APIs.

Synchronous Command Delivery to a Batch of MQTT Devices

The platform can call the API Creating a Batch Task to deliver a command to multiple MQTT devices. The process is as follows.

1. An application calls the API Creating a Batch Task to send a command to the platform. Example message:

   POST https://{Endpoint}/v5/iot/{project_id}/batchtasks 
   Content-Type: application/json
   X-Auth-Token: ********
   {
     "app_id": "84fb64e43c5f4c6cbec339e52449bcea",
     "task_name": "task123",
     "task_type": "createCommands",
     "targets": [
       "5f2bc9b961e7670469c5ef6d_1997930",
    "5f2bc9b961e7670469c5ef6d_1997931"
     ],
     "document": {
       "service_id": "water",
       "command_name": "ON_OFF",
       "paras": {
         "value": "ON"
       }
     }
   }

   • app_id: resource space ID
   • task_name: custom task name
   • task_type: createCommands
   • targets: device ID array
   • document: command-related parameters. For details, see Delivering a Device Command.
2. The platform returns a 201 Created message to the application.
3. The device subscribes to the downstream topic to receive the command and sends the command result to the platform through the upstream topic. For details, see Delivering a Command.
4. The platform calls the API Querying a Batch Task to query the execution status of the batch command delivery task.

APIs

• Delivering a Device Message
• Modifying Device Properties
• Querying Device Properties
• Delivering a Device Command
• Querying Device Messages
• Delivering a Command
• Delivering a Message
• Querying a Message by Message ID
• Pushing a Device Message Status Change Notification