All Products
Search
Document Center

IoT Platform:Submit a script to parse TSL data

Last Updated:Apr 03, 2023

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

  1. Create a product. In the IoT Platform console, create a product and set the Data Type parameter to Custom.
  2. Add a TSL feature: Define a TSL model for the product.

    In this example, three properties are defined. The following table describes the properties.

    IdentifierData typeValid valueRead/write type
    prop_floatFLOAT-100~100Read and write
    prop_int16INT32-100~100Read and write
    prop_boolBOOLEAN0: enabled and 1: disabledRead 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
      ParameterNumber of bytes
      Frame Type1 byte
      The ID of the request4 bytes
      prop_int162 bytes
      prop_bool1 byte
      prop_float 4 bytes
    • Responses to data reporting requests
      ParameterNumber of bytes
      Frame Type1 byte
      The ID of the request4 bytes
      Result code 1 byte
    • Requests to configure properties
      ParameterNumber of bytes
      Frame Type1 byte
      The ID of the request4 bytes
      prop_int162 bytes
      prop_bool1 byte
      prop_float 4 bytes
    • Responses to property configuration requests
      ParameterNumber of bytes
      Frame Type1 byte
      The ID of the request4 bytes
      Result code 1 byte
  3. 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 Message Analysis.
    3. Select a programming language and write a script in the Edit Script field.
      Supported scripting languageThe 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)rawDataToProtocolprotocolToRawDataSample JavaScript script
      Python 2.7raw_data_to_protocolprotocol_to_raw_dataPython sample script
      PHP 7.2rawDataToProtocolprotocolToRawDataPHP 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