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

For more information about the syntax 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 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. IoT Platform parses the raw data into the Alink JSON format based on user-defined scripts that you submitted to IoT Platform. For more information, see What is data 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. TSL data transmission

Devices submit property data to IoT Platform

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 needs to submit to IoT Platform.
    Note
    • Hexidecimal data is transmitted 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. The IDs of the messages for a device must be unique.
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 a response to the registration request. Valid values:
  • 1: IoT Platform returns a response.
  • 0: IoT Platform does not return a response.
Notice For more information about how to configure this feature, see Device Modelling Programming.

If this feature is not configured, this parameter is unavailable. By default, IoT Platform returns a response to the registration request.

method String The request method. Example: thing.event.property.post.
params Object The property data that a device needs to submit in the request. In the preceding example, the device submits the information about the Power (power supply) and WF (working current) properties. The information contains the timestamp that indicates when the property is submitted and the value of the property.

The identifier of a property in a custom module is in the ${Module identifier}:${Property identifier} format. Separate the module identifier and property identifier with a colon (:). Examples: 

"test:Power": {
      "value": "on",
      "time": 1524448722000
    }
time Long The UTC timestamp that indicates 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. This helps you identify the order of messages.

  • If a request contains the time parameter, IoT Platform saves the parameter value as the timestamp that indicates when the property is submitted.
  • If a request does not contain the time parameter, IoT Platform automatically generates a timestamp that indicates when the property is submitted.
value Object The value of the property to be submitted.
Table 2. Response parameters
Parameter Type Description
id String The ID of the message. Valid values: 0 to 4294967295. The IDs of the messages for a device must be unique.
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 defined in the TSL model. If a property 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 that of the method parameter in the request.
version String The version number of the protocol. The parameter value is the same as that 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 the 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 Data formats.

Modify device properties

You can call the SetDeviceProperty or SetDevicesProperty operation to send commands to devices to modify device properties.

Topics and data formats used to send data from IoT Platform to devices:
Data format (from IoT Platform to devices) Request topic and response topic
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. The IDs of the messages for a device must be unique.

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, the temperature property is set to 30.5 and { "temperature": "30.5" } is displayed.

The identifier of a property in a custom module is in the ${Module identifier}:${Property identifier} format. Separate the module identifier and property identifier with a colon (:). Example: { "test:temperature": "30.5" }.

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. The IDs of the messages for a device must be unique.
code Integer The status code. For more information, see Common codes on devices.
data Object This parameter is left empty if the request is successful.
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 that 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 the updated property information 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

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 needs to 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 formats
    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. The IDs of the messages for a device must be unique.
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 a response to the registration request. Valid values:
  • 1: IoT Platform returns a response.
  • 0: IoT Platform does not return a response.
Notice For more information about how to configure this feature, see Device Modelling Programming.

If this feature is not configured, this parameter is unavailable. By default, IoT Platform returns a response to the 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) properties. 
{
   "Power": "on",
   "WF": "2"
}
time Long The UTC timestamp that indicates 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. This helps you identify the order of messages.

  • If a request contains the time parameter, IoT Platform saves the parameter value as the timestamp that indicates when the event is submitted.
  • If a request does not contain the time parameter, IoT Platform automatically generates a timestamp that indicates when the event is submitted.
Table 6. Response parameters
Parameter Type Description
id String The ID of the message. Valid values: 0 to 4294967295. The IDs of the messages for a device must be unique.
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 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 This parameter is left empty if the request is successful.
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 that of the method parameter in the request.
version String The version number of the protocol. The parameter value is the same as that 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 about the parameters, 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 the event 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 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 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 call a service, see Alink protocol.
  • Synchronous mode: 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 you call 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 call services. IoT Platform pushes requests to devices in asynchronous mode. The devices also respond in asynchronous mode. If you call 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 topic and response topic
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. The IDs of the messages for a device must be unique.

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 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. The IDs of the messages for a device must be unique.
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 that 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 a time

