Synchronous Command Delivery

Introduction

You can deliver synchronous commands to MQTT devices one by one or in batches.

Synchronous Command Delivery to an Individual MQTT Device

For details on how to set and query properties, see instructions of the APIs for querying device properties and modifying device properties.

Figure 1 Command delivery flowchart

1. An application calls the API Deliver a Command to a Device 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.
   MQTT devices use the topics corresponding to the APIs for platform delivering a command to receive commands delivered by the platform. Example messages:

   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 Platform 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"
       }
     }
   }

Synchronous Command Delivery to a Batch of MQTT Devices

The API for creating a batch task can be used to deliver a command to multiple MQTT devices. The following describes how to call the API for creating a batch task to deliver commands in batches.

1. An application calls the API for 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"
       }
     }
   }

   Table 2 Parameters for creating a batch task of command delivery

   Parameter	Mandatory/Optional	Description
   app_id	Optional	Resource space ID.
   task_name	Mandatory	Custom task name.
   task_type	Mandatory	Type of the batch task. For details, see Create a Batch Task. Options: createCommands: task for creating synchronous commands in batches createAsyncCommands: task for creating asynchronous commands in batches
   targets	Optional	Device ID array, which is the target for executing the batch task.
   document	Optional	Task execution data file, in JSON format (key-value pairs). For details, see Deliver a Command to a Device.

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 Platform Delivering a Command.
4. Call the API for querying the batch task list to query the execution status of a batch command delivery task.

APIs

• Platform Delivering a Command
• Deliver a Command to a Device