If you define a Thing Specification Language (TSL) model for a product, the devices of the product can report properties and events to IoT Platform. IoT Platform can send commands to devices. These commands are used to set device properties and call services.
A TSL model includes device properties, events, and services. For more information about the data format of TSL models, see Format of a TSL model.
Device data is reported in the following formats: Alink JSON and custom. You can use one of the formats to report device data. We recommend that you use the Alink JSON format.
- ICA standard data format (Alink JSON): A device generates data in the standard format that is defined by IoT Platform, and reports the data to IoT Platform.
- Custom: If the custom mode is used, a device sends raw data such as a binary data
stream to IoT Platform. IoT Platform runs the script that you have submitted to convert
the raw data into a standard format. For more information, see Data parsing scripts. IoT Platform generates data in the Alink JSON format. Before the data is sent to
devices, the data is converted into binary data.
Report device properties
Upstream data in the custom format:
- Request topic:
/sys/{productKey}/{deviceName}/thing/model/up_raw
- Response topic:
/sys/{productKey}/{deviceName}/thing/model/up_raw_reply
Raw data that is reported by a device is sent to the request topic.
Example:
0x00002233441232013fa00000
Example of downstream data:
{
"id":"123",
"code": 200,
"data":{}
}
Upstream data in the Alink JSON format
- Request topic:
/sys/{productKey}/{deviceName}/thing/event/property/post
- Response topic:
/sys/{productKey}/{deviceName}/thing/event/property/post
Sample request in the Alink JSON format:
{
"id": "123",
"version": "1.0",
"params": {
"Power": {
"value": "on",
"time": 1524448722000
},
"WF": {
"value": 23.6,
"time": 1524448722000
}
},
"method": "thing.event.property.post"
}
Parameter | Type | Description |
---|---|---|
id | String | The message ID. Valid values: 0 to 4294967295. Each message ID must be unique for the device. |
version | String | The version of the protocol. Valid value: 1.0. |
method | String | The request method. Valid value: thing.event.property.post. |
params | Object | The request parameters. In the preceding example, the device reports the Power and WF properties. Each property includes the report time and reported value. |
time | Long | The UTC timestampwhen the property was reported. Unit: milliseconds. Optional. You can specify a timestamp based on your business requirements. If a device sends messages at a high frequency, we recommend that you specify a timestamp for each message to identify the order in which the messages are sent. |
value | Object | The value of the property. |
Response format:
{
"id": "123",
"code": 200,
"data": {}
}
Parameter | Type | Description |
---|---|---|
id | String | The message ID. Valid values: 0 to 4294967295. Each message ID must be unique for the device. |
code | Integer | The HTTP status code. For more information, see Common codes on devices. |
data | Object | The response data in the case of a successful request. |
HTTP status code | Error message | Description |
---|---|---|
460 | request parameter error | The error message returned because one or more request parameters are invalid. |
6106 | map size must less than 200 | The error message returned because the number of reported properties exceeds 200. |
6313 | tsl service not available |
The TSL verification service is unavailable. IoT Platform verifies properties that are reported by a device based on the defined TSL model. Only valid properties are reserved after the verification. A successful verification is indicated even if all properties are screened. If the TSL verification service is unavailable, the 6313 HTTP status code is returned. |
You can use the data forwarding feature of the rules engine to forward properties that are reported by devices to the required cloud services. For more information about the required topics and data formats, see Report device properties.
Set device properties
You can call the SetDeviceProperty or SetDevicesProperty API operation to send commands to devices to set properties.
Downstream data in the custom format:
- Request topic:
/sys/{productKey}/{deviceName}/thing/model/down_raw
- Response topic:
/sys/{productKey}/{deviceName}/thing/model/down_raw_reply
Downstream data in the Alink JSON format:
- Request topic:
/sys/{productKey}/{deviceName}/thing/service/property/set
- Response topic:
/sys/{productKey}/{deviceName}/thing/service/property/set_reply
Sample request in the Alink JSON format:
{
"id": "123",
"version": "1.0",
"params": {
"temperature": "30.5"
},
"method": "thing.service.property.set"
}
Parameter | Type | Description |
---|---|---|
id | String |
The message ID. Valid values: 0 to 4294967295. Each message ID must be unique for the device. |
version | String | The version of the protocol. Valid value: 1.0. |
params | Object | The properties to set. In the preceding example, use the { "temperature": "30.5" } key-value pair to set the temperature property to 30.5.
|
method | String | The request method. Valid value: thing.service.property.set. |
Sample response in the Alink JSON format:
{
"id": "123",
"code": 200,
"data": {}
}
Parameter | Type | Description |
---|---|---|
id | String | The message ID. Valid values: 0 to 4294967295. Each message ID must be unique for the device. |
code | Integer | For more information about HTTP status codes, see Common codes on devices. |
data | Object | The response data in the case of a successful request. |
You can use the data forwarding feature of the rules engine to forward property setting results to the required cloud services. For more information about the required topics and data formats, see Submit responses to downstream requests.
Submit device events
Upstream (passthrough)
- Request topic:
/sys/{productKey}/{deviceName}/thing/model/up_raw
- Response topic:
/sys/{productKey}/{deviceName}/thing/model/up_raw_reply
The raw data of a request message:
0xff0000007b00
Response message from IoT Platform:
{
"id":"123",
"code": 200,
"data":{}
}
Upstream data in the Alink JSON format:
- Request topic:
/sys/{productKey}/{deviceName}/thing/event/{tsl.event.identifier}/post
- Response topic:
/sys/{productKey}/{deviceName}/thing/event/{tsl.event.identifier}/post
Sample request in the Alink JSON format:
{
"id": "123",
"version": "1.0",
"params": {
"value": {
"Power": "on",
"WF": "2"
},
"time": 1524448722000
},
"method": "thing.event.{tsl.event.identifier}.post"
}
Parameter | Type | Description |
---|---|---|
id | String | The message ID. Valid values: 0 to 4294967295. Each message ID must be unique for the device. |
version | String | The protocol version. Valid value: 1.0. |
method | String | The request method. Valid value: thing.event.{tsl.event.identifier}.post. Replace {tsl.event.identifier} with the ID of an event that you have defined in the TSL model. For more information,
see Add a TSL feature.
|
params | Object | The parameters of the event. |
value | Object | The values of the parameters. Example:
|
time | Long | Optional. The UTC timestamp that is generated for the event. Unit: milliseconds.
You can specify a timestamp based on your business requirements. If a device sends messages at a high frequency, we recommend that you specify a timestamp for each message to identify the order in which the messages are sent. |
Sample response in the Alink JSON format:
{
"id": "123",
"code": 200,
"data": {}
}
Parameter | Type | Description |
---|---|---|
id | String | The message ID. Valid values: 0 to 4294967295. Each message ID must be unique for the device. |
code | Integer | The HTTP status code. For more information, see Common codes on devices.
Note IoT Platform verifies all the events that are reported by devices. IoT Platform compares
the format of each reported property with the predefined format in the TSL model to
verify the validity of the property. IoT Platform drops an invalid event and returns
an error code.
|
data | Object | The response data in the case of a successful request. |
Sample event in the Alink JSON format:
The following example shows the alarm event that is defined in the TSL model of a product:
{
"schema": "https://iot-tsl.oss-cn-shanghai.aliyuncs.com/schema.json",
"link": "/sys/${productKey}/airCondition/thing/",
"profile ":{
"productKey": "Replace ${productKey} with your product key",
"deviceName": "Replace airCondition with your device name"
},
"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"
}
]
}
Sample request in the Alink JSON format when a device reports the event:
{
"id": "123",
"version": "1.0",
"params": {
"value": {
"errorCode": "error"
},
"time": 1524448722000
},
"method": "thing.event.alarm.post"
}
You can use the data forwarding feature of the rules engine to forward events that are reported by devices to the required cloud services. For more information about the required topics and data formats, see Reporting of device events.
Invoke device services in an asynchronous manner
- Synchronous method: You can call the InvokeThingService or InvokeThingsService API operation to invoke services. IoT Platform uses the Revert-RPC (RRPC) method to push requests to devices. If the service invocation method is synchronous, IoT Platform subscribes to the RRPC topic. For more information about how to implement RRPC, see What is RRPC?
- Asynchronous method: You can call the InvokeThingService or InvokeThingsService API operation to invoke services. IoT Platform pushes requests to devices in an asynchronous
manner, and the devices return results in an asynchronous manner. If the service invocation
method is asynchronous, IoT Platform subscribes to the asynchronous response topic.
You can use the data forwarding feature of the rules engine to obtain the results from an asynchronous invocation. For more information about the required topics and data formats, see Submit responses to downstream requests.
Downstream data in the custom format:
- Request topic:
/sys/{productKey}/{deviceName}/thing/model/down_raw
- Response topic:
/sys/{productKey}/{deviceName}/thing/model/down_raw_reply
Downstream data in the Alink JSON format:
- Request topic:
/sys/{productKey}/{deviceName}/thing/service/{tsl.service.identifier}
- Response topic:
/sys/{productKey}/{deviceName}/thing/service/{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}"
}
Parameter | Type | Description |
---|---|---|
id | String |
The message ID. Valid values: 0 to 4294967295. Each message ID must be unique for the device. |
version | String | The version of the protocol. Valid value: 1.0. |
params | Object | The parameters that are required to invoke the service. You must specify the identifier
and value of the service. Example:
|
method | String | The request method. Valid value: thing.service.{tsl.service.identifier}.
Note Replace
{tsl.service.identifier} with the ID of a service that is defined in the TSL model. For more information,
see Add a TSL feature.
|
Sample response in the Alink JSON format:
{
"id": "123",
"code": 200,
"data": {}
}
Parameter | Type | Description |
---|---|---|
id | String | The message ID. Valid values: 0 to 4294967295. Each message ID must be unique for the device. |
code | Integer | The HTTP status code. For more information, see Common codes on devices. |
data | Object | The response data.
The value of the parameter is based on the TSL model of the product. If the service does not return a response, the value of the data parameter is empty. If the service returns a response, the returned data follows the service definition in the TSL model. |
Sample service in the Alink JSON format:
The following example shows the SetWeight service that is defined in the TSL model of a product:
{
"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 service invocation request in the Alink JSON format:
{
"method": "thing.service.SetWeight",
"id": "105917531",
"params": {
"NewWeight": 100.8
},
"version": "1.0"
}
Sample response in the Alink JSON format:
{
"id": "105917531",
"code": 200,
"data": {
"CollectTime": "1536228947682",
"OldWeight": 100.101
}
}
Report data in batches from a gateway
A gateway can report its own properties and events in batches. The gateway can also report the properties and events of the connected sub-devices in batches.
- A gateway can report a maximum of 200 properties and 20 events at a time.
- A gateway can report the data of a maximum of 20 sub-devices at a time.
Upstream data in the custom format:
- Request topic:
/sys/{productKey}/{deviceName}/thing/model/up_raw
- Response topic:
/sys/{productKey}/{deviceName}/thing/model/up_raw_reply
The raw data of a request message:
0xff0000007b00
Sample response from IoT Platform:
{
"id": "123",
"code": 200,
"data": {}
}
Upstream data in the Alink JSON format:
- Request topic:
/sys/{productKey}/{deviceName}/thing/event/property/pack/post
- Response topic:
/sys/{productKey}/{deviceName}/thing/event/property/pack/post_reply
Sample request in the Alink JSON format:
{
"id": "123",
"version": "1.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"
}
Parameter | Type | Description |
---|---|---|
id | String | The message ID. Valid values: 0 to 4294967295. Each message ID must be unique for the device. |
version | String | The version of the protocol. Set this parameter to 1.0. |
params | Object | The request parameters. |
properties | Object | The properties. You must specify the identifier, value, and time for each property.
The time parameter is optional. You can specify a timestamp based on your business requirements. If a device sends messages at a high frequency, we recommend that you specify a timestamp for each message to identify the order in which the messages are sent. |
events | Object | The events. You must specify the identifier, value, and time for each event.
The time parameter is optional. You can specify a timestamp based on your business requirements. If a device sends messages at a high frequency, we recommend that you specify a timestamp for each message to identify the order in which the messages are sent. |
subDevices | Object | The device information. |
productKey | String | The product key of each sub-device. |
deviceName | String | The name of the sub-device. |
method | String | The request method. Valid value: thing.event.property.pack.post. |
Sample response in the Alink JSON format:
{
"id": "123",
"code": 200,
"data": {}
}
Parameter | Type | Description |
---|---|---|
id | String | The message ID. Valid values: 0 to 4294967295. Each message ID must be unique. |
code | Integer | The response code. The 200 value indicates a successful request.
Note IoT Platform verifies whether devices, topological relationships, reported properties,
and reported events follow the definition of the TSL model for a product. If one of
the preceding items cannot pass the verification, devices fail to report data.
|
data | Object | The response data in the case of a successful request. |
Report the historical data of a TSL model
Upstream data:
- Request topic:
/sys/{productKey}/{deviceName}/thing/event/property/history/post
- Response topic:
/sys/{productKey}/{deviceName}/thing/event/property/history/post
Sample request in the Alink JSON format:
{
"id": 123,
"version": "1.0",
"method": "thing.event.property.history.post",
"params": [
{
"identity": {
"productKey": "",
"deviceName": ""
},
"properties": [
{
"Power": {
"value": "on",
"time": 123456
},
"WF": {
"Value": "3"
"time": 123456
}
},
{
"Power": {
"value": "on",
"time": 123456
},
"WF": {
"Value": "3"
"time": 123456
}
}
],
"events": [
{
"alarmEvent": {
"value": {
"Power": "on",
"WF": "2"
},
"time": 123456
},
"alertEvent": {
"value": {
"Power": "off",
"WF": "3"
},
"time": 123456
}
}
]
},
{
"identity": {
"productKey": "",
"deviceName": ""
},
"properties": [
{
"Power": {
"value": "on",
"time": 123456
},
"WF": {
"value": "3",
"time": 123456
}
}
],
"events": [
{
"alarmEvent": {
"value": {
"Power": "on",
"WF": "2"
},
"time": 123456
},
"alertEvent": {
"value": {
"Power": "off",
"WF": "3"
},
"time": 123456
}
}
]
}
]
}
Parameter | Type | Description |
---|---|---|
id | String | The message ID. Valid values: 0 to 4294967295. Each ID must be unique for the device. |
version | String | The version of the protocol. Valid value: 1.0. |
method | String | The request method. Valid value: thing.event.property.history.post. |
params | Object | The request parameters. |
identity | String | The certificate information of the device to which the historical data belongs. You
must specify the productKey and deviceName parameters.
Note A directly connected device can report only the historical data of its own TSL model.
A gateway can report the historical data of the TSL model for sub-devices that are
attached to the gateway. If a gateway reports the historical data of a sub-device,
the identity parameter includes the sub-device information.
|
properties | Object | The properties. You must specify the identifier, value, and time parameters for each property. |
events | Object | The events. You must specify the identifier, value, and time parameters for each event. |
Sample response in the Alink JSON format:
{
"id":"123",
"code": 200,
"data":{}
}
You can use the data forwarding feature of the rules engine to forward the reported historical data of a TSL model to the required cloud services. For more information about the required topics and data formats, see Format of historical data for a TSL model.