Device properties, events, and services - IoT Platform - Alibaba Cloud Documentation Center

After you define a Thing Specification Language (TSL) model for a product, the devices that belong to the product can submit property data and event data to IoT Platform based on the TSL model. You can send commands to the devices to modify the device properties and call services in the IoT Platform console.

For more information about the data formats of properties, events, and services that are defined in TSL models, see What is a TSL model?

A device submits data in the Alink JSON format to IoT Platform or uses the custom mode to submit data. We recommend that you configure the device to submit data in the Alink JSON format.

Alink JSON: a standard data format that is defined by IoT Connectivity Alliance (ICA). Devices generate data in the Alink JSON format, and then submit the data to IoT Platform. For more information, see the examples in this topic.
Custom: If the custom mode is used, devices can send raw data, such as binary data streams, to IoT Platform. Then, IoT Platform parses the raw data to the Alink JSON format based on the custom script that you submitted to IoT Platform. For more information, see Message parsing. The data that is generated by IoT Platform in the Alink JSON format is converted into binary data based on the scripts that you submitted. Then, the binary data is sent to the devices.

Important

If the TSL data is of the float or double type, the parameter values that correspond to the TSL data contain at least one decimal place. Examples: 10.0 and 11.1.
A device can submit data of TSL properties and TSL events only in the next 24 hours. The time value specified when a device submits a property value or event must be within 24 hours after the actual submission time. If the time limit is exceeded, the submission fails.
The ID of each message for downstream or upstream communication must be unique in the daily messages of a device. The id parameter specifies a message ID.
The ID of each downstream message sent from IoT Platform is used to match each response returned from a device in an asynchronous manner. IoT Platform must ensure that the ID of each downstream message is unique in the daily messages of a device. Make sure that the ID of each upstream message sent from a device is unique in the daily messages of the device.

Devices submit property data to IoT Platform

For more information how a device submits property data, see Submit device properties or events.

Topics and data formats used to send data from devices to IoT Platform:

Custom

Topic

Data formats

Request topic: /sys/${productKey}/${deviceName}/thing/model/up_raw

A request contains the raw data that a device must submit to IoT Platform.

Note

Hexadecimal data is submitted over Message Queuing Telemetry Transport (MQTT).
The submitted data must contain the method parameter that specifies the request method. The value of the parameter must be the same as the request method that you specified in the data parsing script. For example, in the Sample JavaScript script topic, the data that a device needs to submit to IoT Platform must contain the method parameter. The value of the parameter must be the same as the thing.event.property.post value that you specified for the ALINK_PROP_REPORT_METHOD parameter in a data parsing script.

Example:

0x00002233441232013fa00000

Response topic: /sys/${productKey}/${deviceName}/thing/model/up_raw_reply

Sample responses:

Sample success response

{
    "code": 200,
    "data": {},
    "id": "123",
    "message": "success",
    "version": "1.0"
}

Sample failure response

{
    "code": 6813,
    "data": {},
    "id": "123",
    "message": "topic illegal",
    "version": "1.0"
}

Alink JSON

Topic

Data formats

Request topic: /sys/${productKey}/${deviceName}/thing/event/property/post

Sample request:

{
    "id": "123",
    "version": "1.0",
    "sys":{
        "ack":0
    },
    "params": {
        "Power": {
            "value": "on",
            "time": 1524448722000
        },
        "WF": {
            "value": 23.6,
            "time": 1524448722000
        }
    },
    "method": "thing.event.property.post"
}

Response topic: /sys/${productKey}/${deviceName}/thing/event/property/post_reply

Sample responses:

Sample success response

{
    "code": 200,
    "data": {},
    "id": "123",
    "message": "success",
    "method": "thing.event.property.post",
    "version": "1.0"
}

Sample failure response

{
    "code": 6813,
    "data": {},
    "id": "123",
    "message": "The format of result is error!",
    "method": "thing.event.property.post",
    "version": "1.0"
}

Parameters:

