Submit a TSL model message parsing script-IoT Platform (Deprecated)(IoT)-阿里云帮助中心

This topic provides an example of a script that parses property data from mobile originated and mobile terminated messages. It describes how to write and submit a TSL model message parsing script for a product that uses the pass-through or custom data format.

Prerequisites

The data format for the product is set to Pass-through/Custom. For more information, see Create a product.

Background information

If the data format is ICA standard data format, devices generate and report messages in the standard data format defined by IoT Platform. For information about the standard Alink JSON data format, see Device properties, events, and services.

If the data format is Pass-through/Custom, IoT Platform calls the message parsing script that you submit during device communication. The script parses mobile originated TSL model messages into the standard Alink JSON format defined by IoT Platform. The script also parses mobile terminated TSL model messages into the custom data format of the device.

Note The properties in this example are properties of the default module. If you use a custom module, the format of an identifier is ${ModuleIdentifier}:${PropertyIdentifier}. For example, model1:prop_int16.

Step 1: Edit the script

Create a product: In the IoT Platform console, set Data Format to Pass-through/Custom.
Add a TSL model.
This example defines the following three properties:
Identifier Data type Value range Read/Write type
prop_float float -100 to 100 Read/Write
prop_int16 int32 -100 to 100 Read/Write
prop_bool bool 0: On; 1: Off Read/Write
The message parsing script is written based on the TSL model defined here. The script parses data from mobile originated and mobile terminated TSL model messages.
The parameter value lengths for communication in this example are defined as follows:
- Device data reporting request
  Field Bytes
  Frame type 1 byte
  Request ID 4 bytes
  Property prop_int16 2 bytes
  Property prop_bool 1 byte
  Property prop_float 4 bytes
- Device data reporting response
  Field Bytes
  Frame type 1 byte
  Request ID 4 bytes
  Result code 1 byte
- Set property request
  Field Bytes
  Frame type 1 byte
  Request ID 4 bytes
  Property prop_int16 2 bytes
  Property prop_bool 1 byte
  Property prop_float 4 bytes
- Set property response
  Field Bytes
  Frame type 1 byte
  Request ID 4 bytes
  Result code 1 byte

Write the script.

On the Products page, find the product and click View.
On the Product Details page, click the Message Parsing tab.

Select a scripting language and enter the script in the input box under Edit Script.

Supported scripting language	Function to transform custom device data format to Alink JSON format (mobile originated communication)	Function to transform Alink JSON format to custom device data format (mobile terminated communication)	Sample code
JavaScript (ECMAScript 5)	rawDataToProtocol	protocolToRawData	JavaScript script sample
Python 2.7	raw_data_to_protocol	protocol_to_raw_data	Python script sample
PHP 7.2	rawDataToProtocol	protocolToRawData	PHP script sample

Note You also need to write a parsing script for mobile originated messages from custom topics. For more information, see Submit a message parsing script.

For complete sample scripts for parsing messages from custom topics and TSL models, see Complete sample script for pass-through/custom products (JavaScript), Complete sample script for pass-through/custom products (Python), and Complete sample script for pass-through/custom products (PHP).

Step 2: Test the script online

Important The hexadecimal strings and JSON data passed in and returned in the following examples are for reference only. Do not use them for testing in your actual scenario.

After you edit the script, in the Input Simulation section, select a Simulation Type and enter simulated data to test the script online.

Simulate parsing property data reported by a device.
Select Data reported by device as the simulation type, enter the following simulated data, and then click Execute.
Note The following simulated request parameter data is for JavaScript scripts. For more sample content, see JavaScript script sample.
For simulated request parameter data for Python and PHP scripts, see Python script sample and PHP script sample.
You can use a string-to-hexadecimal converter to convert the JSON request parameter data to hexadecimal data. For example, if the converted data is 00002233441232013fa00000, enter the following data.
```
0x00002233441232013fa00000
```
The DPI engine transforms the pass-through data into JSON data based on the script rules.
Click Running Result to view the parsing result.
```
{
    "method": "thing.event.property.post", 
    "id": "2241348", 
    "params": {
        "prop_float": 1.25, 
        "prop_int16": 4658, 
        "prop_bool": 1
    }, 
    "version": "1.0"
}
```
Simulate parsing the response data sent by IoT Platform.
Select Device Accepts Data as the impersonation type, enter the following data in JSON format, and then click Execute.
```
{
  "id": "12345",
  "version": "1.0",
  "code": 200,
  "method": "thing.event.property.post",
  "data": {}
}
```
The data parsing engine transforms JSON data into the following:
```
0x0200003039c8
```
Simulate parsing the property setting data sent by IoT Platform.
Select Device Accepts Data as the impersonation type, enter the following data in JSON format, and then click Execute.
```
{
    "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 transforms JSON data into the following:
```
0x0100003039014d0142f6e76d
```
Simulate parsing the property setting response data returned by the device.
For Impersonation type, select Device-reported data, enter the following data, and then click Execute.
```
0x0300223344c8
```
The DPI engine transforms the pass-through data into the following JSON data:
```
{
  "code": "200",
  "data": {},
  "id": "2241348",
  "version": "1.0"
}
```

Step 3: Submit the script

Important Only submitted scripts can be called by IoT Platform. Scripts in draft status cannot be called.

After you confirm that the script parses data correctly, click Submit. The script is submitted to IoT Platform. IoT Platform calls the script to parse data during mobile originated and mobile terminated communication.

Step 4: Test with a real device

Before you use the script in a production environment, use a real device to communicate with IoT Platform to verify that the script can successfully parse mobile originated and mobile terminated data.

You can use the Link SDK provided by IoT Platform to develop a device and connect it to IoT Platform. For more information, see Link SDK.

Test reporting property data.
1. Use the device to report property data, such as 0x00002233441232013fa00000.
2. In the IoT Platform console, choose Device Management > Devices.
3. Find the device and click View. On the Device Details page, click the TSL Data > Status tab and verify that the corresponding property data is displayed.
Test sending property data.
1. In the IoT Platform console, choose Monitoring and Maintenance > Online Debug.
2. Select the product and device that you want to test. Select Default Module. For Function, select the identifier of the property that you want to test, such as Property (prop_int16). Set 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. Verify that the device receives the property setting instruction.
4. On the Device Details page of the device, click the TSL Data > Status tab and verify that the device reports the current property data.

(Optional) Update the message parsing script

After the message paring script is submitted, you can modify or delete the script on the Message Analysis tab, and then test and submit the new script according to the steps described in this topic. After the script is submitted, it will take effect on all the existing devices of the product in about a minute. It will also take effect on newly added devices of the product.

Warning

After the script is modified and resubmitted, make sure that the code related to the message parsing service is also modified. Otherwise, business interruptions may occur.
After the script is deleted, the message parsing service becomes unavailable, which may interrupt your business.

Proceed with caution.

References

To learn basic information such as the message parsing flow, see What is message parsing?.
For information about parsing messages from custom topics, see Submit a message parsing script.
For information about calling an API to send messages to a device, see APIs for TSL models and APIs for message communication.
For information about how to troubleshoot data parsing issues, see Troubleshooting.

Identifier	Data type	Value range	Read/Write type
prop_float	float	-100 to 100	Read/Write
prop_int16	int32	-100 to 100	Read/Write
prop_bool	bool	0: On; 1: Off	Read/Write

Field	Bytes
Frame type	1 byte
Request ID	4 bytes
Property prop_int16	2 bytes
Property prop_bool	1 byte
Property prop_float	4 bytes