This article describes how to create a product whose data type is custom, create a device for the product, obtain the device certificate, define a Thing Specification Language (TSL) model, and then write a data parsing script. After you perform these operations, you can connect the device to IoT Platform by using a data transmission unit (DTU) device.

Create a product and a device

In the IoT Platform console, create a product and a device, and obtain the device certificate. The device certificate consists of a ProductKey, a DeviceName, and a DeviceSecret.

  1. Log on to the IoT Platform console.
  2. In the left-side navigation pane, choose Devices > Products. On the Products page, click Create Product and create a product.
    Table 1. Product information
    Parameter Description
    Product Name The name of the product.
    Category Select Custom Category.
    Node Type Select Directly Connected Device.
    Network Connection Method Select Cellular (2G / 3G / 4G / 5G).
    Data Type Select Custom.
    Authentication Mode Select Device Secret.
  3. In the left-side navigation pane, choose Devices > Devices. On the Devices page, click Add Device and create a device for the product.
    After the device is created, go to the Devices page. Find the created device and click View in the Actions column. On the Device Details page, view the information about the device certificate. The device certificate must be configured on a DTU device.

Define a TSL model

A TSL model is a data model that digitizes a physical entity and constructs the entity in the cloud. In IoT Platform, a TSL model refers to a set of features. After you define features for a product, IoT Platform generates a TSL model for the product. In this example, the RotateSpeed, Current, and RotateSpeedSet properties are defined for a variable frequency motor.

  1. Log on to the IoT Platform console. In the left-side navigation pane, choose Devices > Products.
  2. On the Products page, find the product that you want to configure and click View in the Actions column.
  3. On the Product Details page, click the Define Feature tab, and then click Edit Draft. On the Edit Draft page, click Add Self-defined Feature.
  4. Create the properties that are described in the following table. Then, click Release online to publish the TSL model.
    Feature Type Feature Name Identifier Data Type Value Range Step Unit Read/Write Type
    Properties RotateSpeed speed int32 0 ~ 3000 1 r/min Read-only
    Properties Current current int32 0 ~ 300 1 A Read-only
    Properties RotateSpeedSet setspeed int32 0 ~ 3000 1 r/min Read/Write

Write a data parsing script

