The data forwarding and server-side subscription features of IoT Platform process and forward data based on the data formats of topics. Topics can be classified into custom topics, basic communication topics, and Thing Specification Language (TSL)-based topics. This topic describes the data formats of basic communication topics and TSL-based communication topics.

Topics that are related to the rules engine and device communication

In this example, the format of the data that is submitted by devices is converted by the rules engine. For more information about the formats of original data, see Alink protocol. The following table describes the topics.

Table 1. Topics
Topic Description References
Custom The topic that is used to forward data of custom formats. The format of this topic is the same as the format of a custom topic. Format: /${productKey}/${deviceName}/user/${TopicShortName}.

${TopicShortName} specifies a custom topic category, which indicates the suffix of the custom topic.

The value can contain wildcard characters, including plus signs (+) and number signs (#).

  • All equipment (+): indicates all devices of the specified product.
  • /user/#: indicates all topics of the specified device.
Custom topics
Device Status Change Notification The topic that is used to forward notifications when the status of a device changes between online and offline. Format: /as/mqtt/status/${productKey}/${deviceName}. Submit device status
TSL Data Reporting The following topics are provided:
  • /${productKey}/${deviceName}/thing/event/property/post: This topic is used to forward device properties.
  • /${productKey}/${deviceName}/thing/event/${tsl.event.identifier}/post: This topic is used to forward device events.
  • /${productKey}/${deviceName}/thing/event/property/post: This topic is used to forward multiple device properties at a time.
  • /${productKey}/${deviceName}/thing/event/batch/post: This topic is used to forward multiple device events at a time.
  • /${productKey}/${deviceName}/thing/downlink/reply/message: This topic is used to forward messages that are sent by a device as responses to IoT Platform commands.
The preceding topics correspond to the following device topics:
  • /sys/{productKey}/{deviceName}/thing/event/property/post: This topic is used to submit device properties.
  • /sys/${productKey}/${deviceName}/thing/event/${tsl.event.identifier}/post and /sys/${productKey}/${deviceName}/thing/event/${tsl.functionBlockId}:{tsl.event.identifier}/post: These topics are used to submit device events.
  • /sys/${productKey}/${deviceName}/thing/event/property/batch/post: This topic is used to submit device properties and events in batches.
Device Changes Throughout Lifecycle The topic that is used to forward notifications when a device is created, deleted, disabled, or enabled. Format: /${productKey}/${deviceName}/thing/lifecycle Submit lifecycle changes
Sub-Device Data Report Detected by Gateway The topic that is used to submit and forward the information about a new sub-device when a gateway detects the sub-device. This topic is specific to gateways. Format: /${productKey}/${deviceName}/thing/list/found Submit information about detected sub-devices
Device Topological Relation Changes The topic that is used to forward notifications when topological relationships between sub-devices and the gateway are created or deleted. This topic is specific to gateways. Format: /${productKey}/${deviceName}/thing/topo/lifecycle. Submit topology changes
The preceding topic corresponds to the following topic: /sys/{productKey}/{deviceName}/thing/topo/change. This topic is used to submit device data. Notify gateways of changes of topological relationships
Device tag change The topic that is used to forward notifications when device tags are changed. Format: /${productKey}/${deviceName}/thing/deviceinfo/update. Submit device tag changes
The preceding topic corresponds to the following topic: /sys/{productKey}/{deviceName}/thing/deviceinfo/update. This topic is used to submit device data. Report tags
TSL Historical Data Reporting The following topics are provided:
  • /${productKey}/${deviceName}/thing/event/property/history/post: This topic is used to forward historical properties.
  • /${productKey}/${deviceName}/thing/event/${tsl.event.identifier}/history/post: This topic is used to forward historical events.
The preceding topics correspond to the following topic: /sys/{productKey}/{deviceName}/thing/event/property/history/post. This topic is used to submit historical TSL data. Devices submit historical TSL data to IoT Platform
Device status notification The following topics are provided:
  • /${productKey}/${deviceName}/ota/upgrade: This topic is used to forward over-the-air (OTA) update results.
  • /${productKey}/${deviceName}/ota/progress/post: This topic is used to forward update progresses.
The preceding topics correspond to the following topic: /ota/device/progress/${YourProductKey}/${YourDeviceName}. This topic is used to submit update progresses. Submit the update progress to IoT Platform
Submit a module version number The topic that is used to forward notifications when the version number of an OTA module for a device is changed. Format: /${productKey}/${deviceName}/ota/version/post. Submit OTA module versions
The preceding topic corresponds to the following topic: /ota/device/inform/${YourProductKey}/${YourDeviceName}. This topic is used to submit the version number of an OTA module. Submit OTA module versions to IoT Platform
Batch status notification The topic to which IoT Platform sends notifications when the status of an OTA update batch changes. Format: /${productKey}/${packageId}/${jobId}/ota/job/status. Submit the status data of OTA update batches

Submit device status

Topic: /as/mqtt/status/${productKey}/${deviceName}

You can use this topic to obtain the online status or offline status of devices.

Format of data for an online device:

{
    "status":"online",
    "iotId":"4z819VQHk6VSLmmBJfrf00107e****",
    "productKey":"al12345****",
    "deviceName":"deviceName1234",
    "time":"2018-08-31 15:32:28.205",
    "utcTime":"2018-08-31T07:32:28.205Z",
    "lastTime":"2018-08-31 15:32:28.195",
    "utcLastTime":"2018-08-31T07:32:28.195Z",
    "clientIp":"192.0.2.1"
}

Format of data for an offline device:

{
    "status":"offline",
    "iotId":"4z819VQHk6VSLmmBJfrf00107e****",
    "offlineReasonCode":427,
    "productKey":"al12345****",
    "deviceName":"deviceName1234",
    "time":"2018-08-31 15:32:28.205",
    "utcTime":"2018-08-31T07:32:28.205Z",
    "lastTime":"2018-08-31 15:32:28.195",
    "utcLastTime":"2018-08-31T07:32:28.195Z",
    "clientIp":"192.0.2.1"
}

The following table describes the parameters.

Parameter Category Description
status String The device status. Valid values:
  • online: The device is online.
  • offline: The device is offline.
iotId String The ID of the device in IoT Platform.
offlineReasonCode Integer The error code returned if the device goes offline. For more information, see Device-behavior-related error codes.
productKey String The ProductKey of the product to which the device belongs.
deviceName String The DeviceName of the device.
lastTime String These parameters are no longer valid.
utcLastTime String
Time String The time when the device was connected or disconnected.

The time when a message is received from a device is different from the time when the device is connected or disconnected. You can sort messages by the value of the Time parameter.

For example, you obtain the following messages in sequence:
  1. Online time: 2018-08-31 10:02:28.195
  2. Offline time: 2018-08-31 10:01:28.195
  3. Offline time: 2018-08-31 10:03:28.195
The preceding three messages indicate that the status of a device changed to offline, online, and then offline.
utcTime String The time when the device was connected or disconnected. The time is in the UTC format.
clientIp String The public IP address of the device.

Submit device properties

Topic: /${productKey}/${deviceName}/thing/event/property/post

You can use this topic to obtain the properties that are submitted by devices.

Data format:

{
    "iotId":"4z819VQHk6VSLmmBJfrf00107e****",
    "requestId":"2",
    "productKey":"al12345****",
    "deviceName":"deviceName1234",
    "gmtCreate":1510799670074,
    "deviceType":"Ammeter",
    "items":{
        "Power":{
            "value":"on",
            "time":1510799670074
        },
        "Position":{
            "time":1510292697470,
            "value":{
                "latitude":39.9,
                "longitude":116.38
            }
        }
    },
    "checkFailedData":{
        "attribute_8":{
            "time": 1510292697470,
            "value": 715665571,
            "code":6304,
            "message":"tsl parse: params not exist -> attribute_8"
        }
    }
}

The following table describes the parameters.

Parameter Category Description
iotId String The ID of the device in IoT Platform.
requestId String The ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for the device.
productKey String The ProductKey of the product to which the device belongs.
deviceName String The DeviceName of the device.
gmtCreate Long The time when the message was generated.
deviceType String The product category of the device.
items Object The data that is submitted by the device.
Power String The identifier of the property. For more information about properties, see the TSL model of the product.
If you use the properties of a custom module, the identifier of each property is in the Module identifier:Property identifier format. A colon is used to connect the two parts of this expression. The following example shows the data format that is used if the identifier of a TSL custom module is named test:
"items":{
        "test:Power":{
            "value":"on",
            "time":1510799670074
        },
        "test:Position":{
            "time":1510292697470,
            "value":{
                "latitude":39.9,
                "longitude":116.38
            }
        }
    }
Position
attribute_8
checkFailedData Object The data that failed to be verified.
value Subject to the TSL definition The value of the resource property.
time Long The time when the property was submitted. If the device does not submit a timestamp, the timestamp when IoT Platform receives the message is used.
code Integer The error code returned if the data fails to be verified. For more information, see Error codes for devices.
message String The error message returned if the data fails to be verified. The message includes the failure cause and the invalid parameters.

Submit device events

Topic: /${productKey}/${deviceName}/thing/event/${tsl.event.identifier}/post

You can use this topic to obtain the events that are submitted by devices.

Data format:

{
    "identifier":"BrokenInfo",
    "name":"Damage rate report",
    "type":"info",
    "iotId":"4z819VQHk6VSLmmBJfrf00107e****",
    "requestId":"2",
    "productKey":"X5eCzh6****",
    "deviceName":"5gJtxDVeGAkaEztpisjX",
    "gmtCreate":1510799670074,
    "value":{
        "Power":"on",
        "Position":{
            "latitude":39.9,
            "longitude":116.38
        }
    },
    "checkFailedData":{
    },
    "time":1510799670074
}

The following table describes the parameters.

Parameter Category Description
identifier String The identifier of the event.
If you use the events of a custom module, the identifier of each property is in the Module identifier:Event identifier format. A colon is used to connect the two parts of this expression. The following example shows the data format if the identifier of a custom TSL module is test:
"test:identifier":"BrokenInfo",
name String The name of the event.
type String The type of the event. For more information about the supported event types, see the TSL model of the product.
iotId String The ID of the device in IoT Platform.
requestId String The ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for the device.
productKey String The ProductKey of the product to which the device belongs.
deviceName String The DeviceName of the device.
gmtCreate Long The time when the message was generated.
value Object The output parameters of the event. Examples: Power and Position.
{
    "Power":"on",
    "Position":{
        "latitude":39.9,
        "longitude":116.38
    }
}
Notice
  • Only the output parameters that pass verification are included in the value parameter. In this case, the checkFailedData parameter is empty.
  • Only the output parameters that fail to verified are included in the checkFailedData parameter. In this case, the value parameter is empty.
checkFailedData Object The data that failed to be verified.

If the output parameters fail to be verified, the checkFailedData parameter includes the following parameters:

{
    "value":{
        "Power":"on",
        "Position":{
            "latitude":39.9,
            "longitude":116.38
        }
    }
    "time":1524448722000,
    "code":6304,
    "message":"tsl parse: params not exist -> type"
}

Description:

  • value: Object type. The output parameters of the event.
  • time: Long type. The timestamp when the event was generated.
  • code: Integer type. The error code returned if the data fails to be verified. For more information, see Error codes for devices.
  • message: String type. The error message returned if the data fails to be verified. The message includes the failure cause and the invalid parameters.
time Long The time when the event was submitted. If the device does not submit a timestamp, the timestamp when IoT Platform receives the message is used.

Submit device properties in batches

Topic: /${productKey}/${deviceName}/thing/property/batch/post

You can use this topic to obtain the properties that are submitted by devices in batches.

Data format:

{
    "productKey": "al12345****",
    "deviceName": "deviceName1234",
    "instanceId": "iot-0***",
    "requestId": "2",
    "payload": {
        "Power": [{
                "value": "on",
                "time": 1524448722000
            },
            {
                "value": "off",
                "time": 1524448722001
            }
        ],
        "WF": [{
                "value": 3,
                "time": 1524448722000
            },
            {
                "value": 4,
                "time": 1524448722009
            }
        ]
    }
}

The following table describes the parameters.

Parameter Category Description
productKey String The ProductKey of the product to which the device belongs.
deviceName String The DeviceName of the device.
instanceId String The ID of the instance to which the device belongs.
requestId String The ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for the device.
payload Object The data that is submitted by the device.
Power String The identifier of the property. For more information about properties, see the TSL model of the product.
If you use the properties of a custom module, the identifier of each property is in the Module identifier:Property identifier format. A colon is used to connect the two parts of this expression. The following example shows the data format that is used if the identifier of a TSL custom module is named test:
"payload":{
        "test:Power":[
            {
            "value":"on",
            "time":1510799670074
            },
            {
              "value": "off", 
              "time": 1524448722001
            }],
        "test:WF":[
            {
              "value": 3, 
              "time": 1524448722000
            },
            {
              "value": 4, 
              "time": 1524448722009
            }]
        }
    }