Gateways can submit multiple properties and events to IoT Platform at a time. A 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 a time.
  • A gateway can submit data for a maximum of 20 sub-devices at a time.
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 gateway needs to 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.property.pack.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
    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_replyThe 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. The IDs of the messages for a device must be unique.
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 a response to the registration request. Valid values:
  • 1: IoT Platform returns a response.
  • 0: IoT Platform does not return a response.
Notice For more information about how to configure this feature, see Device Modelling Programming.

If this feature is not configured, this parameter is unavailable. By default, IoT Platform returns a response to the registration request.

params Object The property data and event data that a gateway needs to 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. This helps you identify the order of messages.

In the preceding example, the gateway submits information about the Power (power supply) and WF (working current) properties.

The identifier of a property in a custom module is in the ${Module identifier}:${Property identifier} format. Separate the module identifier and property identifier with a colon (:). Examples: 

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

The identifier of an event in a custom module is in the ${Module identifier}:${Event identifier} format. Separate the module identifier and event identifier with a colon (:). Examples: 

"test:alarmEvent1": {
        "value": {
          "param1": "on",
          "param2": "2"
        },
        "time": 1524448722000
      }
subDevices Object The information about the attached device.
productKey String The key of the product to which the attached device belongs.
deviceName String The name of the attached device.
method String The request method. Set the parameter 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. The IDs of the messages for a device must be unique.
code Integer The status code. The value 200 indicates that the request is successful.
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 This parameter is left empty if the request is successful.
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 that of the method parameter in the request.
version String The version number of the protocol. The parameter value is the same as that 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.

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. The IDs of the messages for a device must be unique.
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 a response to the registration request. Valid values:
  • 1: IoT Platform returns a response.
  • 0: IoT Platform does not return a response.
Notice For more information about how to configure this feature, see Device Modelling Programming.

If this feature is not configured, this parameter is unavailable. By default, IoT Platform returns a response to the 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 needs to submit in the request.
identity String The certificate information about the device to which the historical 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.

The identifier of a property in a custom module is in the ${Module identifier}:${Property identifier} format. Separate the module identifier and property identifier with a colon (:). Examples: 

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

The identifier of an event in a custom module is in the ${Module identifier}:${Event identifier} format. Separate the module identifier and event identifier with a colon (:). Examples: 

"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. The IDs of the messages for a device must be unique.
code Integer The status code. For more information, see Common codes on devices.
data Object This parameter is left empty if the request is successful.
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 that of the method parameter in the request.
version String The version number of the protocol. The parameter value is the same as that 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.
Notice When IoT Platform forwards historical TSL data, IoT Platform creates a message for each property in properties and each event in events. The messages are used to forward the historical data of properties and events.

Devices submit multiple properties and events to IoT Platform at a 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. The IDs of the messages for a device must be unique.
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 a response to the registration request. Valid values:
  • 1: IoT Platform returns a response.
  • 0: IoT Platform does not return a response.
Notice For more information about how to configure this feature, see Device Modelling Programming.

If this feature is not configured, this parameter is unavailable. By default, IoT Platform returns a response to the 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 needs to 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 a time.

The identifier of a property in a custom module is in the ${Module identifier}:${Property identifier} format. Separate the module identifier and property identifier with a colon (:). Examples: 

"test:Power": {
      "value": "on",
      "time": 1524448722000
    }
events Object The events to be submitted. 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 a time.

The identifier of an event in a custom module is in the ${Module identifier}:${Event identifier} format. Separate the module identifier and event identifier with a colon (:). Examples: 

"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. The IDs of the messages for a device must be unique.
code Integer The status code. For more information, see Common codes on devices.
data Object This parameter is left empty if the request is successful.
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 that of the method parameter in the request.
version String The version number of the protocol. The parameter value is the same as that 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 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 relevant topics and data formats, see Submit device properties in batches and Submit device events in batches.