Table 1. Request parameters
Parameter	Type	Description
id	String	The ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for the device.
version	String	The version number of the protocol. Set the value to 1.0.
sys	Object	The parameter for extended features. The value contains the fields for each feature. Note If no extended features are configured when you use a device SDK to develop device features, this parameter is unavailable. The extended features use the default configurations.
ack	Integer	The extended feature field in the sys parameter. This field specifies whether IoT Platform returns response data for a registration request. Valid values: 1: IoT Platform returns response data. 0: IoT Platform does not return response data. Important For more information about the parameter, see Examples on how to use a TSL model. If the feature is not configured, this parameter is unavailable. By default, IoT Platform returns response data for a registration request.
method	String	The request method. Example: thing.event.property.post
params	Object	The property data that a device must submit in the request. In the preceding example, the device submits information about the Power (power supply) and WF (working current) properties. The information contains the value of the property and a timestamp. The timestamp indicates the point in time at which the property is submitted. If you specify only the property value, the information does not contain the timestamp. Example: `"params": { "Power": "on", "WF": 23.6 }` 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. Example: `"test:Power": { "value": "on", "time": 1524448722000 }`
time	Long	The UTC timestamp when the property is submitted. Unit: milliseconds. This parameter is optional. You can determine whether to specify the timestamp in requests based on your business requirements. If a device frequently sends messages to IoT Platform, we recommend that you specify the timestamp in requests to help you identify the order of messages. If a request contains the time parameter, IoT Platform saves the parameter value as the point in time at which the property is submitted. If a request does not contain the time parameter, IoT Platform automatically generates a timestamp to record the point in time at which the property is submitted.
value	Object	The value of the property that is submitted by a device. This parameter is required only when you specify the time parameter. You can also submit a property value without specifying the time parameter.

Table 2. Response parameters
Parameter	Type	Description
id	String	The ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for the device.
code	Integer	The status code. For more information, see Common codes on devices. Note IoT Platform verifies all properties that are submitted by devices. IoT Platform checks whether the format of each property complies with the format that is defined in the TSL model. If a property is invalid, IoT Platform discards the property and returns an error code.
data	Object	If the request is successful, this parameter is left empty.
message	String	The response message. If the request is successful, the "success" message is displayed.
method	String	The request method in the response. The parameter value is the same as the value of the method parameter in the request.
version	String	The version number of the protocol. The parameter value is the same as the value of the version parameter in the request.

Error codes: IoT Platform may return error codes to devices. For more information, see Error codes for devices.

Data forwarding: IoT Platform can forward property data that is submitted by devices to your server or other Alibaba Cloud services by using the server-side subscription or data forwarding feature. For more information about the relevant topics and data formats, see Submit device properties.

Configure device properties

You can call the SetDeviceProperty or SetDevicesProperty operation to send commands to devices to modify device properties. For more information about how to configure a device property, see Invoke device services or configure device properties.

Important

The success message only indicates that the device received the command for changing the property value from IoT Platform. The device may not run the command. After the Link SDK that is used to configure the device responds to the property configuration request, the device must submit the latest property value to prove that the property value is changed. For more information, see the "Devices submit property data to IoT Platform" section of this topic.

Topics and data formats used to send data from IoT Platform to devices:

Data format (from IoT Platform to devices)	Request and response topics
Custom	Request topic: `/sys/${productKey}/${deviceName}/thing/model/down_raw` Response topic: `/sys/${productKey}/${deviceName}/thing/model/down_raw_reply`
Alink JSON	Request topic: `/sys/${productKey}/${deviceName}/thing/service/property/set` Response topic: `/sys/${productKey}/${deviceName}/thing/service/property/set_reply`

Sample request:

{
    "id": "123",
    "version": "1.0",
    "params": {
        "temperature": "30.5"
    },
    "method": "thing.service.property.set"
}

Sample responses:

Sample success response

{
    "code": 200,
    "data": {},
    "id": "123",
    "message": "success",
    "version": "1.0"
}

Sample failure response

{
    "code": 9201,
    "data": {},
    "id": "123",
    "message": "device offLine",
    "version": "1.0"
}

Parameters:

Table 3. Request parameters
Parameter	Type	Description
id	String	The ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for the device.
version	String	The version number of the protocol. Set the value to 1.0.
params	Object	The properties that you want to modify. In the preceding example, { "temperature": "30.5" } indicates you set the temperature property to 30.5. If the property that you want to modify is a custom module property, enter the property identifier in the format of ${Module identifier}:${Property identifier}. Example: `{ "test:temperature": "30.5" }`. A colon (:) is used to connect the two parts of this expression.
method	String	The request method. Example: thing.service.property.set

Table 4. Response parameters
Parameter	Type	Description
id	String	The ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for the device.
code	Integer	The status code. For more information, see Common codes on devices.
data	Object	If the request is successful, this parameter is left empty.
message	String	The response message. If the request is successful, the "success" message is displayed.
version	String	The version number of the protocol. The parameter value is the same as the value of the version parameter in the request.