WF
value Subject to the TSL definition The value of the resource property.
time Long The time when the property was submitted. If the device does not submit a timestamp, the timestamp when IoT Platform receives the message is used.

Submit device events in batches

Topic: /${productKey}/${deviceName}/thing/event/batch/post

You can use this topic to obtain the events that are submitted by devices in batches.

Data format:

{
    "productKey": "al12345****",
    "deviceName": "deviceName1234",
    "instanceId": "iot-0***",
    "requestId": "2",
    "payload": {
        "alarmEvent": [{
                "value": {
                    "Power": "on",
                    "WF": "2"
                },
                "time": 1524448722000
            },
            {
                "value": {
                    "Power": "on",
                    "WF": "2"
                },
                "time": 1524448723000
            }
        ]
    }
}

The following table describes the parameters.

Parameter Category Description
productKey String The ProductKey of the product to which the device belongs.
deviceName String The DeviceName of the device.
instanceId String The ID of the instance to which the device belongs.
requestId String The ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for the device.
payload Object The data that is submitted by the device.
alarmEvent List The identifier of the event.
value Object The parameters of the event.

Examples: Power and WF.

time Long The time when the event was submitted. If the device does not submit a timestamp, the timestamp when IoT Platform receives the message is used.

Submit lifecycle changes

