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.TSL model-based pass-through

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.

Note Raw data that is transmitted over MQTT is in the hexadecimal format.

Example:

0x00002233441232013fa00000
Note

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"
}
Table 1. Request parameters
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": {}
}
Table 2. Response parameters
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.
Table 3. Error codes
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"
}
Table 4. Request parameters
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": {}
}
Table 5. Response parameters
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
Note

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"
}
Table 6. Request parameters
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:
{
      "Power": "on",
      "WF": "2"
    }
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": {}
}
Table 7. Response parameters
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

IoT Platform allows you to invoke services in a synchronous or asynchronous manner. When you define a service, you must specify the invocation method for the service. For more information, see Service invocation process in Alink.
  • 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}"
}
Table 8. Request parameters
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:
{
      "Power": "on",
      "WF": "2"
    }
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": {}
}
Table 9. Response parameters
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.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.

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

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"
}
Table 10. Request parameters
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": {}
}
Table 11. Response parameters
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
          }
        }
      ]
    }
  ]
}
Table 12. Request parameters
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.