This article describes how to write code to parse Thing Specification Language (TSL) data for products whose Data Type parameter is set to Custom. Sample scripts are provided for parsing upstream and downstream property data.

Step 1: Write a script

Note The properties in this example are default module properties. If you use a custom module, each identifier must be in the following format: Module identifier:Property identifier. Example: model1:prop_int16.
  1. Log on to the IoT Platform console and create a product.
    For more information, see Create a product.
    Note Set the Data Type parameter to Custom.
  2. Define a TSL model for the product. For information about how to set custom properties, see Add a TSL feature.

    In this example, define the three properties that are described in the following table.

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

    The TSL model that is defined in this example is used to write the script for parsing upstream and downstream TSL data.

  3. Specify lengths for the parameters that are used for data communication. In this example, define the parameter lengths as described in the following tables.
    Table 1. Requests that devices send to report data
    Field Number of bytes
    Frame type 1
    Request ID 4
    prop_int16 2
    prop_bool 1
    prop_float 4
    Table 2. Responses to requests for reporting data
    Field Number of bytes
    Frame type 1
    Request ID 4
    Result code 1
    Table 3. Requests for setting properties
    Field Number of bytes
    Frame type 1
    Request ID 4
    prop_int16 2
    prop_bool 1
    prop_float 4
    Table 4. Responses to requests for setting properties
    Field Number of bytes
    Frame type 1
    Request ID 4
    Result code 1
  4. Write a script.
    1. On the Products page, find the product that you want to manage and click View in the Actions column.
    2. On the Product Details page, click the Data Parsing tab.
    3. Select a programming language and write a script in the Edit Script field.

      Only JavaScript (ECMAScript 5), Python 2.7, and PHP 7.2 are supported.

      In the script, define the two functions that can be called to parse upstream and downstream TSL data. Select the functions based on your selected programming language.

      • The function that converts Alink JSON-formatted data into data in a custom format:
        • JavaScript (ECMAScript 5): protocolToRawData
        • Python 2.7: protocol_to_raw_data
        • PHP 7.2: protocolToRawData
      • The function that converts data in a custom format into Alink JSON-formatted data:
        • JavaScript (ECMAScript 5): rawDataToProtocol
        • Python 2.7: raw_data_to_protocol
        • PHP 7.2: rawDataToProtocol

      For information about the complete sample script, see JavaScript example, Python example, and PHP example.

      Note You also need to write a script for parsing data that is sent to custom topics. For information about how to write the script, see Submit a data parsing script.

      For information about the complete sample scripts for parsing data that is sent to custom topics and for parsing TSL data in different programming languages, see Complete sample script in JavaScript, Complete sample script in Python, and Complete sample script in PHP.

Step 2: Test the script online

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

Note In this example, the hexadecimal string and JSON-formatted data that are specified and returned are used only for a test. Do not use them for debugging in actual scenarios.
  • 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 the JavaScript sample script, see JavaScript example.

    For information about Python and PHP sample scripts, see Python example and PHP example.

    You can use a tool that converts strings to hexadecimal data to convert the JSON-formatted data into hexadecimal data. For example, if the hexadecimal data after the conversion is 00002233441232013fa00000, enter 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 the Parsing Results tab and view 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 its 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

After you confirm that the script can properly parse data, click Submit to submit the script to IoT Platform. Then, IoT Platform can call this script to parse upstream and downstream data.

Note Scripts can be called only after they are submitted to IoT Platform. Scripts that are in the draft state cannot be called.
Submit the script

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 verifies that IoT Platform can call the script and parse upstream and downstream data.

  • 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. In the IoT Platform console, choose Maintenance > Online Debug in the left-side navigation pane.
    2. On the Online Debug page, select the product and device that you want to debug. 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 for setting properties.
    4. On the Device Details page, click the TSL Data tab and then the Status tab. Check whether the device has reported its current property data.

References