Topic: /${productKey}/${deviceName}/thing/lifecycle

You can use this topic to receive notifications when devices are created, deleted, enabled, or disabled.

Data format:

{
    "action": "create|delete|enable|disable",
    "iotId": "4z819VQHk6VSLmmBJfrf00107e****",
    "productKey": "al5eCzh****",
    "deviceName": "5gJtxDVeGAkaEztpisjX",
    "deviceSecret": "wsde***", 
    "messageCreateTime": 1510292739881 
}

The following table describes the parameters.

Parameter Category Description
action String
  • create: creates a device
  • delete: deletes a device
  • enable: enables a device
  • disable: disables a device
iotId String The ID of the device in IoT Platform.
productKey String The ProductKey of the product to which the device belongs.
deviceName String The DeviceName of the device.
deviceSecret String The DeviceSecret of the device. This parameter is available only if the action parameter is set to create.
messageCreateTime Integer The timestamp that was generated for the message. Unit: milliseconds.

Submit topology changes

Topic: /${productKey}/${deviceName}/thing/topo/lifecycle

You can use this topic to receive notifications when topological relationships between sub-devices and gateways are created or deleted.

Data format:

{
    "action" : "create|delete|enable|disable",
    "gwIotId": "dfaejVQHk6VSLmmBJfrf00107e****",
    "gwProductKey": "al5eCzh****",
    "gwDeviceName": "deviceName1234",
    "devices": [ 
        {
          "iotId": "4z819VQHk6VSLmmBJfrf00107e****",
          "productKey": "ala4Czh****",
          "deviceName": "deviceName1234"
       }
    ],
    "messageCreateTime": 1510292739881 
}