Error codes: IoT Platform may return error codes to devices. For more information, see Error codes for devices.

Data forwarding: IoT Platform can forward property modification results to your server or other Alibaba Cloud services by using the server-side subscription or data forwarding feature. For more information about the relevant topics and data formats, see Submit responses to downstream requests.

Devices submit events to IoT Platform

For more information about how a device submits events, see Submit device properties or events.

Topics and data formats used to send data from devices to IoT Platform:

Custom

Topic

Data format

Request topic: /sys/${productKey}/${deviceName}/thing/model/up_raw

A request contains the raw data that a device must submit to IoT Platform.

Note

The submitted data must contain the method parameter that specifies the request method. The value of the parameter must be the same as the request method that you specified in the data parsing script. For example, you can set the method parameter to thing.event.${tsl.event.identifier}.post.

Example:

0xff0000007b00

Response topic: /sys/${productKey}/${deviceName}/thing/model/up_raw_reply

Sample responses:

Sample success response

{
    "code": 200,
    "data": {},
    "id": "123",
    "message": "success",
    "version": "1.0"
}

Sample failure response

{
    "code": 6813,
    "data": {},
    "id": "123",
    "message": "topic illegal",
    "version": "1.0"
}

Alink JSON

TSL module

Topic

Data format

Default module

Request topic: /sys/${productKey}/${deviceName}/thing/event/${tsl.event.identifier}/post
Response topic: /sys/${productKey}/${deviceName}/thing/event/${tsl.event.identifier}/post_reply

Sample request in the Alink JSON format if the default TSL module is used:

{
    "id": "123",
    "version": "1.0",
    "sys":{
        "ack":0
    },
    "params": {
        "value": {
            "Power": "on",
            "WF": "2"
        },
        "time": 1524448722000
    },
    "method": "thing.event.${tsl.event.identifier}.post"
}

Sample response in the Alink JSON format:

{
    "code": 200,
    "data": {},
    "id": "123",
    "message": "success",
    "method": "thing.event.${tsl.event.identifier}.post",
    "version": "1.0"
}

If the request fails, {} is returned.

Custom module

Request topic: /sys/${productKey}/${deviceName}/thing/event/${tsl.functionBlockId}:{tsl.event.identifier}/post
Response topic: /sys/${productKey}/${deviceName}/thing/event/${tsl.functionBlockId}:{tsl.event.identifier}/post_reply

Parameters:

Table 5. Request parameters
Parameter	Type	Description
id	String	The ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for the device.
version	String	The version number of the protocol. Set the value to 1.0.
sys	Object	The parameter for extended features. The value contains the fields for each feature. Note If no extended features are configured when you use a device SDK to develop device features, this parameter is unavailable. The extended features use the default configurations.
ack	Integer	The extended feature field in the sys parameter. This field specifies whether IoT Platform returns response data for a registration request. Valid values: 1: IoT Platform returns response data. 0: IoT Platform does not return response data. Important For more information about the parameter, see Examples on how to use a TSL model. If the feature is not configured, this parameter is unavailable. By default, IoT Platform returns response data for a registration request.
method	String	The request method. Default module Set the value to `thing.event.${tsl.event.identifier}.post`. Custom module Set the value to `thing.event.${tsl.functionBlockId}:${tsl.event.identifier}.post`. Note `${tsl.event.identifier}` specifies the identifier of the event that is defined in the TSL model, and `${tsl.functionBlockId}` specifies the identifier of the custom module. For more information, see Add a TSL feature.
params	Object	The parameters of the event.
value	Object	The values of the parameters of the event. The preceding example shows the information about the Power (power supply) and WF (working current) parameters. `{ "Power": "on", "WF": "2" }`
time	Long	The UTC timestamp when the event is submitted. Unit: milliseconds. This parameter is optional. You can determine whether to specify the timestamp in requests based on your business requirements. If a device frequently sends messages to IoT Platform, we recommend that you specify the time parameter in requests to help you identify the order of messages. If a request contains the time parameter, IoT Platform saves the parameter value as the point in time at which the event is submitted. If a request does not contain the time parameter, IoT Platform automatically generates a timestamp to record the point in time at which the event is submitted.

Table 6. Response parameters
Parameter	Type	Description
id	String	The ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for the device.
code	Integer	The status code. For more information, see Common codes on devices. Note IoT Platform verifies all events that are submitted by devices. IoT Platform checks whether the data format of each event complies with the format that is defined in the TSL model. If an event is invalid, IoT Platform discards it and returns an error code.
data	Object	If the request is successful, this parameter is left empty.
message	String	The response message. If the request is successful, the "success" message is displayed.
method	String	The request method in the response. The parameter value is the same as the value of the method parameter in the request.
version	String	The version number of the protocol. The parameter value is the same as the value of the version parameter in the request.