IoT Platform processes data of the Alink JSON format. If devices communicate with IoT Platform by using DTU devices, IoT Platform cannot process pass-through data that is sent from the devices. IoT Platform provides the data parsing feature. This feature allows you to convert the custom format of upstream data into the Alink JSON format and the format of downstream data into the custom format of your device. To use the data parsing feature, you must write a data parsing script in the IoT Platform console and submit the script to IoT Platform. You must write a data parsing script based on upstream and downstream data.

  1. Log on to the IoT Platform console, go to the Product Details page, and then click the Data Parsing tab.
  2. On the Data Parsing tab, enter a data parsing script in the Edit Script field.
    For more information about how to write a data parsing script, see Submit a data parsing script.

    In this example, a device sends data of the hexadecimal format to IoT Platform. Therefore, you must use a data parsing script to convert upstream data of the hexadecimal format into data of the Alink JSON format and downstream data of the Alink JSON format into data of the hexadecimal format.

    The following code provides an example on how to write a data parsing script:

    var ALINK_ID = "12345";
    var ALINK_VERSION = "1.1";
    var ALINK_PROP_POST_METHOD = 'thing.event.property.post';
    // var ALINK_EVENT_TEMPERR_METHOD = 'thing.event.TempError.post';
    // var ALINK_EVENT_HUMIERR_METHOD = 'thing.event.HumiError.post';
    var ALINK_PROP_SET_METHOD = 'thing.service.property.set';
    // var ALINK_SERVICE_THSET_METHOD = 'thing.service.SetTempHumiThreshold';
    /* * * * * *
    * Upstream data:
    * 0102 // Two bytes in total * Results:
    * {"method":"thing.event.TempError.post","id":"12345","params":{"Temperature": 2},"version":"1.1"}
    * Upstream data:
    * 0202 // Two bytes in total * Results:
    * {"method":"thing.event.HumiError.post","id":"12345","params":{"Humidity":2}, "version":"1.1"}
    */
    /* The rawDataToProtocol function converts upstream data that is reported by a device into TSL data of the Alink JSON format. */
    function rawDataToProtocol(bytes) {
        /* Convert upstream data into an array. Upstream data is stored in the bytes object. */
        var uint8Array = new Uint8Array(bytes.length);
        for (var i = 0; i < bytes.length; i++) {
            uint8Array[i] = bytes[i] & 0xff;
        }
    
        var params = {};                            // Create an object to store device properties.
        var jsonMap = {};                           // Create an object to define the format of an Alink message.
    
        /* Specify header fields for an Alink message. */
        jsonMap['version'] = ALINK_VERSION;         // The version number of the Alink protocol.
        jsonMap['id'] = ALINK_ID;                   // The ID of the Alink message.
        jsonMap['method'] = ALINK_PROP_POST_METHOD; // The method that is used to report device properties.
        /* Specify properties for the Alink message. */
        params['speed'] = uint8Array[0];            // Convert the first received byte into the value of the RotateSpeed property.
        params['current'] = uint8Array[1];          // Convert the second received byte into the value of the Current property.
        jsonMap['params'] = params;                 // Pack the required parameters to a JSON array.
    
        return jsonMap;                             // Return the results to IoT Platform.
    }
    
    // The following code describes helper functions:
    function buffer_uint8(value)
    {
        var uint8Array = new Uint8Array(1);
        var dv = new DataView(uint8Array.buffer, 0);
        dv.setUint8(0, value);
        return [].slice.call(uint8Array);
    }
    function buffer_int16(value)
    {
        var uint8Array = new Uint8Array(2);
        var dv = new DataView(uint8Array.buffer, 0);
        dv.setInt16(0, value);
        return [].slice.call(uint8Array);
    }
    function buffer_int32(value)
    {
        var uint8Array = new Uint8Array(4);
        var dv = new DataView(uint8Array.buffer, 0);
        dv.setInt32(0, value);
        return [].slice.call(uint8Array);
    }
    function buffer_float32(value)
    {
        var uint8Array = new Uint8Array(4);
        var dv = new DataView(uint8Array.buffer, 0);
        dv.setFloat32(0, value);
        return [].slice.call(uint8Array);
    }
    /* The protocolToRawData function converts downstream data into hexadecimal data that can be recognized by the device. */
    function protocolToRawData(json)
    {
        var method = json['method'];
        var id = json['id'];
        var version = json['version'];
    
        var payloadArray = [];
        if (method == ALINK_PROP_SET_METHOD)    // If the device receives the Set Device Properties command from IoT Platform, the following code is run:
        {
            var send_params = json['params'];
            var prop_cur = send_params['setspeed'];   // Specify the received value for the prop_cur parameter.
    
            // Concatenate raw data based on the custom format.
            payloadArray = payloadArray.concat(buffer_uint8(0x55)); // The first byte that indicates the header of a message.
            payloadArray = payloadArray.concat(buffer_uint8(prop_bool)); // The second byte that indicates the value of a property.
        }
    
        return payloadArray;    // Send values to the device.
    }
    function transformPayload(topic, rawData) {
        var jsonObj = {};
        return jsonObj;
    }                        
  3. Test the script.
    • Test the parsing of data that is reported by a device.
      1. Select Upstreamed Device Data from the Simulation Type drop-down list.
      2. On the Input Simulation tab, enter test data in the field.

        The preceding script specifies the first byte as the value of the RotateSpeed property and the second byte as the Current property. If you enter 6410, the first byte 64 indicates that the rotating speed is 100 rpm and the second byte 10 indicates that the electric current is 16 A.

      3. Click Run.

        The Parsing Results tab displays the results, as shown in the following figure.

        Parsing Results tab
    • Test the parsing of data that is sent by IoT Platform.
      1. Select Received Device Data from the Simulation Type drop-down list.
      2. On the Input Simulation tab, enter test data in the field. Sample downstream data:
        {
            "method": "thing.service.property.set",
            "id": "12345",
            "version": "1.0",
            "params": {
                "setspeed": 123
            }
        }
      3. Click Run.

        The Parsing Results tab displays the results, as shown in the following figure.

        Parsing Results tab
  4. After you confirm that test data can be parsed by the script as expected, click Submit to submit the script to IoT Platform.
    Note IoT Platform cannot call scripts that are in the draft state. Before IoT Platform can call a script, you must submit the script.

What to do next

Configure a DTU device