The following table describes the parameters.

Parameter Category Description
action String
  • create: creates a topology
  • delete: deletes a topology
  • enable: enables a topology
  • disable: disables a topology
gwIotId String The ID of the gateway in IoT Platform.
gwProductKey String The ProductKey of the product to which the gateway belongs.
gwDeviceName String The name of the gateway.
devices Object The sub-devices whose topologies are changed.
iotId String The ID of each sub-device in IoT Platform.
productKey String The ProductKey of the product to which the sub-device belongs.
deviceName String The name of the sub-device.
messageCreateTime Integer The timestamp that was generated for the message. Unit: milliseconds.

Submit information about detected sub-devices

Topic: /${productKey}/${deviceName}/thing/list/found

In some cases, gateways can detect sub-devices and submit sub-device information. You can use this topic to obtain the submitted information.

Data format:

{
    "gwIotId":"dfaew9VQHk6VSLmmBJfrf00107e****",
    "gwProductKey":"al12345****",
    "gwDeviceName":"deviceName1234",
    "devices":[
        {
            "iotId":"4z819VQHk6VSLmmBJfrf00107e****",
            "productKey":"alr56g9****",
            "deviceName":"deviceName1234"
        }
    ]
}

The following table describes the parameters.

Parameter Category Description
gwIotId String The ID of the gateway in IoT Platform.
gwProductKey String The ProductKey of the product to which the gateway belongs.
gwDeviceName String The name of the gateway.
devices Object The sub-devices that are detected by the gateway.
iotId String The ID of each sub-device in IoT Platform.
productKey String The ProductKey of the product to which the sub-device belongs.
deviceName String The name of the sub-device.

