After you define a Thing Specification Language (TSL) model for a product, the devices of the product can submit properties and events to IoT Platform. IoT Platform can send downstream commands to set device properties and call device services.

A TSL model defines the properties, events, and services of devices. For more information about data formats, see What is a TSL model?.

You can submit device data in one of the following formats: Alink JSON and custom. We recommend that you use the Alink JSON format.

  • Alink JSON: the standard data format used by IoT Connectivity Alliance (ICA). A device generates data in the standard format that is defined by IoT Platform, and submits the data to IoT Platform. For more information about the format, see the examples in this topic.
  • 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 the standard format. For more information, see Data parsing scripts. IoT Platform generates data in the Alink JSON format. IoT Platform converts the data into binary data and sends the binary data to devices. TSL-based pass-through

Submit device properties

Upstream data format Request and response topics Request and response data
Custom
  • Request topic: /sys/{productKey}/{deviceName}/thing/model/up_raw
  • Response topic: /sys/{productKey}/{deviceName}/thing/model/up_raw_reply
 Raw data of devices are submitted.
Note
  • Raw data that is transmitted over MQTT is in the hexadecimal format.
  • The submitted data must include the method parameter that specifies the request method. Set the value to thing.event.property.post.

Example:

0x00002233441232013fa00000

Sample response:

{
  "id": "123",
  "code": 200,
  "data": {}
}
Alink JSON
  • Request topic: /sys/{productKey}/{deviceName}/thing/event/property/post
  • Response topic: /sys/{productKey}/{deviceName}/thing/event/property/post_reply
 Sample request in the Alink JSON format:
{
  "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"
}

Sample response in the Alink JSON format:

{
  "id": "123",
  "code": 200,
  "data": {}
}
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.
method String The request method. Set the value to thing.event.property.post.
params Object The request parameters. In the preceding example, the device submits the Power and WF properties. You can specify the value and time parameters for each property.

The identifier of a custom module property is in the format of Module identifier:Property identifier. Example: 

"test:Power": {
      "value": "on",
      "time": 1524448722000
    }
time Long The UTC timestamp that indicates when the property was submitted. Unit: milliseconds. This 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.
value Object The property value to be submitted.
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 that indicates the result. For more information, see Common codes on devices.
Note IoT Platform verifies all the properties that are submitted by devices. IoT Platform checks the format of each submitted property based on the predefined format in the TSL model. If a property is invalid, IoT Platform discards it and returns an error code.
data Object The data returned if the request is successful. The value is empty.
Table 3. Error codes
Error code Error message Description
460 request parameter error The error code returned because the request parameters are invalid.
6106 map size must less than 200 The error code returned because the number of submitted properties exceeds 200.
6313 tsl service not available

The error code returned because the TSL verification service is unavailable.

IoT Platform verifies properties that are submitted by a device based on the defined TSL model.

Only valid properties are retained after the verification. The verification is successful even if all properties are discarded.

If the TSL verification service is unavailable, the error code 6313 is returned.

IoT Platform can forward the properties that are 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 specific topics and data formats, see Submit device properties.

Set device properties

You can call the SetDeviceProperty or SetDevicesProperty operation to send commands that set device properties.

Downstream data format 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 in the Alink JSON format:

{
  "id": "123",
  "version": "1.0",
  "params": {
    "temperature": "30.5"
  },
  "method": "thing.service.property.set"
}
Table 4. 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 to set. Example: { "temperature": "30.5" }.

If the property to be set belongs to a custom module, enter the property identifier in the format of Module identifier:Property identifier, such as { "test:temperature": "30.5" }.

method String The request method. Set the value to thing.service.property.set.

Sample response in the Alink JSON format:

{
  "id": "123",
  "code": 200,
  "data": {}
}
Table 5. 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 that indicates the result. For more information, see Common codes on devices.
data Object The data that is returned when the request is successful. The value is empty.

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

Submit device events

Upstream data format Request and response topics Request and response data
Custom
  • Request topic: /sys/{productKey}/{deviceName}/thing/model/up_raw
  • Response topic: /sys/{productKey}/{deviceName}/thing/model/up_raw_reply
 Raw data of devices are submitted.
Note The submitted data must include the method parameter that specifies the request method. For more information, see the description in the following table.

Example:

0xff0000007b00

Sample response:

{
    "id":"123",
    "code":200,
    "data":{}
}
Alink JSON
  • 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
  • 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
 Sample request in the Alink JSON format:
{
  "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:

{
  "id": "123",
  "code": 200,
  "data": {}
}
Table 6. 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.
method String The request method.
  • Default module

    Valid value: thing.event.{tsl.event.identifier}.post.

  • Custom module

    Set the value to thing.event.{tsl.functionBlockId}:{tsl.event.identifier}.post.

Note In the preceding values, {tsl.event.identifier} indicates the event identifier that is defined in the TSL model, and {tsl.functionBlockId} indicates 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. Example: 
{
   "Power": "on",
   "WF": "2"
}
time Long The UTC timestamp that indicates when the event was generated. Unit: milliseconds.

This 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.

Table 7. 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 that indicates the result. For more information, see Common codes on devices.
Note IoT Platform verifies all the events that are submitted by devices. IoT Platform checks the format of each submitted property based on the predefined format in the TSL model. If an event is invalid, IoT Platform discards it and returns an error code.
data Object The data returned if the request is successful. The value is empty.

Sample event in the Alink JSON format:

The following example shows the alert event that is defined in the 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"
    }
  ]
}

Sample request in the Alink JSON format when a device submits the event:

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

IoT Platform can forward the events that are 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 specific topics and data formats, see Submit device events.

