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

For information about the definition, usage, and classification of communication topics, see Topics.

Topics that are related to the rules engine and device communication

The rules engine receives the raw data that is submitted by devices. This topic describes the data formats into which the raw data is converted by the rules engine.

For more information about the formats of the raw 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 changes in topological relationships
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 or offline status of devices.

Data format of the online status:

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

Data format of the offline status:

{
    "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 Type Description
status String The status of the device. Valid values:
  • online: The device is online.
  • offline: The device is offline.
iotId String The unique identifier of the device in IoT Platform.
offlineReasonCode Integer The error code that is returned when the device is disconnected. For more information, see Device behavior-related error codes.
productKey String The unique identifier of the product to which the device belongs.
deviceName String The name 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 IoT Platform receives a device status change message 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 receive 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 messages indicate that the device was disconnected, reconnected, and then disconnected again.
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 Type Description
iotId String The unique identifier 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 unique identifier of the product to which the device belongs.
deviceName String The name of the device.
gmtCreate Long The time when the message was generated.
deviceType String The product category of the device.

You can specify the product category when you create a product in IoT Platform. For more information, see Create a product and CreateProduct.

items Object The data that is submitted by the device.
Power String The identifiers of the properties. 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 the expression. The following example shows the data format for a custom module whose identifier is 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 property.
time Long The time when the property was submitted. If the device does not submit a timestamp, the timestamp that indicates when IoT Platform received the message is used.
code Integer The error code that is returned when the data fails to be verified. For more information, see Error codes for devices.
message String The error message that is returned when the data fails to be verified. The message includes the cause of the failure 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 reporting",
    "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 Type Description
identifier String The identifier of the event.
If you use the events of a custom module, the identifier of each event is in the ${Module identifier}:${Event identifier} format. A colon is used to connect the two parts of the expression. The following example shows the data format for a custom module whose identifier is test:
"test:identifier":"BrokenInfo",
name String The name of the event.
type String The type of the event. For information about the supported event types, see the TSL model of the product.
iotId String The unique identifier 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 unique identifier of the product to which the device belongs.
deviceName String The name 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 the verification are included in the value parameter. In this case, the checkFailedData parameter is empty.
  • Only the output parameters that fail the verification 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 the verification, 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 that indicates when the event was generated.
  • code: Integer type. The error code that is returned when the data fails to be verified. For more information, see Error codes for devices.
  • message: String type. The error message that is returned when the data fails to be verified. The message includes the cause of the failure and the invalid parameters.
time Long The time when the event was submitted. If the device does not submit a timestamp, the timestamp that indicates when IoT Platform received 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 Type Description
productKey String The unique identifier of the product to which the device belongs.
deviceName String The name 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 identifiers of the properties. 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 the expression. The following example shows the data format for a custom module whose identifier is 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 property.
time Long The time when the property was submitted. If the device does not submit a timestamp, the timestamp that indicates when IoT Platform received 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 Type Description
productKey String The unique identifier of the product to which the device belongs.
deviceName String The name 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 that indicates when IoT Platform received the message is used.

Submit lifecycle changes

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

You can use this topic to receive messages that are generated 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 Type Description
action String
  • create: creates a device.
  • delete: deletes a device.
  • enable: enables a device.
  • disable: disables a device.
iotId String The unique identifier of the device in IoT Platform.
productKey String The unique identifier of the product to which the device belongs.
deviceName String The name of the device.
deviceSecret String The DeviceSecret of the device. This parameter is available only if the value of the action parameter is create.
messageCreateTime Integer The timestamp that indicates when the message was generated. Unit: milliseconds.

Submit changes in topological relationships

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

You can use this topic to receive messages that are generated 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 Type Description
action String
  • create: creates a topological relationship.
  • delete: deletes a topological relationship.
  • enable: enables a topological relationship.
  • disable: disables a topological relationship.
gwIotId String The unique identifier of the gateway in IoT Platform.
gwProductKey String The unique identifier of the product to which the gateway belongs.
gwDeviceName String The name of the gateway.
devices Object The sub-devices whose topological relationships are changed.
iotId String The unique identifier of the sub-device in IoT Platform.
productKey String The unique identifier of the product to which the sub-device belongs.
deviceName String The name of the sub-device.
messageCreateTime Integer The timestamp that indicates when the message was generated. 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 Type Description
gwIotId String The unique identifier of the gateway in IoT Platform.
gwProductKey String The unique identifier 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 unique identifier of the sub-device in IoT Platform.
productKey String The unique identifier 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 Type Description
gmtCreate Long The timestamp in the UTC format.
iotId String The unique identifier of the device in IoT Platform.
productKey String The unique identifier of the product to which the device belongs.
deviceName String The name 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 Table 2 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 parser 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 that is returned when the data fails to be verified. For more information, see Error codes for devices.
message String The error message that is returned when the data fails to be verified. The message includes the cause of the failure 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 The error message returned because the maximum number of requests in a specified period has been reached.
9200 device not actived The error message returned because the device is not activated.
9201 device offline The error message returned because the device is disconnected from IoT Platform.
403 request forbidden The error message returned because the request is rejected due to overdue payments.

For 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 table describes the parameters.

Parameter Type Description
iotId String The unique identifier 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 unique identifier of the product to which the device belongs.
deviceName String The name of the device.
gmtCreate Long The time when the message was generated.
deviceType String The product category of the device.

You can specify the product category when you create a product in IoT Platform. For more information, see Create a product and CreateProduct.

items Object The data that is submitted by the device.
Power String The identifiers of the properties. 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 the expression. The following example shows the data format for a custom module whose identifier is 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 property.
time Long The time when the property was submitted. If the device does not submit a timestamp, the timestamp that indicates when IoT Platform received the message is used.
code Integer The error code that is returned when the data fails to be verified. For more information, see Error codes for devices.
message String The error message that is returned when the data fails to be verified. The message includes the cause of the failure 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 reporting",
    "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 table describes the parameters.

Parameter Type Description
identifier String The identifier of the event.
If you use the events of a custom module, the identifier of each event is in the ${Module identifier}:${Event identifier} format. A colon is used to connect the two parts of the expression. The following example shows the data format for a custom module whose identifier is test:
"test:identifier":"BrokenInfo",
name String The name of the event.
type String The type of the event. For information about the supported event types, see the TSL model of the product.
iotId String The unique identifier 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 unique identifier of the product to which the device belongs.
deviceName String The name 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 the verification are included in the value parameter. In this case, the checkFailedData parameter is empty.
  • Only the output parameters that fail the verification 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 the verification, 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 that indicates when the event was generated.
  • code: Integer type. The error code that is returned when the data fails to be verified. For more information, see Error codes for devices.
  • message: String type. The error message that is returned when the data fails to be verified. The message includes the cause of the failure and the invalid parameters.
time Long The time when the event was submitted. If the device does not submit a timestamp, the timestamp that indicates when IoT Platform received 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 messages that are generated when OTA updates succeed or fail.

Note If an update task on a device is in the pending state and you start another batch update task on the device, the most recent update task fails. In this case, the message 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 Type Description
iotId String The unique identifier of the device in IoT Platform.
productKey String The unique identifier of the product to which the device belongs.
deviceName String The name of the device.
moduleName String The name of the OTA module.
status String The status of the update. Valid values:
  • SUCCEEDED: The update was successful.
  • FAILED: The update failed.
  • CANCELED: The update was canceled.
messageCreateTime Long The timestamp that indicates when the message was generated. 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 unique identifier of the update batch.
taskId String The unique identifier 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 Type Description
iotId String The unique identifier of the device in IoT Platform.
productKey String The unique identifier of the product to which the device belongs.
deviceName String The name of the device.
moduleName String The name of the OTA module.
status String The status of the update. The value is fixed to IN_PROGRESS.
step Integer The progress of the update.
messageCreateTime Long The timestamp that indicates when the message was generated. 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 unique identifier of the update batch.
taskId String The unique identifier 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. Messages are forwarded when the versions that are submitted by devices are different from the previous versions.

Data format:

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

The following table describes the parameters.

Parameter Type Description
iotId String The unique identifier of the device in IoT Platform.
productKey String The unique identifier of the product to which the device belongs.
deviceName String The name of the device.
moduleName String The name of the module.
moduleVersion String The version number of the module.
messageCreateTime Long The timestamp that indicates when the message was generated. 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 Type Description
productKey String The unique identifier 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 unique identifier of 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 indicates when the message was generated. Unit: milliseconds.

Submit device tag changes

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

You can use this topic to receive messages that are generated when device tags are 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 Type Description
action String The type of the tag change. Valid values:
  • UPDATE: The tag is updated or a tag is created.
  • DELETE: The tag is deleted.
  • DELETEALL: All tags are deleted.
iotId String The unique identifier of the device in IoT Platform.
productKey String The unique identifier of the product to which the device belongs.
deviceName String The name of the device.
deletedAttrKeyList List The keys of the deleted tags.

This parameter is available only if the value of the action parameter is 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.