Example in the Alink JSON format: An alarm event is defined in a TSL model. For more information, see What is a TSL model?

{
    "schema": "https://iot-tsl.oss-cn-shanghai.aliyuncs.com/schema.json",
    "link": "/sys/${productKey}/airCondition/thing/",
    "profile": {
        "productKey": "${productKey}",
        "deviceName": "airCondition"
    },
    "events": [
        {
            "identifier": "alarm",
            "name": "alarm",
            "desc": "Fan alert",
            "type": "alert",
            "required": true,
            "outputData": [
                {
                    "identifier": "errorCode",
                    "name": "Error code",
                    "dataType": {
                        "type": "text",
                        "specs": {
                            "length": "255"
                        }
                    }
                }
            ],
            "method": "thing.event.alarm.post"
        }
    ]
}

The device submits the event in the following request of the Alink JSON data format.

{
    "id": "123",
    "version": "1.0",
    "params": {
        "value": {
            "errorCode": "error"
        },
        "time": 1524448722000
    },
    "method": "thing.event.alarm.post"
}

Error codes: IoT Platform may return error codes to devices. For more information, see Error codes for devices.

Data forwarding: IoT Platform can forward event information that is submitted by devices to your server or other Alibaba Cloud services by using the server-side subscription or data forwarding feature. For more information about the relevant topics and data formats, see Data formats.

Call device services in asynchronous mode

IoT Platform allows you to call services in synchronous mode or asynchronous mode. When you define a service in a TSL model, you must specify the mode in which the service can be called. For more information about how to define a service, see Add a TSL feature. For more information about how to invoke a device service, see Invoke device services or configure device properties.

Synchronous mode: You can call the InvokeThingService or InvokeThingsService operation to invoke services of a device. IoT Platform uses the Revert-Remote Procedure Call (RRPC) synchronous communication mechanism to send the request to the device. If you invoke a service in synchronous mode, IoT Platform subscribes to the RRPC topic. For more information, see What is RRPC?
Asynchronous mode: You can call the InvokeThingService or InvokeThingsService operation to invoke services of a device. IoT Platform asynchronously send the request to the device. Then, the device asynchronously returns a response If you invoke a service in asynchronous mode, IoT Platform subscribes to the asynchronous response topic.

Topics and data formats used to send data from IoT Platform to devices:

Data format (from IoT Platform to devices)	Request and response topics
Custom	Request topic: `/sys/${productKey}/${deviceName}/thing/model/down_raw` Response topic: `/sys/${productKey}/${deviceName}/thing/model/down_raw_reply`
Alink JSON	Default TSL module Request topic: `/sys/${productKey}/${deviceName}/thing/service/${tsl.service.identifier}` Response topic: `/sys/${productKey}/${deviceName}/thing/service/${tsl.service.identifier}_reply` Custom module Request topic: `/sys/${productKey}/${deviceName}/thing/service/${tsl.functionBlockId}:${tsl.service.identifier}` Response topic: `/sys/${productKey}/${deviceName}/thing/service/${tsl.functionBlockId}:${tsl.service.identifier}_reply`

Sample request in the Alink JSON format:

{
    "id": "123",
    "version": "1.0",
    "params": {
        "Power": "on",
        "WF": "2"
    },
    "method": "thing.service.${tsl.service.identifier}"
}

Sample responses:

Sample success response

{
    "code": 200,
    "data": {},
    "id": "123",
    "message": "success",
    "version": "1.0"
}

Sample failure response

{
    "code": 9201,
    "data": {},
    "id": "123",
    "message": "device offLine",
    "version": "1.0"
}

Parameters:

Table 7. Request parameters
Parameter	Type	Description
id	String	The ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for the device.
version	String	The version number of the protocol. Set the value to 1.0.
params	Object	The parameters that are used to call the service. Each parameter consists of the service identifier and value of a service. The preceding example contains the Power (power supply) and WF (working current) parameters. `{ "Power": "on", "WF": "2" }`
method	String	The request method. Default module Set the value to `thing.service.${tsl.service.identifier}`. Custom module Set the value to `thing.service.${tsl.functionBlockId}:${tsl.service.identifier}`. Note `${tsl.service.identifier}` specifies the service identifier that is defined in the TSL model, and `${tsl.functionBlockId}` specifies the identifier of the custom module. For more information, see Add a TSL feature.

