If you have defined the TSL for a product, the devices of this product can separately report data regarding the properties, events, and services that you have defined. For information about the data format of TSL, see Data format . This topic describes how data is reported based on the TSL.

When you create a product, you must select a data type for devices of the product. IoT Platform supports two data types: ICA Standard Data Format (Alink JSON) and Do not parse/Custom. We recommend that you select Alink JSON, because it is the standard data format of IoT Platform.
  • ICA Standard Data Format (Alink JSON): Devices generate data in the standard format defined by IoT Platform, and then report the data to IoT Platform. The following sections provide examples of Alink JSON data format.
  • Do not parse/Custom: Devices report raw data, such as binary data, to IoT Platform, and then IoT Platform parses the raw data to be standard data using the parsing script that you have submitted in the console. Data generated by IoT Platform is in Alink JSON format, and before sending the data to devices, IoT Platform will parse the data to the format that the devices support.

Devices report properties

Report data (Do not parse/Custom)

  • 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:

0x020000007b00

Response message from IoT Platform:

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

Report Data (Alink JSON)

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

Request message:

{
  "id": "123",
  "version": "1.0",
  "params": {
    "Power": {
      "value": "on",
      "time": 1524448722000
    },
    "WF": {
      "value": 23.6,
      "time": 1524448722000
    }
  },
  "method": "thing.event.property.post"
}
Table 1. Request Parameters
Parameter Type Description
id String The message ID. You need to define IDs for upstream messages using numbers, and the message IDs must be unique within the device.
version String The protocol version. Currently, the value is 1.0.
params Object The request parameters. In the preceding request example, the device reports two properties: Power and WF. Property information includes time (the time when the property is reported) and value (the value of the property).
time Long The time when the property is reported.
value Object The value of the property.
method String Request method. The value is thing.event.property.post.

Response message:

{
  "id": "123",
  "code": 200,
  "data": {}
}
Table 2. Response parameters
Parameter Type Description
id String The message ID.
code Integer The result code. See Common codes on devices.
data String The data that is returned when the request is successful.
Table 3. Error codes
Error code Error message Description
460 request parameter error The request parameters are incorrect.
6106 map size must less than 200 The number of reported properties exceeds the maximum limit. Up to 200 properties can be reported at a time.
6313 tsl service not available

The TSL verification service is not available.

IoT Platform verifies all the received properties according to the TSLs of products.

If the TSL verification service is available, but some reported properties do not match with any properties defined in the TSL, IoT Platform ignores the invalid properties. If all the reported properties do not match with any properties defined in the TSL, IoT Platform ignores them all. In this case, the response will still indicate that the verification is successful.

This error is reported when a system exception occurs.

You can use the Rules engine to forward property information reported by devices to other supported Alibaba Cloud services. For more information about topics and data formats, see Messages about device properties reported by devices.

Set device properties

Push data to devices (Do not parse/Custom)

  • Request topic: /sys/{productKey}/{deviceName}/thing/model/down_raw
  • Response topic: /sys/{productKey}/{deviceName}/thing/model/down_raw_reply

Push data to devices (Alink JSON)

  • Request topic: /sys/{productKey}/{deviceName}/thing/service/property/set
  • Response topic: /sys/{productKey}/{deviceName}/thing/service/property/set_reply

Request message:

{
  "id": "123",
  "version": "1.0",
  "params": {
    "temperature": "30.5"
  },
  "method": "thing.service.property.set"
}
Table 4. Request Parameters
Parameter Type Description
id String The message ID. IoT Platform generates IDs for downstream messages.
version String The protocol version. Currently, the value is 1.0.
params Object The property parameters. In the preceding request example, the property to be set is
{ "temperature": "30.5" }
method String Request method. The value is thing.service.property.set.

Response message:

{
  "id": "123",
  "code": 200,
  "data": {}
}
Table 5. Response parameters
Parameter Type Description
id String The message ID.
code Integer The result code. See Common codes on devices.
data String The data that is returned when the request is successful.

You can use the Rules engine to forward the property setting results from devices to other supported Alibaba Cloud services. For message topics and data formats, see Devices return result data to the cloud.

Devices report events

Report data (Do not parse/Custom)

  • 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,
    "method":"thing.event.{tsl.event.identifier}.post"
    "data":{}
}

Report Data (Alink JSON)

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

Request message:

{
  "id": "123",
  "version": "1.0",
  "params": {
    "value": {
      "Power": "on",
      "WF": "2"
    },
    "time": 1524448722000
  },
  "method": "thing.event.{tsl.event.identifier}.post"
}
Table 6. Request Parameters
Parameter Type Description
id String The message ID. You need to define IDs for upstream messages using numbers, and the message IDs must be unique within the device.
version String The protocol version. Currently, the value is 1.0.
params List The parameters of the reported events.
value Object The event information. In the preceding request example, the events are:
{
      "Power": "on",
      "WF": "2"
    }
