Submit a script to parse TSL data - IoT Platform - Alibaba Cloud Documentation Center

This topic describes how to write a script to parse Thing Specification Language (TSL) data for products whose Data Type parameter is set to Custom and submit the script. This topic also provides sample scripts that can be used to parse upstream and downstream property data.

Prerequisites

The Data Type parameter of a product is set to Custom when you created the product. For more information, see Create a product.

Background information

The Data Type parameter is set to ICA Standard Data Format (Alink JSON). In this case, devices generate data in the Alink JSON format, and then report the data to IoT Platform. For more information about the Alink JSON data format, see Device properties, events, and services.

The Data Type parameter is set to Custom. In this case, IoT Platform uses the data parsing scripts that you submitted to convert upstream TSL data to Alink JSON-formatted data and converts downstream TSL data to device data in a custom format when devices communicate with IoT Platform.

Note In this example, the properties of the default module are used. If you use a custom module, you must specify each identifier in the following format: ${Module identifier}:${Property identifier}. Example: model1:prop_int16.

Step 1: Write a script

Create a product. In the IoT Platform console, create a product and set the Data Type parameter to Custom.
Add a TSL feature: Define a TSL model for the product.
In this example, three properties are defined. The following table describes the properties.
Identifier Data type Valid value Read/write type
prop_float FLOAT -100~100 Read and write
prop_int16 INT32 -100~100 Read and write
prop_bool BOOLEAN 0: enabled and 1: disabled Read and write
The script is written to parse upstream and downstream TSL data based on the TSL model.
In this example, the lengths of the values of parameters that are used for data communication are specified. The following table describes the lengths.
- Requests that devices send to report data
  Parameter Number of bytes
  Frame Type 1 byte
  The ID of the request 4 bytes
  prop_int16 2 bytes
  prop_bool 1 byte
  prop_float 4 bytes
- Responses to data reporting requests
  Parameter Number of bytes
  Frame Type 1 byte
  The ID of the request 4 bytes
  Result code 1 byte
- Requests to configure properties
  Parameter Number of bytes
  Frame Type 1 byte
  The ID of the request 4 bytes
  prop_int16 2 bytes
  prop_bool 1 byte
  prop_float 4 bytes
- Responses to property configuration requests
  Parameter Number of bytes
  Frame Type 1 byte
  The ID of the request 4 bytes
  Result code 1 byte

Write a script.

On the Products page, find the product that you want to manage and click View in the Actions column.
On the product details page, click Message Analysis.

Select a programming language and write a script in the Edit Script field.

Supported scripting language	The function that converts upstream data in a custom format to Alink JSON-formatted data:	The function that converts Alink JSON-formatted data to downstream data in a custom format:	Sample code
JavaScript (ECMAScript 5)	rawDataToProtocol	protocolToRawData	Sample JavaScript script
Python 2.7	raw_data_to_protocol	protocol_to_raw_data	Python sample script
PHP 7.2	rawDataToProtocol	protocolToRawData	PHP sample script

Note You must write a script that can be used to parse data that is sent to custom topics. For information about how to write the script, see Submit a message parsing script.

For information about the complete sample scripts that can be used to parse data that is sent to custom topics and to parse TSL data, see Sample JavaScript code used to parse custom data, Complete sample script in Python, and Sample PHP code used to parse custom data.

Step 2: Test the script online

Important The hexadecimal string and JSON-formatted data that are specified and returned in this example are used only for testing and cannot be used for debugging in actual scenarios.

After you write the script, configure the Simulation Type parameter and specify simulated data on the Input Simulation tab to test the script.