Table 8. Response parameters
Parameter	Type	Description
id	String	The ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for the device.
code	Integer	The status code. For more information, see Common codes on devices.
data	Object	The response message. The value of this parameter varies based on the TSL model. If the service does not return a response, this parameter is left empty. If the service returns a response, the returned data complies with the format of the service that is defined in the TSL model.
message	String	The response message. If the request is successful, the "success" message is displayed.
version	String	The version number of the protocol. The parameter value is the same as the value of the version parameter in the request.

Example in the Alink JSON format: The SetWeight service is defined in the following TSL model.

{
    "schema": "https://iotx-tsl.oss-ap-southeast-1.aliyuncs.com/schema.json",
    "profile": {
        "productKey": "testProduct01"
    },
    "services": [
        {
            "outputData": [
                {
                    "identifier": "OldWeight",
                    "dataType": {
                        "specs": {
                            "unit": "kg",
                            "min": "0",
                            "max": "200",
                            "step": "1"
                        },
                        "type": "double"
                    },
                    "name": "OldWeight"
                },
                {
                    "identifier": "CollectTime",
                    "dataType": {
                        "specs": {
                            "length": "2048"
                        },
                        "type": "text"
                    },
                    "name": "CollectTime"
                }
            ],
            "identifier": "SetWeight",
            "inputData": [
                {
                    "identifier": "NewWeight",
                    "dataType": {
                        "specs": {
                            "unit": "kg",
                            "min": "0",
                            "max": "200",
                            "step": "1"
                        },
                        "type": "double"
                    },
                    "name": "NewWeight"
                }
            ],
            "method": "thing.service.SetWeight",
            "name": "Set weight",
            "required": false,
            "callType": "async"
        }
    ]
}

Sample request in the Alink JSON format:

{
    "method": "thing.service.SetWeight",
    "id": "105917531",
    "params": {
        "NewWeight": 100.8
    },
    "version": "1.0"
}

Sample responses in the Alink JSON format:

{
    "id": "105917531",
    "code": 200,
    "data": {
        "CollectTime": "1536228947682",
        "OldWeight": 100.101
    }
    "message": "success",
    "version": "1.0"
}

Error codes: IoT Platform may return error codes to devices. For more information, see Error codes for devices.

Data forwarding: IoT Platform can forward the results of asynchronous calls to your server or other Alibaba Cloud services by using the server-side subscription or data forwarding feature. For more information about the relevant topics and data formats, see Submit responses to downstream requests.

Gateways submit multiple properties and events to IoT Platform at the same time

A gateway can submit multiple properties and events to IoT Platform at the same time. The gateway can submit its own properties and events, or the properties and events of sub-devices that are attached to the gateway.

Note

A gateway can submit a maximum of 200 properties and 20 events at the same time.
A gateway can submit data for a maximum of 20 sub-devices at the same time.

Topics and data formats used to send data from gateways to IoT Platform:

Custom

Topic

Data formats

Request topic: /sys/${productKey}/${deviceName}/thing/model/up_raw

A request contains the raw data that a gateway must submit to IoT Platform.

Note

Example:

0xff0000007b00

Response topic: /sys/${productKey}/${deviceName}/thing/model/up_raw_reply

Sample responses:

Sample success response

{
    "code": 200,
    "data": {},
    "id": "123",
    "message": "success",
    "version": "1.0"
}

Sample failure response

{
    "code": 6813,
    "data": {},
    "id": "123",
    "message": "topic illegal",
    "version": "1.0"
}

Alink JSON

Request and response topics

Request data and response data

Request topic: /sys/${productKey}/${deviceName}/thing/event/property/pack/post

Sample request in the Alink JSON format:

{
    "id": "123",
    "version": "1.0",
    "sys":{
        "ack":0
    },
    "params": {
        "properties": {
            "Power": {
                "value": "on",
                "time": 1524448722000
            },
            "WF": {
                "value": { },
                "time": 1524448722000
            }
        },
        "events": {
            "alarmEvent1": {
                "value": {
                    "param1": "on",
                    "param2": "2"
                },
                "time": 1524448722000
            },
            "alertEvent2": {
                "value": {
                    "param1": "on",
                    "param2": "2"
                },
                "time": 1524448722000
            }
        },
        "subDevices": [
            {
                "identity": {
                    "productKey": "",
                    "deviceName": ""
                },
                "properties": {
                    "Power": {
                        "value": "on",
                        "time": 1524448722000
                    },
                    "WF": {
                        "value": { },
                        "time": 1524448722000
                    }
                },
                "events": {
                    "alarmEvent1": {
                        "value": {
                            "param1": "on",
                            "param2": "2"
                        },
                        "time": 1524448722000
                    },
                    "alertEvent2": {
                        "value": {
                            "param1": "on",
                            "param2": "2"
                        },
                        "time": 1524448722000
                    }
                }
            }
        ]
    },
    "method": "thing.event.property.pack.post"
}

