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 are 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 business requirements. This topic describes the formats in which the rules engine converts the data of topics for basic communication and topics for TSL communication.
Topics that are related to the rules engine and device communication
For information about the definition, usage, and classification of communication topics, see Topics.
You must specify the format of raw data that is submitted by devices when you develop the devices. Take note of the following items:
The data of topics for basic communication and topics for TSL communication must comply with the Alink protocol that is supported by IoT Platform. For more information, see related sub-topics in the Alink protocol topic.
After the rules engine forwards raw data that is submitted by devices, the format of the raw data is converted. For more information about the data formats, see the description in this topic.
You can specify the data format of custom topics.
After the rules engine forwards raw data that is submitted by devices, the format of the raw data is not converted.
The following table describes the mapping between topics that the rules engine uses to forward data and topics to which devices submit data.
Topic | Description | References |
Table 1. TopicsTopic | Description | References |
Custom | The topic that is used to forward data in 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 is the suffix of the custom topic. The value can contain wildcard characters, including plus signs (+) and number signs (#). | Use custom topics for communication |
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/property/batch/post: This topic is used to forward device properties in batches. /${productKey}/${deviceName}/thing/event/batch/post: This topic is used to forward device events in batches. /${productKey}/${deviceName}/thing/downlink/reply/message: This topic is used to forward messages that a device returns as responses to IoT Platform commands.
| |
The following topics are used to submit raw device data: /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 messages 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. | Device Topological Relation Changes |
/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 messages when device tags are changed. Format: /${productKey}/${deviceName}/thing/deviceinfo/update. | Submit device tag changes |
/sys/${productKey}/${deviceName}/thing/deviceinfo/update: This topic is used to submit device data.
| Submit 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.
| |
/sys/${productKey}/${deviceName}/thing/event/property/history/post: This topic is used to submit historical TSL data.
| Device properties, events, and services |
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 the progress of updates.
| |
The preceding topics correspond to the following topic: /ota/device/progress/${productKey}/${deviceName}. This topic is used to submit update progress. | Submit the update progress to IoT Platform |
Submit a module version number | The topic that is used to forward messages 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/${productKey}/${deviceName}. 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 messages when the status of an OTA update batch changes. Format: /${productKey}/${packageId}/${jobId}/ota/job/status. | Submit the status data of OTA update batches |
Job Event | /sys/uid/${uid}/distribution/${jobId}/lifecycle: The topic that is used to forward notifications when the status of a device job changes.
Note The name of the instance migration task is the same as the name of the product whose data you want to migrate. | Submit the status data of data migration tasks for instances |
Submit device status
Topic: /as/mqtt/status/${productKey}/${deviceName}
You can use this topic to obtain the online or offline status of devices.
Format of data that a device submits when the device goes online:
{
"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 that a device submits when the device goes offline:
{
"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"
}
Parameters:
Parameter | Type | Description |
status | String | The status of the device. Valid values: |
iotId | String | The unique identifier of the device in IoT Platform. |
offlineReasonCode | Integer | The error code that is returned when the device goes offline. For more information, see Error codes that are related to device behaviors. |
productKey | String | The unique identifier 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 online or offline. The returned messages are not sorted by time. You need to manually sort the messages. For example, you received the following messages in sequence: Online time: 2018-08-31 10:02:28.195 Offline time: 2018-08-31 10:01:28.195 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 went online or offline. 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"
}
}
}
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 DeviceName 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 or 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 of 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 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 error message includes the cause of the failure and information about 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
}
Parameters:
Parameter | Type | Description |
identifier | String | The identifier of the event. The identifier of a custom module 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 of 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 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
}
}
Important Only the output parameters that passed verification are included in the value parameter. In this case, the checkFailedData parameter is empty. Only the output parameters that failed to be 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 failed 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"
}
Take note of the following items: 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 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 cause of the failure and the information about 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",
"items": {
"Power": [
{
"value": "on",
"time": 1524448722000
},
{
"value": "off",
"time": 1524448722001
}
],
"WF": [
{
"value": 3,
"time": 1524448722000
},
{
"value": 4,
"time": 1524448722009
}
]
}
}
Parameters:
Parameter | Type | Description |
productKey | String | The unique identifier 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. |
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
},
{
"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",
"items": {
"alarmEvent": [
{
"value": {
"Power": "on",
"WF": "2"
},
"time": 1524448722000
},
{
"value": {
"Power": "on",
"WF": "2"
},
"time": 1524448723000
}
]
}
}
Parameters:
Parameter | Type | Description |
productKey | String | The unique identifier 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. |
items | 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
}
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 DeviceName of the device. |
deviceSecret | String | The DeviceSecret of the device. This parameter is included only if the action parameter is set to 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
}
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 when the message was generated. Unit: milliseconds. |
Submit information about detected sub-devices
Topic: /${productKey}/${deviceName}/thing/list/found
In some scenarios, 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"
}
]
}
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 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"
}
}
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 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 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 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 error message includes the cause of the failure and information about the invalid parameters. |
Table 1. Response codescode | message | Description |
200 | success | The request is successful. |
400 | request error | An internal error occurred. |
460 | request parameter error | The request parameter is invalid and the device failed to verify the parameter. |
429 | too many requests | The maximum number of requests in a specified period has been reached. |
9200 | device not actived | The device is not activated. |
9201 | device offline | The device is disconnected from IoT Platform. |
403 | request forbidden | The request is rejected due to overdue payments. |
For information about how to troubleshoot issues, 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"
}
}
}
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 DeviceName 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 or 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 of 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 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 error message includes the cause of the failure and information about 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
}
Parameters:
Parameter | Type | Description |
identifier | String | The identifier of the event. The identifier of a custom module 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 of 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 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
}
}
Important Only the output parameters that passed verification are included in the value parameter. In this case, the checkFailedData parameter is empty. Only the output parameters that failed to be 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 failed 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"
}
Take note of the following items: 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 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 cause of the failure and the information about 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****"
}
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 DeviceName of the device. |
moduleName | String | The name of the OTA module. |
status | String | The status of the update. SUCCEEDED: The update task is successful. FAILED: The update task failed. : The update task is canceled.
|
messageCreateTime | Long | The timestamp 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 ID of the update batch. This parameter is used to uniquely identify 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****"
}
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 DeviceName 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 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 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
}
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 DeviceName of the device. |
moduleName | String | The name of the OTA 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
}
Parameters:
Parameter | Type | Description |
productKey | String | The unique identifier of the product to which the device belongs. |
moduleName | String | The name of the OTA 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 is not started.
IN_PROGRESS: The update is running.
COMPLETED: The update is complete.
CANCELED: The update is canceled.
UNFINISH: The update is not complete.
If the number of update attempts reaches the upper limit for an Enterprise Edition instance, the update batch is in the UNFINISH state.
|
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 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": "attrValue",
"tagKey": "tagValue"
}
],
"messageCreateTime": 1510799670074
}
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 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. |
Submit the status data of data migration tasks for instances
Topic: /sys/uid/{uid}/distribution/{jobId}/lifecycle
You can use this topic to obtain the status changes of data migration tasks for instances.
Replace ${uid} with the ID of your Alibaba Cloud account. To obtain your account ID, log on to the IoT Platform and move the pointer over the profile picture to view the account ID.
Data format:
{
"jobId": "4z819VQHk6VSLmmxxxxxxxxxxee200",
"status": "GRAY_EXECUTING",
"messageCreateTime": 1510292739881,
"type":"INSTANCE_UPGRADE",
"sourceInstance":"iotx-oxssharez200",
"targetInstance":"iot-es5v4***",
"successDevices":[
{
"productKey":"al12***",
"deviceName":"deviceName1",
"iotId":"4z81frf00107e***"
}
]
}
Parameters:
Parameter | Type | Description |
jobId | String | The ID of the task. |
status | String | The status of the task. Valid values: GRAY_EXECUTING: Partial data is being migrated.
GRAY_FINISHED: Partial data is migrated.
ALL_EXECUTING: The task is being executed.
ALL_FINISHED: The task is complete.
ALL_PAUSE: The task is paused.
ROLL_BACK_EXECUTING: The task is being rolled back.
ROLL_BACK_PAUSE: The rollback is paused.
|
messageCreateTime | Long | The timestamp that was generated for the message. Unit: milliseconds. |
type | String | The type of the task. The value is fixed to INSTANCE_UPGRADE. |
sourceInstance | String | The ID of the public instance from which data is migrated. If the public instance is of a previous version, the value is iotx-oxssharez200. For more information about IoT Platform instances, see Overview. |
targetInstance | String | The ID of the Enterprise Edition instance to which data is migrated. |
successDevices | List | The information about the devices that are migrated. If you perform a phased data migration task or a full-scale data migration task, the value of the parameter contains information about the devices that are migrated from a public instance to an Enterprise Edition instance. If you roll back a data migration task, the value of the parameter contains information about the devices that are migrated from an Enterprise Edition instance to a public instance.
|
productKey | String | The unique identifier of the product to which the device belongs. |
deviceName | String | The DeviceName of the device. |
iotId | String | The unique identifier of the device in IoT Platform. |
Elastic Compute Service (ECS)
Container Compute Service (ACS)
