The data forwarding and server-side subscription features of IoT Platform process data based on the format of data that is obtained from a topic. Topics can be grouped into custom topics, basic communication topics, and Thing Specification Language (TSL)-based topics. This article describes the data formats of basic communication topics and TSL-based communication topics.

Submit device status

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

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

Data format:

{
    "status":"online|offline",
    "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":"123.123.123. ***"
}

The following table describes the parameters.

Parameter Type Description
status String The device status. Valid values:
  • online: The device is online.
  • offline: The device is offline.
productKey String The ProductKey of the product to which the device belongs.
deviceName String The name of the specified device.
time String The time when the status notification was sent.
utcTime String The time in UTC when the status notification was sent.
lastTime String The time when the last communication occurred before the status changed.

The time when a message is received from a device is not equal to the time when the device status changes. You can check the time when the status of a device changes based on the lastTime 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 three messages indicate that the status of a device changed to offline, online, and then offline.
utcLastTime String The time in UTC when the last communication occurred before the status changed.
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 retrieve the properties that are submitted by devices.

Data format:

{
    "iotId":"4z819VQHk6VSLmmBJfrf00107e****",
    "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 ID of the device in IoT Platform.
productKey String The ProductKey of the product to which the device belongs.
deviceName String The name of the specified device.
deviceType String The device type.
items Object The data that is submitted by the device.
Power String The identifier of each property. For more information about the properties, see the TSL 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. For example, if the identifier of a TSL-based custom module is test, the data format is similar to the following code.
"items":{
        "test:Power":{
            "value":"on",
            "time":1510799670074
        },
        "test:Position":{
            "time":1510292697470,
            "value":{
                "latitude":39.9,
                "longitude":116.38
            }
        }
    }
Position
attribute_8
value Subject to the TSL definition The value of the property.
time Long The time when the property was generated. If the device does not submit the timestamp, the timestamp that is generated when IoT Platform receives the message is used.
gmtCreate Long The time when the message was generated.
checkFailedData Object The data that failed to be verified.
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 cause and invalid parameters.

Submit device events

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

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

Data format:

{
    "identifier":"BrokenInfo",
    "name":"Damage rate report",
    "type":"info",
    "iotId":"4z819VQHk6VSLmmBJfrf00107e****",
    "productKey":"X5eCzh6****",
    "deviceName":"5gJtxDVeGAkaEztpisjX",
    "gmtCreate":1510799670074,
    "value":{
        "Power":"on",
        "Position":{
            "latitude":39.9,
            "longitude":116.38
        }
    },
    "checkFailedData":{
        "value": {
            "type": "onMapTrace",
            "content": "{\"tid\":\"1313701472\",\"totalCount\":2267,\"traceStart\":2266,\"pointCount\":1,\"traceValue\":\"XQAABAAFAAAAAB0AE6UAB/oAAA==\"}",
            "timestamp": "15970451390162"
        },
        "code":6304,
        "message":"tsl parse: params not exist -> type"
    },
    "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 property is in the Module identifier:Event identifier format. A colon is used to connect the two parts of this expression. For example, if the identifier of a TSL-based custom module is test, the data format is similar to the following code.
"test:identifier":"BrokenInfo",
name String The name of the event.
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 name of the specified device.
type String The type of the event. For more information about the event types, see the TSL of the product.
value Object The parameters of the event.
Power String The name of the event parameter.
Position String The name of the event parameter.
time Long The time when the event was generated. If the device does not submit the timestamp, the timestamp that is generated when IoT Platform receives the message is used.
gmtCreate Long The time when the message was generated.
checkFailedData Object The data that failed to be verified.
content String The data that failed to be verified.
timestamp Long The timestamp of when the device submitted the data.
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 cause and invalid parameters.

Submit device properties in batches

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

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

Data format:

{
    "productKey": "al12345****",
    "deviceName": "deviceName1234",
    "instanceId": "iot-0***",
    "requestId": "57b144cf-***",
    "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 ProductKey of the product to which the device belongs.
deviceName String The name of the specified device.
instanceId String The ID of the instance to which the device belongs.
requestId String The globally unique ID that is generated by IoT Platform for the request.
payload Object The data that is submitted by the device.
Power String The identifier of each property. For more information about the properties, see the TSL 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. For example, if the identifier of a TSL-based custom module is test, the data format is similar to the following code.
"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 generated. If the device does not submit the timestamp, the timestamp that is generated 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 retrieve the events that are submitted by devices.

Data format:

{
    "productKey": "al12345****",
    "deviceName": "deviceName1234",
    "instanceId": "iot-0***",
    "requestId": "57b144cf-***",
    "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 ProductKey of the product to which the device belongs.
deviceName String The name of the specified device.
instanceId String The ID of the instance to which the device belongs.
requestId String The globally unique ID that is generated by IoT Platform for the request.
payload Object The device data.
alarmEvent List The identifier of the event.
value Object The parameters of the event.
time Long The time when the event was generated. If the device does not submit the timestamp, the timestamp that is generated when IoT Platform receives the message is used.

Submit lifecycle changes

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

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

Data format:

{
    "action" : "create|delete|enable|disable",
    "iotId" : "4z819VQHk6VSLmmBJfrf00107e****",
    "productKey" : "al5eCzh****",
    "deviceName" : "5gJtxDVeGAkaEztpisjX",
    "deviceSecret" : "", 
    "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 ID of the device in IoT Platform.
productKey String The ProductKey of the product to which the device belongs.
deviceName String The name of the specified device.
deviceSecret String The DeviceSecret of the device. This parameter is available only when the action parameter is set to create.
messageCreateTime Integer The timestamp of when the message was generated. Unit: milliseconds.

Submit topology changes

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

You can use this topic to retrieve 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 Type 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 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 of 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 retrieve 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 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 retrieve the results that are returned after devices process downstream requests. IoT Platform provides an asynchronous method to send the downstream requests to devices. If errors occur when IoT Platform sends the downstream requests, you can also use this topic to retrieve error messages.

Data format:

{
    "gmtCreate":1510292739881,
    "iotId":"4z819VQHk6VSLmmBJfrf00107e****",
    "productKey":"al12355****",
    "deviceName":"deviceName1234",
    "requestId":1234,
    "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. The time is displayed 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 name of the specified device.
requestId Long The ID of the request.
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.
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 value or the value of the service parameter.
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 cause and invalid parameters.
Table 1. Status codes
code message Description
200 success The message returned because the request succeeds.
400 request error The error message returned because an internal error has occurred.
460 request parameter error The error message returned because the request parameter is invalid and the device has failed to verify the parameter.
429 too many requests The error message returned because the maximum number of requests in a specified period is 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 more information about how to fix these errors, see Error codes for devices.

Submit historical properties

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

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

Data format:

{
    "iotId":"4z819VQHk6VSLmmBJfrf00107e****",
    "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 ID of the device in IoT Platform.
productKey String The ProductKey of the product to which the device belongs.
deviceName String The name of the specified device.
gmtCreate Long The time when the message was generated.
deviceType String The type of the TSL feature. For more information, see the TSL of the product.
items Object The data that is submitted by the device.
Power String The identifier of each property. For more information about the properties, see the TSL 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. For example, if the identifier of a TSL-based custom module is test, the data format is similar to the following code.
"items":{
        "test:Power":{
            "value":"on",
            "time":1510799670074
        },
        "test:Position":{
            "time":1510292697470,
            "value":{
                "latitude":39.9,
                "longitude":116.38
            }
        }
    }
Position
attribute_8
value Subject to the TSL definition The value of the property.
time Long The time when the property was generated. If the device does not submit the timestamp, the timestamp that is generated when IoT Platform receives the message is used.
checkFailedData Object The data that failed to be verified.
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 cause and invalid parameters.

Submit historical events

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

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

Data format:

{
    "identifier":"BrokenInfo",
    "name":"Damage rate report",
    "type":"info",
    "iotId":"4z819VQHk6VSLmmBJfrf00107e****",
    "productKey":"X5eCzh6****",
    "deviceName":"5gJtxDVeGAkaEztpisjX",
    "gmtCreate":1510799670074,
    "value":{
        "Power":"on",
        "Position":{
            "latitude":39.9,
            "longitude":116.38
        }
    },
    "checkFailedData":{
        "value": {
            "type": "onMapTrace",
            "content": "{\"tid\":\"1313701472\",\"totalCount\":2267,\"traceStart\":2266,\"pointCount\":1,\"traceValue\":\"XQAABAAFAAAAAB0AE6UAB/oAAA==\"}",
            "timestamp": "15970451390162"
        },
        "code":6304,
        "message":"tsl parse: params not exist -> type"
    },
    "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 property is in the Module identifier:Event identifier format. A colon is used to connect the two parts of this expression. For example, if the identifier of a TSL-based custom module is test, the data format is similar to the following code.
"test:identifier":"BrokenInfo",
name String The name of the event.
type String The type of the event. For more information about the event types, see the TSL of the product.
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 name of the specified device.
gmtCreate Long The time when the message was generated.
value Object The parameters of the event.
Power String The name of the event parameter.
Position String The name of the event parameter.
time Long The time when the event was generated. If the device does not submit the timestamp, the timestamp that is generated when IoT Platform receives the message is used.
checkFailedData Object The data that failed to be verified.
content String The data that failed to be verified.
timestamp Long The timestamp of when the device submitted the data.
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 cause and invalid parameters.

Submit the status data of OTA updates

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

You can use this topic to retrieve notifications when firmware updates succeed or fail.

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

Data format:

{
    "iotId": "4z819VQHk6VSLmmBJfrf00107e****",
    "productKey": "X5eCzh6****",
    "deviceName": "deviceName1234",
    "status": "SUCCEEDED|FAILED",
    "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 ID of the device.
productKey String The ProductKey of the product to which the device belongs.
deviceName String The name of the specified device.
status String The status of the update.
  • SUCCEEDED: The update succeeds.
  • FAILED: The update failed.
messageCreateTime Long The timestamp of 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 ID of the device update record.

Submit OTA module versions

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

You can use this topic to retrieve 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 Type Description
iotId String The ID of the device.
productKey String The ProductKey of the product to which the device belongs.
deviceName String The name of the specified device.
moduleName String The name of the module.
moduleVersion String The version number of the module.
messageCreateTime Long The timestamp of 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 retrieve the status data of OTA update batches.

Data format:

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

The following table describes the parameters.

Parameter Type 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 operation to create an update package.
jobId String The ID of the update batch. This parameter is used to uniquely identify the update batch.
status 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 batch is completed.
  • CANCELED: The update batch is canceled.
messageCreateTime Long The timestamp of when the message was generated. Unit: milliseconds.

Submit device tag changes

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

You can use this topic to retrieve 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 Type 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 cleared.
iotId String The ID of the device.
productKey String The ProductKey of the product to which the device belongs.
deviceName String The name of the specified device.
deletedAttrKeyList List The keys of deleted tags.

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

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

Submit notifications when the status of a device task is changed.

Topic: /sys/uid/${uid}/job/${jobId}/lifecycle

You can use this topic to retrieve the status changes of device tasks. These device tasks include tasks that are used to batch set device properties, tasks that are used to batch call device services, and custom tasks.

${uid} specifies an Alibaba Cloud account ID. To view the ID, perform the following steps: Log on to the IoT Platform console, and click the profile picture in the upper-right corner of the page. The ID appears on the Security Settings page.

Data format:

{
    "jobId": "4z819VQHk6VSLmm***ee200",
    "jobType": "CUSTOM_JOB",
    "status": "INITIALIZING",
    "messageCreateTime": 1510292739881
}

The following table describes the parameters.

Parameter Type Description
jobId String The task ID. The ID is a globally unique ID for the task.
jobType String The type of the task. Valid values:
  • SET_PROPERTY: a task that is used to batch set device properties.
  • INVOKE_SERVICE: a task that is used to batch call device services.
  • CUSTOM_JOB: a custom task.
status String The task status. Valid values:
  • INITIALIZING: The task is being initialized.
  • WAITING: The task is pending. The task needs to be scheduled.
  • IN_PROGRESS: The task is running.
  • COMPLETED: The task is completed.
  • CANCELLING: The task is being canceled.
  • CANCELED: The task is canceled.
  • REMOVING: The task is being deleted.
messageCreateTime Long The timestamp of when the message was generated. Unit: milliseconds.