Submit responses to downstream requests

Topic: /${productKey}/${deviceName}/thing/downlink/reply/message

You can use this topic to obtain the results that are returned after devices process downstream requests. IoT Platform sends the downstream requests to the devices in an asynchronous manner. If errors occur when IoT Platform sends the downstream requests, you can also use this topic to obtain error messages.

Data format:

{
    "gmtCreate":1510292739881,
    "iotId":"4z819VQHk6VSLmmBJfrf00107e****",
    "productKey":"al12355****",
    "deviceName":"deviceName1234",
    "requestId":"2",
    "code":200,
    "message":"success",
    "topic":"/sys/al12355****/deviceName1234/thing/service/property/set",
    "data":{

    },
    "checkFailedData":{
        "value": {
            "PicID": "15194139"
        },
        "code":6304,
        "message":"tsl parse: params not exist -> PicID"
    }
}

The following table describes the parameters.

Parameter Category Description
gmtCreate Long The timestamp in UTC.
iotId String The ID of the device in IoT Platform.
productKey String The ProductKey of the product to which the device belongs.
deviceName String The DeviceName of the device.
requestId String The ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for the device.
code Integer The response code that is returned by the device. For more information, see the following Response codes table.
message String The message that is returned by the device.
topic String The information about the topic that is used to send the downstream request.
data Object The data that is returned by the device. If the device returns Alink data, you do not need to parse the data. If the device returns pass-through data, you must parse the data by using a data parsing script.
checkFailedData Object The data that failed to be verified.
value Subject to the TSL definition The property or service parameter whose value failed to be verified.