Test the script by using simulated property data that a device reports to IoT Platform.
Set the Simulation Type parameter to Upstreamed Device Data, enter the following simulated data, and then click Run.
Note In this example, simulated JavaScript data is used. For more information about sample JavaScript scripts, see Sample JavaScript script.
For information about sample Python and PHP scripts, see Python sample script and PHP sample script.
You can use a tool that converts strings to hexadecimal data to convert the JSON-formatted data into hexadecimal data. For example, if the converted hexadecimal data is 00002233441232013fa00000, specify the following data:
```
0x00002233441232013fa00000
```
The data parsing engine converts the pass-through data into JSON-formatted data based on the rules that are defined in the script.
Click Parsing Results. The Parsing Results tab displays the parsed data.
```
{
    "method": "thing.event.property.post", 
    "id": "2241348", 
    "params": {
        "prop_float": 1.25, 
        "prop_int16": 4658, 
        "prop_bool": 1
    }, 
    "version": "1.0"
}
```
Test the script by using simulated result data that IoT Platform returns to a device.
Set the Simulation Type parameter to Received Device Data, enter the following JSON-formatted data, and then click Run.
```
{
  "id": "12345",
  "version": "1.0",
  "code": 200,
  "method": "thing.event.property.post",
  "data": {}
}
```
The data parsing engine converts the JSON-formatted data into the following data:
```
0x0200003039c8
```
Test the script by using simulated data that IoT Platform sends to a device to request the device to modify properties.
Set the Simulation Type parameter to Received Device Data, enter the following JSON-formatted data, and then click Run.
```
{
    "method": "thing.service.property.set", 
    "id": "12345", 
    "version": "1.0", 
    "params": {
        "prop_float": 123.452, 
        "prop_int16": 333, 
        "prop_bool": 1
    }
}
```
The data parsing engine converts the JSON-formatted data into the following data:
```
0x0100003039014d0142f6e76d
```
Test the script by using simulated result data that a device returns to IoT Platform after the device modifies the properties.
Set the Simulation Type parameter to Upstreamed Device Data, enter the following data, and then click Run.
```
0x0300223344c8
```
The data parsing engine converts the pass-through data into the following JSON-formatted data:
```
{
  "code": "200",
  "data": {},
  "id": "2241348",
  "version": "1.0"
}
```

Step 3: Submit the script

Important Before IoT Platform can run scripts, you must submit the scripts to IoT Platform. Scripts that are in the Draft state cannot be called.

After you confirm that the script can parse data as expected, click Submit to submit the script to IoT Platform. IoT Platform can use the script to parse upstream and downstream data.

Step 4: Use a physical device for debugging

Before you use the script in your business, use a physical device to communicate with IoT Platform. This way, you can check whether IoT Platform can call the script and parse upstream and downstream data.

You can use an IoT Platform Link SDK to configure a device and connect the device to IoT Platform. For more information, see Link SDK.

Verify that IoT Platform can call the script to parse upstream property data.
1. Use the device to report property data to IoT Platform, such as 0x00002233441232013fa00000.
2. In the IoT Platform console, choose Devices > Devices in the left-side navigation pane.
3. On the Devices page, find the device and click View in the Actions column. On the Device Details page, click the TSL Data tab and then the Status tab. Check whether the reported property data exists.
Verify that IoT Platform can call the script to parse downstream property data.
1. Log on to the IoT Platform console. In the left-side navigation page, choose Maintenance > Online Debug.
2. On the Online Debug page, select the product and device that you want to debug and then select Default Module. Select the identifier of the property that you want to debug, such as prop_int16. Set the method to Set. Enter the following data and click Send Command.
```
{
    "method": "thing.service.property.set", 
    "id": "12345", 
    "version": "1.0", 
    "params": {
        "prop_float": 123.452, 
        "prop_int16": 333, 
        "prop_bool": 1
    }
}
```
3. Check whether the device receives the command to configure properties.
4. On the Device Details page, choose TSL Data > Status. On the tab that appears, check whether the current property data is reported by the device.

Optional. Update the message parsing script.

After you submit the message parsing script, you can modify or delete the code of the script and then re-submit the script on the Message Analysis tab.

Warning After you modify or delete the code of the script and then re-submit the script, the message parsing service is unavailable for the devices in the product and your business is interrupted. Proceed with caution.

References

For information about the process of data parsing, see Message parsing.
For more information about how to parse data that is sent to custom topics, see Submit a message parsing script.
For information about the API operations that are used to send messages to devices, see Use of TSL models and Messaging.

Identifier	Data type	Valid value	Read/write type
prop_float	FLOAT	-100~100	Read and write
prop_int16	INT32	-100~100	Read and write
prop_bool	BOOLEAN	0: enabled and 1: disabled	Read and write

Parameter	Number of bytes
Frame Type	1 byte
The ID of the request	4 bytes
prop_int16	2 bytes
prop_bool	1 byte
prop_float	4 bytes