All Products
Search
Document Center

IoT Platform:Data formats

Last Updated:Oct 27, 2023

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.

Table 1. Topics

Topic

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 (#).

  • All equipment (+): indicates all devices of the specified product.

  • /user/#: indicates all topics of the specified device.

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:

  • offline

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:

  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 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 codes

code

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.