Example: PicID.

code Integer The error code returned if the data fails to be verified. For more information, see Error codes for devices.
message String The error message returned if the data fails to be verified. The message includes the failure cause and the invalid parameters.
Table 2. Response codes
code message Description
200 success The message returned because the request is successful.
400 request error The error message returned because an internal error occurred.
460 request parameter error The error message returned because the request parameter is invalid and the device failed to verify the parameter.
429 too many requests An excessive number of requests are submitted within a specific period of time.
9200 device not actived The device is not activated.
9201 device offline The device is offline.
403 request forbidden The error message returned because the request is rejected due to overdue payments.

For more information about how to troubleshoot errors, see Error codes for devices.

Submit historical properties

Topic: /${productKey}/${deviceName}/thing/event/property/history/post

You can use this topic to obtain historical properties that are submitted by devices.

Data format:

{
    "iotId":"4z819VQHk6VSLmmBJfrf00107e****",
    "requestId":"2",
    "productKey":"12345****",
    "deviceName":"deviceName1234",
    "gmtCreate":1510799670074,
    "deviceType":"Ammeter",
    "items":{
        "Power":{
            "value":"on",
            "time":1510799670074
        },
        "Position":{
            "time":1510292697470,
            "value":{
                "latitude":39.9,
                "longitude":116.38
            }
        }
    },
    "checkFailedData":{
        "attribute_8":{
            "time": 1510292697470,
            "value": 715665571,
            "code":6304,
            "message":"tsl parse: params not exist -> attribute_8"
        }
    }
}

The following section describes the parameters:

Parameter Category Description
iotId String The ID of the device in IoT Platform.
requestId String The ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for the device.
productKey String The ProductKey of the product to which the device belongs.
deviceName String The DeviceName of the device.
gmtCreate Long The time when the message was generated.
deviceType String The product category of the device.
items Object The data that is submitted by the device.
Power String The identifier of the property. For more information about properties, see the TSL model of the product.
If you use the properties of a custom module, the identifier of each property is in the Module identifier:Property identifier format. A colon is used to connect the two parts of this expression. The following example shows the data format that is used if the identifier of a TSL custom module is named test:
"items":{
        "test:Power":{
            "value":"on",
            "time":1510799670074
        },
        "test:Position":{
            "time":1510292697470,
            "value":{
                "latitude":39.9,
                "longitude":116.38
            }
        }
    }
Position
attribute_8
checkFailedData Object The data that failed to be verified.
value Subject to the TSL definition The value of the resource property.
time Long The time when the property was submitted. If the device does not submit a timestamp, the timestamp when IoT Platform receives the message is used.
code Integer The error code returned if the data fails to be verified. For more information, see Error codes for devices.
message String The error message returned if the data fails to be verified. The message includes the failure cause and the invalid parameters.

Submit historical events

Topic: /${productKey}/${deviceName}/thing/event/${tsl.event.identifier}/history/post

You can use this topic to obtain historical events that are submitted by devices.

Data format:

{
    "identifier":"BrokenInfo",
    "name":"Damage rate report",
    "type":"info",
    "iotId":"4z819VQHk6VSLmmBJfrf00107e***",
    "requestId":"2",
    "productKey":"X5eCzh6***",
    "deviceName":"5gJtxDVeGAkaEztpisjX",
    "value":{
        "Power":"on",
        "Position":{
            "latitude":39.9,
            "longitude":116.38
        }
    },
    "checkFailedData":{
    },
    "time":1510799670074
}

The following section describes the parameters:

Parameter Category Description
identifier String The identifier of the event.
If you use the events of a custom module, the identifier of each property is in the Module identifier:Event identifier format. A colon is used to connect the two parts of this expression. The following example shows the data format if the identifier of a custom TSL module is test:
"test:identifier":"BrokenInfo",
name String The name of the event.
type String The type of the event. For more information about the supported event types, see the TSL model of the product.
iotId String The ID of the device in IoT Platform.
requestId String The ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for the device.
productKey String The ProductKey of the product to which the device belongs.
deviceName String The DeviceName of the device.
gmtCreate Long The time when the message was generated.
value Object The output parameters of the event. Examples: Power and Position.
{
    "Power":"on",
    "Position":{
        "latitude":39.9,
        "longitude":116.38
    }
}
Notice
  • Only the output parameters that pass verification are included in the value parameter. In this case, the checkFailedData parameter is empty.
  • Only the output parameters that fail to verified are included in the checkFailedData parameter. In this case, the value parameter is empty.
checkFailedData Object The data that failed to be verified.

If the output parameters fail to be verified, the checkFailedData parameter includes the following parameters:

{
    "value":{
        "Power":"on",
        "Position":{
            "latitude":39.9,
            "longitude":116.38
        }
    }
    "time":1524448722000,
    "code":6304,
    "message":"tsl parse: params not exist -> type"
}

Description:

  • value: Object type. The output parameters of the event.
  • time: Long type. The timestamp when the event was generated.
  • code: Integer type. The error code returned if the data fails to be verified. For more information, see Error codes for devices.
  • message: String type. The error message returned if the data fails to be verified. The message includes the failure cause and the invalid parameters.
time Long The time when the event was submitted. If the device does not submit a timestamp, the timestamp when IoT Platform receives the message is used.

Submit the status data of over-the-air (OTA) updates

Topic: /${productKey}/${deviceName}/ota/upgrade

You can use this topic to receive notifications when OTA updates succeed or fail.

Note If an update task on a device is pending and you initiate another batch update task on the device, the most recent update task fails. In this case, the notification that is generated when the most recent update task fails is not sent to IoT Platform.

Data format:

{
    "iotId": "4z819VQHk6VSLmmBJfrf00107e****",
    "productKey": "X5eCzh6****",
    "deviceName": "deviceName1234",
    "moduleName": "default",
    "status": "SUCCEEDED|FAILED|CANCELED",
    "messageCreateTime": 1571323748000,
    "srcVersion": "1.0.1",
    "destVersion": "1.0.2",
    "desc": "success",
    "jobId": "wahVIzGkCMuAUE2gDERM02****",
    "taskId": "y3tOmCDNgpR8F9jnVEzC01****"
}

The following table describes the parameters.

Parameter Category Description
iotId String The ID of the device.
productKey String The ProductKey of the product to which the device belongs.
deviceName String The DeviceName of the device.
moduleName String The name of the OTA module.
status String The status of the update. Valid values:
  • SUCCEEDED: The update is successful.
  • FAILED: The update failed.
  • CANCELED: The update task is canceled.
messageCreateTime Long The timestamp that was generated for the message. Unit: milliseconds.
srcVersion String The firmware version before the update.
destVersion String The firmware version after the update.
desc String The description of the update.
jobId String The ID of the update batch. This parameter is used to uniquely identify the update batch.
taskId String The ID of the device update record.

Submit the progress data of OTA updates

Topic: /${productKey}/${deviceName}/ota/progress/post

You can use this topic to obtain the progress data of OTA updates.

Data format:

{
    "iotId": "4z819VQHk6VSLmmBJfrf00107e****",
    "productKey": "X5eCzh6****",
    "deviceName": "deviceName1234",
    "moduleName":"default",
    "status":"IN_PROGRESS",
    "step": "90",
    "messageCreateTime": 1571323748000,
    "srcVersion":"1.0.1",
    "destVersion":"1.0.2",
    "desc": "success",
    "jobId": "wahVIzGkCMuAUE2gDERM02****",
    "taskId": "y3tOmCDNgpR8F9jnVEzC01****"
}

The following table describes the parameters.

