Help Center> IoT Device Access> User Guide> Message Communications> Command Delivery> Command, Property, and Message Delivery for MQTT Devices
Updated on 2023-01-18 GMT+08:00

Command, Property, and Message Delivery for MQTT Devices

The IoT platform supports command delivery, property setting, property query, and message delivery for MQTT devices.

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 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.
    The MQTT device can receive commands delivered by the platform only after subscribing to the topic corresponding to the API Platform 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 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"
        }
      }
    }

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 Message to a Device 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. 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 Platform 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 Message to a Device 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 Platform 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. 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

Status

Description

PENDING

If an MQTT device is offline, the platform caches the message. In this case, the task status is PENDING.

TIMEOUT

If the platform does not deliver the message in the pending state within one day, the task status changes to TIMEOUT.

DELIVERED

After the platform sends the message to the device, the task status changes to DELIVERED.

FAILED

If the platform fails to send a message to the device, the task status changes to FAILED.

Synchronous Command Delivery to an Individual MQTT Device

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

  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.

    • 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.

API

Function

Delivering a Command to a Device

This API is used by an application to deliver a command to a device. The platform sends the command to the device in synchronous mode and returns the command execution result synchronously to the application. If the device does not respond, the platform returns a timeout message to the application.

Querying Device Properties

This API is used by an application to query properties of a device.

Modifying Device Properties

This API is used by an application to modify properties of a device. The platform sends the properties to the device in synchronous mode and returns the execution result synchronously to the application.

Querying Device Messages

This API is used by an application to query messages of a device. By default, the platform stores a maximum of 20 messages for each device. If the number of messages exceeds 20, the earliest messages will be overwritten by subsequent messages.

Delivering a Message to a Device

This API is used by an application to deliver a message to a device. After an application delivers a message to the platform, the platform returns a response to the application and then sends the message to the device.

Querying a Message by Message ID

This API is used to query a message of a specified ID.

Synchronous Command Delivery to a Batch of MQTT Devices

The API Creating a Batch Task can be used to deliver a command to multiple MQTT devices. This section describes how to call this API to deliver commands in batches.

  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 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. The application calls the API Querying the Batch Task List to query the execution status of the batch command delivery task.