Response topic: /sys/${productKey}/${deviceName}/thing/event/property/pack/post_reply

Sample response in the Alink JSON format:

{
    "code": 200,
    "data": {},
    "id": "123",
    "message": "success",
    "method": "thing.event.property.pack.post",
    "version": "1.0"
}

If the request fails, {} is returned.

Parameters:

Table 9. Request parameters
Parameter	Type	Description
id	String	The ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for the device.
version	String	The version number of the protocol. Set the value to 1.0.
sys	Object	The parameter for extended features. The value contains the fields for each feature. Note If no extended features are configured when you use a device SDK to develop device features, this parameter is unavailable. The extended features use the default configurations.
ack	Integer	The extended feature field in the sys parameter. This field specifies whether IoT Platform returns response data for a registration request. Valid values: 1: IoT Platform returns response data. 0: IoT Platform does not return response data. Important For more information about the parameter, see Examples on how to use a TSL model. If the feature is not configured, this parameter is unavailable. By default, IoT Platform returns response data for a registration request.
params	Object	The property data and event data that a gateway must submit in the request.
properties	Object	The properties to be submitted. You can specify the identifier, value, and time of each property. The time parameter is optional. You can determine whether to specify the time parameter in requests based on your business requirements. If a gateway frequently sends messages to IoT Platform, we recommend that you specify the time parameter in requests to help you identify the order of messages. In the preceding example, the gateway submits information about the Power (power supply) and WF (working current) properties. 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. Example: `"test:Power": { "value": "on", "time": 1524448722000 }`
events	Object	The events to be submitted. You can specify the identifier, value, and time of each event. The time parameter is optional. You can determine whether to specify the time parameter in requests based on your business requirements. If a gateway frequently sends messages to IoT Platform, we recommend that you specify the time parameter in requests. This helps you identify the order of messages. In the preceding example, alarmEvent1 (Alert Event 1) and alarmEvent2 (Alert Event 2) are submitted. The parameters of the events are param1 and param2. If you use the events of a custom module, the identifier of each event is in the ${Module identifier}:${Event identifier}. A colon (:) is used to connect the two parts of this expression. Example: `"test:alarmEvent1": { "value": { "param1": "on", "param2": "2" }, "time": 1524448722000 }`
subDevices	Object	The information about the attached sub-device.
productKey	String	The ProductKey of the product to which the attached device belongs.
deviceName	String	The DeviceName of the sub-device.
method	String	The request method. Set the value to thing.event.property.pack.post.

Table 10. Response parameters
Parameter	Type	Description
id	String	The ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for a device.
code	Integer	The status code. The value 200 indicates a successful request. Note IoT Platform checks whether devices, topological relationships, and submitted properties and events comply with the formats that are defined in the TSL model. If the format of a preceding item is invalid, the request failed.
data	Object	If the request is successful, this parameter is left empty.
message	String	The response message. If the request is successful, the "success" message is displayed.
method	String	The request method in the response. The parameter value is the same as the value of the method parameter in the request.
version	String	The version number of the protocol. The parameter value is the same as the value of the version parameter in the request.

Error codes: IoT Platform may return error codes to devices. For more information, see Error codes for devices.

Data forwarding: IoT Platform can forward a batch of TSL data that is reported by a gateway to your server or other Alibaba Cloud services by using the server-side subscription or data forwarding feature. Then, the system separates the TSL data into messages and forwards the messages in sequence. The messages include the data of the properties and events of the gateway and the sub-devices that are attached to the gateway. For more information about the relevant topics and data formats, see Submit device properties and Submit device events.

Devices submit historical TSL data to IoT Platform

Topics and data formats used to send data from devices to IoT Platform:

Request topic: /sys/${productKey}/${deviceName}/thing/event/property/history/post
Response topic: /sys/${productKey}/${deviceName}/thing/event/property/history/post_reply