time Long The UTC timestamp when the event occurs.
method String Request method.
Note tsl.event.identifier indicates the event identifier in the TSL. For information about TSL template, see Overview.

Response message:

{
  "id": "123",
  "code": 200,
  "data": {}
}
Table 7. Response parameters
Parameter Type Description
id String The message ID.
code Integer The result code. See Common codes on devices.
Note IoT Platform verifies all the events reported by devices according to the TSLs of products. If the reported event does not match with any events defined in the TSL, an error code is returned.
data String The data that is returned when the request is successful.

Examples

For example, an event alarm has been defined in the TSL of a product:

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

Request message of reporting an event:

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

You can use the Rules engine to forward event information reported by devices to other supported Alibaba Cloud services. For more information about topics and data formats, see Messages about events reported by devices

Call device services

Push data to devices (Do not parse/Custom)

  • Request topic: /sys/{productKey}/{deviceName}/thing/model/down_raw
  • Response topic: /sys/{productKey}/{deviceName}/thing/model/down_raw_reply

Push data to devices (Alink JSON)

  • Request topic: /sys/{productKey}/{deviceName}/thing/service/{tsl.service.identifier}
  • Response topic: /sys/{productKey}/{deviceName}/thing/service/{tsl.service.identifier}_reply

Service calling methods

Supports synchronous calls and asynchronous calls. When you define a service, you are required to select a method for the service.
  • Synchronous method: IoT Platform uses the RRPC method to push requests to devices. For information about the RRPC method, see What is RRPC.
  • Asynchronous method: IoT Platform pushes requests to devices in an asynchronous manner, and the devices return operation results in an asynchronous manner.

    Only when asynchronous method is selected for a service does IoT Platform subscribe to the response topic. You can use the Rules engine to forward the results of asynchronous calls returned by devices to other supported Alibaba Cloud services. For more information about topics and data formats, see Devices return result data to the cloud.

Request message:

{
  "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 message ID. IoT Platform generates IDs for downstream messages.
version String The protocol version. Currently, the value is 1.0.
params Map The parameters used to call a service, including the identifier and value of the service. Example:
{
      "Power": "on",
      "WF": "2"
    }
method String Request method.
Note tsl.service.identifier indicates the identifier of the service in TSL. For information about how to define a TSL, see Overview.

Response message:

{
  "id": "123",
  "code": 200,
  "data": {}
}
Table 9. Response parameters
Parameter Type Description
id String The message ID.
code Integer The result code. See Common codes on devices.
data String The data that is returned when the request is successful.

The value of data is determined by the TSL of the product. If the device does not return any information about the service, the value of data is empty. If the device returns service information, the returned data value will strictly comply with the definition of the service in the TSL.

Examples

For example, the service SetWeight has been defined in the TSL of the product as follows:

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

Request message of a service call:

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

Response message:

{
  "id": "105917531",
  "code": 200,
  "data": {
    "CollectTime": "1536228947682",
    "OldWeight": 100.101
  }
}

Gateway devices report data

A gateway device can report properties and events of itself and properties and events of its sub-devices to IoT Platform.

Note
  • A gateway can report up to 200 properties and 20 events at one time.
  • A gateway can report up to 20 properties and events of sub-devices.

Report data (Do not parse/Custom)

  • 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,
  "method": "thing.event.property.pack.post",
  "data": {}
}

Report data (Alink JSON)

  • Request topic: /sys/{productKey}/{deviceName}/thing/event/property/pack/post
  • Response topic: /sys/{productKey}/{deviceName}/thing/event/property/pack/post_reply

Request message:

{
  "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"
}
Table 10. Request Parameters
Parameter Type Description
id String The message ID. You need to define IDs for upstream messages using numbers, and the message IDs must be unique within the device.
version String The protocol version. Currently, the value is 1.0.
params Object The request parameters.
properties Object The information about a property, including property identifier, value and time when the property was generated.
events Object The information about an event, including event identifier, value and time when the event was generated.
subDevices Object The sub-device information.
productKey String The ProductKey of a sub-device.
deviceName String The name of a sub-device.
method String Request method. The value is thing.event.property.pack.post.

Response message:

{
  "id": "123",
  "code": 200,
  "data": {}
}
Table 11. Response parameters
Parameter Type Description
id String The message ID.
code Integer Result code. A value of 200 indicates that the request is successful.
Note IoT Platform then verifies the devices, topological relationships, and property and event definitions in the TSL. If any one of the verifications fails, the data report also fails.
data Object The data that is returned when the request is successful.