Call device services in an asynchronous manner

IoT Platform allows you to call services in a synchronous or asynchronous manner. When you define a service, you must specify the calling method for the service. For more information, see Service calling process in Alink.
  • Synchronous method: You can call the InvokeThingService or InvokeThingsService operation to call services. IoT Platform uses the revert-RPC (RRPC) method to push requests to devices. If the service calling method is synchronous, IoT Platform subscribes to the RRPC topic. For more information, see What is RRPC?
  • Asynchronous method: You can call the InvokeThingService or InvokeThingsService operation to call services. IoT Platform pushes requests to devices in an asynchronous manner, and the devices return results also in an asynchronous manner. If the service calling method is asynchronous, IoT Platform subscribes to the asynchronous response topic.

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

Downstream data format 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 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}"
}
Table 8. 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. You must specify the identifier and value of the service. Example: 
{
   "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 In the preceding values, {tsl.service.identifier} indicates the service identifier that is defined in the TSL model, and {tsl.functionBlockId} indicates the identifier of the custom module. For more information, see Add a TSL feature.

Sample response in the Alink JSON format:

{
  "id": "123",
  "code": 200,
  "data": {}
}
Table 9. 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 that indicates the result. For more information, see Common codes on devices.
data Object The response data.

The value of the data parameter is determined by the TSL model. 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:

{
  "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": "SetWeight",
      "required": false,
      "callType": "async"
    }
  ]
}

Sample request in the Alink JSON format when IoT Platform calls the service:

{
  "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
  }
}

Submit multiple properties and events at a time from a gateway

A gateway can submit multiple properties and events at a time. A gateway can submit its own properties and events and 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 a time.
  • A gateway can submit the data of a maximum of 20 sub-devices at a time.
Upstream data format Request and response topics Request and response data
Custom
  • Request topic: /sys/{productKey}/{deviceName}/thing/model/up_raw
  • Response topic: /sys/{productKey}/{deviceName}/thing/model/up_raw_reply
 Raw data of devices are submitted.
Note The submitted data must include the method parameter that specifies the request method. Set the value to thing.event.property.pack.post.

Example:

0xff0000007b00

Sample response:

{
  "id": "123",
  "code": 200,
  "data": {}
}
Alink JSON
  • 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",
  "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"
}

Sample response in the Alink JSON format:

{
  "id": "123",
  "code": 200,
  "data": {}
}
Table 10. 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 request parameters.
properties Object The properties to be submitted. You can specify the identifier, value, and time parameters 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.

The identifier of a custom module property is in the format of Module identifier:Property identifier. Example: 

"test:Power": {
      "value": "on",
      "time": 1524448722000
    }
events Object The events to be submitted. You can specify the identifier, value, and time parameters 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.

The identifier of a custom module property is in the format of Module identifier:Property identifier. Example: 

"test:alarmEvent1": {
        "value": {
          "param1": "on",
          "param2": "2"
        },
        "time": 1524448722000
      }
subDevices Object The sub-device information.
productKey String The key of the product to which the sub-device belongs.
deviceName String The DeviceName of the sub-device.
method String The request parameters. Set the value to thing.event.property.pack.post.
Table 11. 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 response code. The 200 value indicates a successful request.
Note IoT Platform checks whether devices, topological relationships, and submitted properties and events follow the definition of the TSL model. If one of the preceding items cannot pass the verification, devices fail to submit data.
data Object The data returned if the request is successful. The value is empty.

Submit historical TSL data

The following topics are used when a device sends requests to IoT Platform and IoT Platform sends responses to the device:

  • 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
          }
        }
      ]
    }
  ]
}
Table 12. 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.
method String The request method. Set the value to 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 submit only historical TSL data. A gateway can submit historical TSL data of the sub-devices that are attached to the gateway. If a gateway submits the historical data of a sub-device, the identity parameter includes the sub-device information.
properties Object The properties to be submitted. You can specify the identifier, value, and time parameters for each property.

The identifier of a custom module property is in the format of Module identifier:Property identifier. Example: 

"test:Power": {
      "value": "on",
      "time": 1524448722000
    }
events Object The events to be submitted. You can specify the identifier, value, and time parameters for each event.

The identifier of a custom module property is in the format of Module identifier:Property identifier. Example: 

"test:alarmEvent": {
            "value": {
              "Power": "on", 
              "WF": "2"
            }, 
            "time": 1524448722000
}

Sample response in the Alink JSON format:

{
    "id":"123",
    "code":200,
    "data":{}
}

IoT Platform can forward submitted historical TSL data to your server or other Alibaba Cloud services by using the server-side subscription or data forwarding feature. For more information about the specific topics and data formats, see Format of historical TSL data.

Submit multiple device properties and events at a time

The following topics are used when a device sends requests to IoT Platform and IoT Platform sends responses to the device:

  • 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
          }
         ]
     }
}
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.
method String The request method. Set the value to thing.event.property.batch.post.
params Object The request parameters.
properties Object The properties to be submitted. You can specify the identifier, value, and time parameters for each property.

The identifier of a custom module property is in the format of Module identifier:Property identifier. Example: 

"test:Power": {
      "value": "on",
      "time": 1524448722000
    }
events Object The events to be submitted. You can specify the identifier, value, and time parameters for each event.

The identifier of a custom module property is in the format of Module identifier:Property identifier. Example: 

"test:alarmEvent": {
            "value": {
              "Power": "on", 
              "WF": "2"
            }, 
            "time": 1524448722000
}

Sample response in the Alink JSON format:

{
    "id":"123",
    "code":200,
    "data":{}
}

You can forward submitted TSL data 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.