Sample request in the Alink JSON format:

{
    "id": "123", 
    "version": "1.0",
    "sys":{
        "ack":0
    }, 
    "method": "thing.event.property.history.post", 
    "params": [
        {
            "identity": {
                "productKey": "", 
                "deviceName": ""
            }, 
            "properties": [
                {
                    "Power": {
                        "value": "on", 
                        "time": 1524448722000
                    }, 
                    "WF": {
                        "value": "3", 
                        "time": 1524448722000
                    }
                }, 
                {
                    "Power": {
                        "value": "on", 
                        "time": 1524448722000
                    }, 
                    "WF": {
                        "value": "3", 
                        "time": 1524448722000
                    }
                }
            ], 
            "events": [
                {
                    "alarmEvent": {
                        "value": {
                            "Power": "on", 
                            "WF": "2"
                        }, 
                        "time": 1524448722000
                    }, 
                    "alertEvent": {
                        "value": {
                            "Power": "off", 
                            "WF": "3"
                        }, 
                        "time": 1524448722000
                    }
                }
            ]
        }, 
        {
            "identity": {
                "productKey": "", 
                "deviceName": ""
            }, 
            "properties": [
                {
                    "Power": {
                        "value": "on", 
                        "time": 1524448722000
                    }, 
                    "WF": {
                        "value": "3", 
                        "time": 1524448722000
                    }
                }
            ], 
            "events": [
                {
                    "alarmEvent": {
                        "value": {
                            "Power": "on", 
                            "WF": "2"
                        }, 
                        "time": 1524448722000
                    }, 
                    "alertEvent": {
                        "value": {
                            "Power": "off", 
                            "WF": "3"
                        }, 
                        "time": 1524448722000
                    }
                }
            ]
        }
    ]
}

Sample responses in the Alink JSON format:

Sample success response

{
    "code": 200,
    "data": {},
    "id": "123",
    "message": "success",
    "method": "thing.event.property.history.post",
    "version": "1.0"
}

Sample failure response

{
    "code": 5092,
    "data": {},
    "id": "123",
    "message": "property not found",
    "method": "thing.event.property.history.post",
    "version": "1.0"
}

Parameters:

Table 11. Request parameters
Parameter	Type	Description
id	String	The ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for the device.
version	String	The version number of the protocol. Set the value to 1.0.
sys	Object	The parameter for extended features. The value contains the fields for each feature. Note If no extended features are configured when you use a device SDK to develop device features, this parameter is unavailable. The extended features use the default configurations.
ack	Integer	The extended feature field in the sys parameter. This field specifies whether IoT Platform returns response data for a registration request. Valid values: 1: IoT Platform returns response data. 0: IoT Platform does not return response data. Important For more information about the parameter, see Examples on how to use a TSL model. If the feature is not configured, this parameter is unavailable. By default, IoT Platform returns response data for a registration request.
method	String	The request method. Set the value to thing.event.property.history.post.
params	Object	The property data and event data that a device must submit in the request.
identity	String	The certificate information about the device to which the data belongs. You must specify the productKey and deviceName parameters. Note A directly connected device can submit only its own historical TSL data. A gateway can submit the historical TSL data of the sub-devices that are attached to the gateway. If a gateway submits the historical data of an attached sub-device, the identity parameter contains information about the attached sub-device.
properties	Object	The properties to be submitted. You can specify the identifier, value, and time parameters of each property. In the preceding example, the device submits historical data about the Power (power supply) and WF (working current) properties. 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. Example: `"test:Power": { "value": "on", "time": 1524448722000 }`
events	Object	The events that a device needs to submit. You can specify the identifier, value, and time of each event. In the preceding example, the historical data about the alarmEvent (alert event) event, the Power (power supply) property, and the WF (working current) property are submitted. If you use the events of a custom module, the identifier of each event is in the ${Module identifier}:${Event identifier}. A colon (:) is used to connect the two parts of this expression. Example: `"test:alarmEvent": { "value": { "Power": "on", "WF": "2" }, "time": 1524448722000 }`

Table 12. Response parameters
Parameter	Type	Description
id	String	The ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for the device.
code	Integer	The status code. For more information, see Common codes on devices.
data	Object	If the request is successful, this parameter is left empty.
message	String	The response message. If the request is successful, the "success" message is displayed.
method	String	The request method in the response. The parameter value is the same as the value of the method parameter in the request.
version	String	The version number of the protocol. The parameter value is the same as the value of the version parameter in the request.