Parameter Category Description
iotId String The ID of the device.
productKey String The ProductKey of the product to which the device belongs.
deviceName String The DeviceName of the device.
moduleName String The name of the OTA module.
status String The status of the update. Set the value to IN_PROGRESS.
step Integer The progress of the update.
messageCreateTime Long The timestamp that was generated for the message. Unit: milliseconds.
srcVersion String The firmware version before the update.
destVersion String The firmware version after the update.
desc String The description of the update.
jobId String The ID of the update batch. This parameter is used to uniquely identify the update batch.
taskId String The ID of the device update record.

Submit OTA module versions

Topic: /${productKey}/${deviceName}/ota/version/post

You can use this topic to obtain OTA module versions that are submitted by devices. If the submitted versions are different from the previous versions, the messages that are sent to the topic are forwarded.

Data format:

{
    "iotId": "4z819VQHk6VSLmmBJfrf00107e****",
    "deviceName": "deviceName1234",
    "productKey": "X5eCzh6****",
    "moduleName": "BarcodeScanner",
    "moduleVersion": "1.0.3",
    "messageCreateTime": 1571323748000
}

The following table describes the parameters.

Parameter Category Description
iotId String The ID of the device.
productKey String The ProductKey of the product to which the device belongs.
deviceName String The DeviceName of the device.
moduleName String The name of the module.
moduleVersion String The version number of the module.
messageCreateTime Long The timestamp that was generated for the message. Unit: milliseconds.

Submit the status data of OTA update batches

Topic: /${productKey}/${packageId}/${jobId}/ota/job/status

You can use this topic to obtain the status data of OTA update batches.

Data format:

{
    "productKey": "X5eCzh6****",
    "moduleName": "BarcodeScanner",
    "packageId": "wahVIzGkCMuAUE2***",
    "jobId": "wahVIzGkCMuAUE2gDERM02****",
    "state": "IN_PROGRESS",
    "messageCreateTime": 1571323748000
}

The following table describes the parameters.

Parameter Category Description
productKey String The ProductKey of the product to which the device belongs.
moduleName String The name of the module.
packageId String The ID of the update package. The value of this parameter is the same as the value of the FirmwareId parameter that is returned when you call the CreateOTAFirmware operation to create an update package.
jobId String The ID of the update batch. This parameter is used to uniquely identify the update batch.
state String The status of the update batch. Valid values:
  • PLANNED: The update batch is not started.
  • IN_PROGRESS: The update batch is running.
  • COMPLETED: The update is complete.
  • CANCELED: The update is canceled.
messageCreateTime Long The timestamp that was generated for the message. Unit: milliseconds.

Submit device tag changes

Topic: /${productKey}/${deviceName}/thing/deviceinfo/update

You can use this topic to receive notifications when a device tag is changed.

Data format:

{
  "action": "UPDATE|DELETE|DELETEALL"
  "iotId": "4z819VQHk6VSLmmBJfrf00107e****",
  "productKey": "X5eCzh6****",
  "deviceName": "deviceName1234",
  "deletedAttrKeyList": ["abc", "def", "rng"],
  "value": [
    {
      "attrKey": "tagKey",
      "attrValue": "tagValue"
    }
  ],
  "messageCreateTime": 1510799670074
}

The following table describes the parameters.

Parameter Category Description
action String The type of the tag change. Valid values:
  • UPDATE: The tag is updated or created.
  • DELETE: The tag is deleted.
  • DELETEALL: All tags are deleted.
iotId String The ID of the device.
productKey String The ProductKey of the product to which the device belongs.
deviceName String The DeviceName of the device.
deletedAttrKeyList List The keys of the deleted tags.

This parameter is available only if the action parameter is set to DELETE.

value List The data of the tag.
attrKey String The key of the tag.
attrValue String The value of the tag.
messageCreateTime Long The timestamp that was generated for the message. Unit: milliseconds.