You can add a Thing Specification Language (TSL) feature, such as a property, event, or service. This topic describes how to define a TSL feature in the IoT Platform console.

Background information

  • If a product is published, you cannot edit the TSL model of the product. To edit a TSL model, you must unpublish the product for which the TSL model is defined.
  • You can edit one of the historical versions for a TSL model to generate a new version.
  • A TSL model can have a maximum of 10 versions that are recently created. Extra historical versions are overwritten.
  • After you edit a TSL model, you must publish the TSL model to apply the update.

Procedure

  1. Log on to the IoT Platform console.
  2. In the left-side navigation pane, choose Devices > Products.
  3. On the Products page, find the product to which you want to add features, and click View in the Actions column of the product.
  4. On the Product Details page, click the Define Feature tab, and click Edit Draft.
  5. Optional. From the Version History drop-down list, select a historical version that you want to edit, and click Restore to This Version to edit the TSL model of the historical version.
  6. Add a self-defined feature.

    Click Add Self-defined Feature. You can add a property, service, or event to the product.

    • Add a property: In the Add Self-defined Feature dialog box, select Properties in the Feature Type field. Set the required parameters, and click OK.Properties

      The following table describes the parameters.

      Parameter Description
      Feature Name

      The name of the property, for example, power consumption. Each feature name must be unique for a product.

      The feature name must be 1 to 30 characters in length, and can contain letters, digits, hyphens (-), and underscores (_). The feature name must start with a letter or digit.

      Identifier The ID of the property. Each ID must be unique for a product. The ID is indicated by the value of the identifier parameter in the Alink JSON format. A device uses the ID as the key to report property data, and IoT Platform verifies the ID to determine whether to receive the data. The ID must be 1 to 50 characters in length, and can contain letters, digits, and underscores (_), for example, PowerComsuption.
      Note You cannot set this parameter to one of the following reserved words: set, get, post, time, and value.
      Data Type
      • int32: 32-bit integer. You must specify a value range, step size, and unit.
      • float: single-precision floating-point number. You must specify a value range, step size, and unit.
      • double: double-precision floating-point number. You must specify a value range, step size, and unit.
      • enum: enumeration. You must specify a value and description for an ENUM item. Examples: 1-heating mode and 2-cooling mode.
      • bool: Boolean. You must use the numbers 0 and 1 to define Boolean values. Examples: 0-off and 1-on.
      • text: string. You must specify the length of a string. The string must be 1 to 2,048 bytes in length.
      • date: timestamp. A UTC timestamp. Data type: string. Unit: milliseconds.
      • struct: JSON object. You must define a JSON structure and add JSON parameters to the structure. For example, you can define the color of a lamp as a structure that is composed of the following three parameters: Red, Green, and Blue. Nested structures are not supported.
      • array: array. You must specify the data type and number of elements in an array. Valid values: int32, float, double, text, and struct. Make sure that the data types of elements in an array are the same. The number of elements ranges from 1 to 512.
      Note If the device connection protocol is Modbus, you do not need to specify this parameter.
      Value Range If the Data Type parameter is set to int32, float, or double, you must specify a value range for the property.
      Step The minimum granularity by which property values change. If the Data Type parameter is set to int32, float, or double, you must specify a step size based on your business requirements.

      For example, when you add the temperature property to a thermometer product, you set the Data Type parameter to int32, the Step parameter to 2, the Unit parameter to °C, and the Value Range parameter to 0 to 100. In this case, each time the temperature changes by 2 degrees, a device submits a temperature value, for example, 0°C, 2°C, 4°C, 6°C, or 8°C.

      Unit You can select None or other values based on your business requirements.
      Read/Write Type
      • Read/Write: Both GET and SET requests are supported.
      • Read-only: Only GET requests are supported.
      Note If the gateway connection protocol is Modbus, you do not need to specify this parameter.
      Description The description of the feature. The description must be 1 to 100 characters in length.
      Extended Information

      The mapping between the device connection protocol and the standard TSL. The extended information is included in the TSL extension configuration of the TSL model.

      If the gateway connection protocol is Custom, OPC UA, or Modbus, this parameter is required.

      • If the gateway connection protocol is Custom, enter a JSON-formatted description of custom configurations. The description must be 1 to 1,024 characters in length.
      • If the gateway connection protocol is OPC UA, enter a node name. Each node name that you specify for a property must be unique.
      • If the gateway connection protocol is Modbus, configure the following parameters:
        • Operation Type:
          • Coil Status (read only, 0x01)
          • Coil Status (read and write, 0x01-read, 0x05-write)
          • Coil Status (read and write, 0x01-read, 0x0F-write)
          • Discrete Input (read-only, 0x02)
          • Holding Registers (read-only, 0x03)
          • Holding Registers (read and write, 0x03-read, 0x06-write)
          • Holding Registers (read and write, 0x03-read, 0x10-write)
          • Input Registers (read-only, 0x04)
        • Register Address: You must specify a hexadecimal value that starts with 0x. Valid values: 0x0 to 0xFFFF, for example, 0xFE.
        • Original Data Type: Multiple data types are supported. Valid values: int16, uint16, int32, uint32, int64, uint64, float, double, string, and bool.
        • Value Range: The value range is retrieved after the original data is processed by using a specified scale factor. Data that exceeds the value range is discarded. IoT Platform sets the default value ranges for the following operation types:
          • Coil Status: 0 to 1
          • Discrete Input: 0 to 1
          • Holding Registers: -2147483648 to 2147483647
          • Input Registers: -2147483648 to 2147483647
        • Switch High Byte and Low Byte in Register: specifies whether to swap the first and last 8 bits of the 16-bit data in the register. Valid values:
          • true: swap
          • false: do not swap
        • Switch Register Bits Sequence: specifies whether to swap the first and last 16 bits of the original 32-bit data. Valid values:
          • true: swap
          • false: do not swap
        • Zoom Factor: The value of this parameter can be set to a negative number and cannot be set to 0. Default value: 1.
        • Data Report: You can select At Specific Time or Report Changes.
    • Add a service: In the Add Self-defined Feature dialog box, select Services in the Feature Type field. Set the required parameters and click OK.
      Note If the gateway connection protocol is Modbus, you cannot add services.
      Services

      The following table describes the parameters.

      Parameter Description
      Feature Name

      The service name.

      The feature name must be 1 to 30 characters in length, and can contain letters, digits, hyphens (-), and underscores (_). The feature name must start with a letter or digit.

      Identifier The ID of the service. Each service ID that you specify for a product must be unique. The ID is indicated by the value of the identifier parameter that is specified for the service in the Alink JSON format. The ID must be 1 to 30 characters in length, and can contain letters, digits, and underscores (_).
      Note You cannot set this parameter to one of the following reserved words: set, get, post, time, and value.
      Invoke Method
      • Asynchronous: For an asynchronous call, IoT Platform returns the result after the call is executed. IoT Platform does not wait for a response from the device.
      • Synchronous: For a synchronous call, IoT Platform waits for a response from the device. If no response is generated, the call times out.
      Input Parameters Optional. The input parameters of the service.

      Click +Add Parameter, and add an input parameter in the dialog box that appears.

      If the gateway connection protocol is OPC UA, you must set a parameter index to specify the order of the parameters.

      Note
      • You cannot set this parameter to one of the following reserved words: set, get, post, time, and value.
      • You can use a property as an input parameter or customize an input parameter. For example, when you specify the Automatic Sprinkling service, you can use the Sprinkling Interval and Sprinkling Amount properties as the input parameters. When the Automatic Sprinkling service is called, the sprinkler automatically starts sprinkling based on the specified sprinkling interval and amount.
      • You can add a maximum of 20 input parameters to a service.
      Output Parameters Optional. The output parameters of the service.

      Click Add Parameter, and add an output parameter in the dialog box that appears.

      If the gateway connection protocol is OPC UA, you must set a parameter index to specify the order of the parameters.

      Note
      • You cannot set this parameter to one of the following reserved words: set, get, post, time, and value.
      • You can use a property as an output parameter or customize an output parameter. For example, when you specify the Automatic Sprinkling service, you can use the Soil Humidity property as an output parameter. When IoT Platform calls the Automatic Sprinkling service, the data about soil humidity is returned.
      • A service supports a maximum of 20 output parameters.
      Extended Information

      The mapping between the device connection protocol and the standard TSL. The extended information is included in the TSL extension configuration of the TSL model.

      If the gateway connection protocol is Custom, OPC UA, or Modbus, you must enter extended information.

      If the gateway connection protocol is Custom, enter a JSON-formatted description of custom configurations. The description must be 1 to 1,024 characters in length.

      If the gateway connection protocol is OPC UA, enter a node name. Each node name that you specify for a service must be unique.

      Description The description of the feature. The description must be 1 to 100 characters in length.
    • Add an event: In the Add Self-defined Feature dialog box, select Events in the Feature Type field. Set the required parameters and click OK.
      Note If the gateway connection protocol is Modbus, you cannot define events.
      Events

      The following table describes the parameters.

      Parameter Description
      Feature Name

      The name of the event.

      The feature name must be 1 to 30 characters in length, and can contain letters, digits, hyphens (-), and underscores (_). The feature name must start with a letter or digit.

      Identifier The ID of the event. Each ID must be unique for a product. The ID is indicated by the value of the identifier parameter in the Alink JSON format. A device uses the ID as the key to submit property data, for example, ErrorCode.
      Note You cannot set this parameter to one of the following reserved words: set, get, post, time, and value.
      Event Type You can perform logic processing or analytics for events of different types.
      • Info: Devices submit common notifications, such as the completion of a specific task.
      • Alert: Devices submit emergencies or exceptions that occur during running. Events of this type have a high priority.
      • Error: Devices submit emergencies or exceptions that occur during running. Events of this type have a high priority.
      Output parameters The output parameters of an event. Click +Add Parameter. In the dialog box that appears, set the required parameters. You can use a property as an output parameter or customize an output parameter. For example, you can use the Voltage property as an output parameter. When a device reports an error, the current voltage value is also reported for troubleshooting.

      If the gateway connection protocol is OPC UA, you must set a parameter index to specify the order in which the parameters are set.

      Note
      • You cannot set this parameter to one of the following reserved words: set, get, post, time, and value.
      • An event supports a maximum of 50 output parameters.
      Extended Information

      The mapping between the device connection protocol and the standard TSL. The extended information is included in the TSL extension configuration of the TSL model.

      If the gateway connection protocol is Custom or OPC UA, you must enter the extended information

      If the gateway connection protocol is Custom, enter a JSON-formatted description of custom configurations. The description must be 1 to 1,024 characters in length.

      If the gateway connection protocol is OPC UA, enter a node name. Each node name that you specify for an event must be unique.

      Description The description of the feature. The description must be 1 to 100 characters in length.
  7. Publish the TSL model.
    1. On the Edit Draft page, click Release Online. The Publish TSL Model Online dialog box appears.
    2. Optional. In the Publish TSL Model Online dialog box, click Add Description, and enter a version number and description.
      Parameter Description
      Version Number The version of the TSL model. You can manage the TSL model based on version numbers.

      The version number must be 1 to 16 characters in length, and can contain letters, digits, and periods (.).

      Version Description The description of the TSL model. The description can contain letters, digits, and special characters. The description must be 1 to 100 characters in length.

    3. Click OK to publish the TSL model.
      Note
      • The TSL model is applied only after it is published.
      • A TSL model can have a maximum of 10 versions that are recently created. Extra historical versions are overwritten.

Result

After you edit a TSL model, you must publish the TSL model to apply the update. On the Define Feature tab of the Product Details page, you can perform the following operations:
  • Click TSL Model to view the TSL model in the JSON format.