Error codes: IoT Platform may return error codes to devices. For more information, see Error codes for devices.

Data forwarding: IoT Platform can forward historical TSL data that is submitted by devices to your server or other Alibaba Cloud services by using the server-side subscription or data forwarding feature. For more information about the relevant topics and data formats, see Submit historical properties and Submit historical events.

Important

When IoT Platform forwards historical TSL data, it creates a message for each property in the value of the properties parameter or each event in the value of the events parameter. The messages are used to forward the historical data of the properties and events.

Devices submit multiple properties and events to IoT Platform at the same time

Topics and data formats used to send data from devices to IoT Platform:

Request topic: /sys/${productKey}/${deviceName}/thing/event/property/batch/post
Response topic: /sys/${productKey}/${deviceName}/thing/event/property/batch/post_reply

Sample request in the Alink JSON format:

{
    "id": "123", 
    "version": "1.0",
    "sys":{
        "ack":0
    }, 
    "method": "thing.event.property.batch.post", 
    "params": {
        "properties": {
            "Power": [
                {
                    "value": "on", 
                    "time": 1524448722000
                },
                {
                    "value": "off", 
                    "time": 1524448722001
                }
            ], 
            "WF": [
                {
                    "value": 3, 
                    "time": 1524448722000
                },
                {
                    "value": 4, 
                    "time": 1524448722009
                }
            ]
        }, 
        "events": {
            "alarmEvent": [
                {
                    "value": {
                        "Power": "on", 
                        "WF": "2"
                    }, 
                    "time": 1524448722000
                },
                {
                    "value": {
                        "Power": "on", 
                        "WF": "2"
                    }, 
                    "time": 1524448722000
                }
            ]
        }
    }
}

Sample responses in the Alink JSON format:

Sample success response

{
    "code": 200,
    "data": {},
    "id": "123",
    "message": "success",
    "method": "thing.event.property.batch.post",
    "version": "1.0"
}

Sample failure response

{
    "code": 9201,
    "data": {},
    "id": "123",
    "message": "device offLine",
    "method": "thing.event.property.batch.post",
    "version": "1.0"
}

Parameters:

Table 13. Request parameters
Parameter	Type	Description
id	String	The ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for the device.
version	String	The version number of the protocol. Set the value to 1.0.
sys	Object	The parameter for extended features. The value contains the fields for each feature. Note If no extended features are configured when you use a device SDK to develop device features, this parameter is unavailable. The extended features use the default configurations.
ack	Integer	The extended feature field in the sys parameter. This field specifies whether IoT Platform returns response data for a registration request. Valid values: 1: IoT Platform returns response data. 0: IoT Platform does not return response data. Important For more information about the parameter, see Examples on how to use a TSL model. If the feature is not configured, this parameter is unavailable. By default, IoT Platform returns response data for a registration request.
method	String	The request method. Set the value to thing.event.property.batch.post.
params	Object	The property data and event data that a device must submit in the request.
properties	Object	The properties to be submitted. You can specify the identifier, value, and time parameters of each property. In the preceding example, the device submits the Power (power supply) and WF (working current) properties at the same time. 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. Example: `"test:Power": { "value": "on", "time": 1524448722000 }`
events	Object	The events that a device needs to submit. You can specify the identifier, value, and time of each event. In the preceding example, the device submits the alarmEvent (alert event), the Power (power supply) property, and the WF (working current) property at the same time. If you use the events of a custom module, the identifier of each event is in the ${Module identifier}:${Event identifier}. A colon (:) is used to connect the two parts of this expression. Example: `"test:alarmEvent": { "value": { "Power": "on", "WF": "2" }, "time": 1524448722000 }`

Table 14. Response parameters
Parameter	Type	Description
id	String	The ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for the device.
code	Integer	The status code. For more information, see Common codes on devices.
data	Object	If the request is successful, this parameter is left empty.
message	String	The response message. If the request is successful, the "success" message is displayed.
method	String	The request method in the response. The parameter value is the same as the value of the method parameter in the request.
version	String	The version number of the protocol. The parameter value is the same as the value of the version parameter in the request.

Error codes: IoT Platform may return error codes to devices. For more information, see Error codes for devices.

Data forwarding: IoT Platform can forward a batch of TSL data that is submitted by devices to your server by using the server-side subscription feature. Properties and events are forwarded in two separate messages. For more information about the specific topics and data formats, see Submit device properties in batches and Submit device events in batches.

References

What are the differences among submitting property data, submitting historical data, and submitting multiple values of properties at the same time?