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 has been published, you cannot add or edit TSL features of the product. To add or edit TSL features, you must unpublish the product.
  • You can edit previous TSL versions to generate new versions.
  • A TSL can contain the last 10 versions. Other historical versions are overwritten.
  • After you edit TSL features, you must publish the TSL to validate the TSL features.

Procedure

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

    Select Add Self-defined Feature. You can define a property, service, and event for the product.

    • Define a property: In the Create Self-Defined Feature dialog box, select Properties for the Feature Type parameter. Configure the parameters and click OK.Properties

      The following table describes the parameters.

      Parameter Description
      Feature Name

      The name of the property. Example: power_usage. The feature names of a product must be unique.

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

      [DO NOT TRANSLATE]

      Note [DO NOT TRANSLATE]
      Identifier The unique identifier of the property. This parameter uniquely identifies a product feature. The identifier is indicated by the value of the identifier parameter in Alink JSON data. A device uses the identifier as the key to submit property data, and IoT Platform verifies the identifier to confirm whether to receive the data. The identifier must be 1 to 50 characters in length, and can contain letters, digits, and underscores (_). 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 can be up 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 into 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 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 array can contain 1 to 512 elements.
      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 smallest 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 business needs.

      For example, when you define the temperature property for 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~100. In this case, each time the temperature changes by 2 degrees, a device submits a temperature value, such as 0°c, 2°c, 4°c, 6°c, and 8°c.

      Unit You can select None or other values based on your needs.
      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 Enter a description of the feature. The description can be up to 100 characters in length.
      Extended Information

      The mapping between the device connection protocol and the standard TSL.

      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 can be up to 1,024 characters in length.
      • If the gateway connection protocol is OPC UA, enter a node name. Node names for different properties 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. Example: 0xFE.
        • Original Data Type: Multiple data types are supported, including int16, uint16, int32, uint32, int64, uint64, float, double, string, and bool. You can also customize a data type to use raw data.
        • Value Range: The value range is retrieved after the original data is processed by using the 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~1
          • Discrete Input: 0~1
          • Holding Registers: -2147483648~2147483647
          • Input Registers: -2147483648~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 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 for this parameter.
    • Define a service: In the Create Self-Defined Feature dialog box, select Services for the Feature Type parameter. Configure the parameters and click OK.
      Note If the gateway connection protocol is Modbus, you cannot define services.
      Services

      The following table describes the parameters.

      Parameter Description
      Feature Name

      The name of the service.

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

      [DO NOT TRANSLATE]

      Note If the gateway connection protocol is Modbus, you cannot define services.
      Identifier The unique identifier of the service. This parameter uniquely identifies a product service. The identifier is indicated by the value of the identifier parameter that is specified for the service in Alink JSON data. The identifier 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 instead of waiting 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 indicate 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.
      • A service supports a maximum of 20 input parameters.
      Output Parameters Optional. The output 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 indicate 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 input 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 If the gateway connection protocol is Custom or OPC UA, you must add extended information to indicate the mapping between the device connection protocol and the standard TSL.

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

      If the gateway connection protocol is OPC UA, enter a node name. Node names for different services must be unique.

      Description Enter a description of the feature. The description can be up to 100 characters in length.
    • Define an event: In the Create Self-Defined Feature dialog box, select Events for the Feature Type parameter. Configure the 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 Chinese characters, English letters, digits, hyphens (-), and underscores (_). It must start with a Chinese character, English letter, or digit.

      Note If the gateway connection protocol is Modbus, you cannot define events.
      Identifier The unique identifier of the event. This parameter uniquely identifies a product feature. The identifier is indicated by the value of the identifier parameter in Alink JSON data. A device uses the identifier, for example, ErrorCode, as the key to submit property data.
      Note You cannot set this parameter to one of the following reserved words: set, get, post, time, and value.
      Event Type
      • 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 high priorities. You can perform logic processing or analytics for events of different types.
      • Error: Devices submit emergencies or exceptions that occur during running. Events of this type have high priorities. You can perform logic processing or analytics for events of different types.
      Output Parameters The output parameters of an event. Click +Add Parameter, and add an input parameter in the dialog box that appears. You can use a property as an output parameter or customize an input parameter. For example, you can use the Voltage property as an output parameter. When a device submits an error, the current voltage value is also submitted for troubleshooting.

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

      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 If the gateway connection protocol is Custom or OPC UA, you must add extended information to indicate the mapping between the device connection protocol and the standard TSL.

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

      If the gateway connection protocol is OPC UA, enter a node name. Node names for different events must be unique.

      Description Enter a description of the feature. The description can be up to 100 characters in length.
  7. Publish the TSL.
    1. On the Edit Draft page, click Release Online in the lower-left corner.
    2. In the Release model online dialog box, enter a version number and description, and click OK.
      Parameter Description
      Version Number The version of the TSL. You can manage the TSL based on version numbers.

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

      note The description of the TSL. The description can contain Chinese characters, English letters, digits, and special characters. The description can be up to 100 characters in length.
      Note
      • The TSL takes effect only after you publish it.
      • A TSL can contain the last 10 versions. Other historical versions are overwritten.

Result

After the TSL is published, IoT Platform generates a formal version of TSL for the product. On the Product Details page, you can perform the following operations on the Define Feature tab:
  • Click TSL Model to view the TSL in the JSON format.