You can add a Thing Specification Language (TSL) feature for a product. Features include properties, events, and services. This topic describes how to add a TSL feature in the IoT Platform console.

Prerequisites

A product is created. For more information, see Create a product.

Background information

  • You must configure TSL features in modules. The total number of default modules and custom modules in each product cannot exceed 10.
  • 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 a historical version of a TSL model to generate a new version.
  • IoT Platform can save the 10 most recent versions of a TSL model. Earlier versions are overwritten.
  • After you edit a TSL model, you must release the TSL model for the update to take effect.

For more information, see Limits.

Procedure

  1. Log on to the IoT Platform console.
  2. On the Overview page, find the instance that you want to manage and click the instance name to go to the Instance Details page.
    Important Enterprise Edition instances are available in the China (Shanghai) and Japan (Tokyo) regions. If the Enterprise Edition instances are unavailable in the region that you select, skip this step.
    Overview
  3. In the left-side navigation pane, choose Devices > Products. In the product list, find the product that you want to manage and click View in the Actions column.
  4. On the Product Details page, click the Define Feature tab, click Edit Draft, and then click Default Module or Add Module.
  5. Optional: If you want to add a module, set the required parameters, and click OK. Then, click the name of the added module. The following table describes the parameters.
    Parameter Description
    Module Name The name must be 4 to 30 characters in length, and can contain letters, digits, and underscores (_).
    Module Identifier The ID of the module. The ID must be unique in the product. The ID must be 1 to 30 characters in length and can contain letters, digits, and underscores (_).
    Module Description The description of the module. The description cannot exceed 100 characters in length.
  6. Optional: Select a version from the Version History drop-down list, and click Roll Back. Then, you can edit the TSL model based on the historical version.
  7. Add a custom feature.

    Click Add Self-defined Feature. Then, 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. Configure the parameters and click OK.

      The following table describes the parameters.

      Parameter Description
      Feature Name

      The name of the property. Example: power consumption. The name must be unique for a product.

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

      Identifier The ID of the property. The 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 a key to report property data. IoT Platform checks 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, you can set the ID to PowerConsumption.
      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 0 and 1 to define Boolean values. Examples: 0-off and 1-on.
      • text: string. You must specify the length of the string. The string must be 1 to 10,240 bytes in length.
      • date: timestamp. A UTC timestamp in the string format. Unit: milliseconds.
      • struct: JSON object. You must define a JSON struct and add JSON parameters to the struct. For example, you can define the color of a lamp as a struct that consists of the following parameters: Red, Green, and Blue. Nested structs are not supported.
      • array: array. You must specify the data type and number of elements in an array. Valid values of the element type: int32, float, double, text, and struct. The elements in an array must be of the same type. Valid values of the number of elements: 1 to 512.
      Note This parameter is not required if the Gateway Connection Protocol parameter of a product is set to Modbus.
      Value Range If the Data Type parameter is set to int32, float, or double, specify a value range for the property.
      Step The minimum step size by which property values can be changed. 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, you want to add the temperature property to a thermometer product. You can 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°C, the device of the thermometer product reports a temperature value, such as 0°C, 2°C, 4°C, 6°C, or 8°C.

      Unit You can select None or other values based on the actual conditions in your business scenario.
      Read/Write Type
      • Read/Write: GET requests and SET requests are supported.
      • Read-only: Only GET requests are supported.
      Note This parameter is not required if the Gateway Connection Protocol parameter of a product is set to Modbus.
      Description The description of the feature. The description cannot exceed 100 characters in length.
      Extended Information

      The extended information specifies the mapping between the connection protocol and the standard TSL model of the device. After you configure the extended settings in a TSL model, you can view the settings on the TSL Extension Information tab of the TSL model in the IoT Platform console.

      If the Gateway Connection Protocol parameter of a gateway sub-device is set to Custom, OPC UA, or Modbus, you must specify extended information.

      • If the Gateway Connection Protocol parameter is set to Custom, specify a description in JSON format for custom configurations. The description must be 1 to 1,024 characters in length.
      • If the Gateway Connection Protocol parameter is set to OPC UA, enter a node name. Each node name that you specify for a property must be unique.
      • If the Gateway Connection Protocol parameter is set to Modbus, configure the following parameters:
        • Operation Type: You can set this parameter to one of the following values.
          • Discrete Input (read-only, 0x02)
          • Coil Status (read-only, 0x01)
          • Coil Status (read and write, 0x01-read, 0x05-write)
          • Coil Status (read and write, 0x01-read, 0x0F-write)
          • Coil Status (write-only, 0x05)
          • Coil Status (write-only, 0x0F)
          • Holding Registers (read-only, 0x03)
          • Holding Registers (read and write, 0x03-read, 0x06-write)
          • Holding Registers (read and write, 0x03-read, 0x10-write)
          • Holding Registers (write only, 0x06)
          • Holding Registers (read-only, 0x10)
          • 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. Valid values: int16, uint16, int32, uint32, int64, uint64, float, double, string, bool, and bits.
        • Bit Position: You must specify this parameter if the Original Data Type parameter is set to bits. Select the bit position where the data is stored.
        • Value Range: The value range is obtained after the original data is processed by using a specified scale factor. Data that exceeds the value range is discarded. IoT Platform defines the default value ranges for the following types of operations:
          • 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 exchange the first 8 bits and last 8 bits of the 16-bit integer in the register. Valid values:
          • true: The system exchanges the first 8 bits and last 8 bits.
          • false: The system does not exchange the first 8 bits and last 8 bits.
        • Switch Register Bits Sequence: specifies whether to exchange the first 16 bits and last 16 bits of the original 32-bit integer. Valid values:
          • true: The system exchanges the first 16 bits and last 16 bits.
          • false: The system does not exchange the first 16 bits and last 16 bits.
        • Scale Factor: specifies an integer or floating-point number. Default value: 1. The value cannot be 0 or negative.
        • 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. Configure the parameters and click OK.
      Note If the Gateway Connection Protocol parameter is set to Modbus, you cannot add services.

      The following table describes the parameters.

      Parameter Description
      Feature Name

      The name of the service. The name must be 1 to 30 characters in length, and can contain letters, digits, hyphens (-), underscores (_), forward slashes (/), and periods (.). It must start with a letter or a digit.

      Identifier The ID of the service. The ID must be unique for a product. 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 50 characters in length, and can contain letters, digits, and underscores (_).
      Note You cannot set this parameter to the following reserved words: set, get, post, time, and value.
      Invoke Method
      • Asynchronous: IoT Platform returns the result after the service is invoked. IoT Platform does not wait for a response from the device.
      • Synchronous: IoT Platform waits for a response from the device. If no response is returned, the service invocation 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 parameter is set to OPC UA, you must set a parameter index to specify the order of the parameters.

      Note
      • You cannot set this parameter to the following reserved words: set, get, post, time, and value.
      • You can use a property as an input parameter or configure a custom input parameter. For example, when you define the Automatic Sprinkling service, you can use the predefined Sprinkling Interval property and Sprinkling Amount property as the input parameters. When IoT Platform invokes the Automatic Sprinkling service, the sprinkler device starts sprinkling based on the specified sprinkling interval and specified amount.
      • You can add up to 20 input parameters for each 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 parameter is set to OPC UA, you must set a parameter index to specify the order of the parameters.

      Note
      • You cannot set this parameter to the following reserved words: set, get, post, time, and value.
      • You can use a property as an output parameter or configure a custom output parameter. For example, when you define the Automatic Sprinkling service, you can use the predefined Soil Humidity property as an output parameter. When IoT Platform invokes the Automatic Sprinkling service, the data related to soil humidity is returned.
      • You can add up to 20 output parameters for each service.
      Extended Information

      The extended information specifies the mapping between the connection protocol and the standard TSL model of the device. After you configure the extended settings in a TSL model, you can view these settings on the TSL Extension Information tab of the TSL model in the IoT Platform console.

      If the Gateway Connection Protocol parameter of a gateway sub-device is set to Custom or OPC UA, you must specify the extended information.

      • If the Gateway Connection Protocol parameter is set to Custom, specify a description in JSON format for custom configurations. The description must be 1 to 1,024 characters in length.
      • If the Gateway Connection Protocol parameter is set to OPC UA, enter a node name. Each node name that you specify for a service must be unique.
      Description The description of the service. The description cannot exceed 100 characters in length.
    • Add an event: In the Add Self-defined Feature dialog box, select Events in the Feature Type field. Configure the parameters and click OK.
      Note If the Gateway Connection Protocol parameter is set to Modbus, you cannot add events.

      The following table describes the parameters.

      Parameter Description
      Feature Name

      The name of the event. The name must be 1 to 30 characters in length, and can contain letters, digits, hyphens (-), underscores (_), forward slashes (/), and periods (.). It must start with a letter or a digit.

      Identifier The ID of the event. The 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 a key to report event data. Example: ErrorCode. The ID must be 1 to 50 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.
      Event Type You can perform logic processing or analysis for events of different types.
      • Info: Devices report common notifications, such as the task completion notification.
      • Alert: Devices report emergencies or exceptions that occur when a device is running. Events of this type are assigned a high priority.
      • Error: Devices report emergencies or exceptions that occur when a device is running. Events of this type are assigned a high priority.
      Output Parameters The output parameters of an event. Click + Add Parameter, and add an output parameter in the dialog box that appears. You can use a property as an output parameter or configure a custom output parameter. For example, you can use the predefined Voltage property as an output parameter. If a device reports a voltage-related error, the voltage of the device is also reported for troubleshooting.

      If the Gateway Connection Protocol parameter is set to 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 define a maximum of 50 output parameters for an event.
      Extended Information

      The extended information specifies the mapping between the connection protocol and the standard TSL model of the device. After you configure the extended settings in a TSL model, you can view the settings on the TSL Extension Information tab of the TSL model in the IoT Platform console.

      If the Gateway Connection Protocol parameter of a gateway sub-device is set to Custom or OPC UA, you must specify the extended information.

      • If the Gateway Connection Protocol parameter is set to Custom, specify a description in JSON format for custom configurations. The description must be 1 to 1,024 characters in length.
      • If the Gateway Connection Protocol parameter is set to OPC UA, enter a node name. Each node name that you specify for an event must be unique.
      Description The description of the event. The description cannot exceed 100 characters in length.

Publish a TSL model

Important A TSL model cannot take effect until the TSL model is published.
  1. Choose Define Feature > Edit Draft. In the lower left corner of the page that appears, click Release online. The Release model online? dialog box appears.
  2. Optional:Click +Add post notes, and configure the Version Number and note parameters. The following table describes the parameters.
    Parameter Description
    Version Number The version number of the TSL model. You can manage the TSL model based on the version number.

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

    note The description of the TSL model. The description can contain letters, digits, and special characters. The description cannot exceed 100 characters in length. A Chinese character or an English letter is considered one character.
  3. If an online version is available, you must check the differences between the version that you want to release and the online version.
    Click View Differences. In the View Differences panel, you can view the differences between versions. After you confirm your settings, click Confirm. In the Release model online? dialog box, the checkbox is automatically selected.

    If you do not want to view the version differences, you can select "Make sure that you have verified the differences between the current version and the online version."

  4. Click OK to publish the TSL model.

Verify the result

After you publish a TSL model, you can view the published model in the IoT Platform console. You can perform the following operations on the Define Feature tab of the Product Details page:

  • Click TSL Model to view the TSL model in the JSON format.

Related operations

API Description
CreateThingModel Adds features or extended information to the TSL model of a product.
QueryThingModel Queries the details of a TSL model of a product.
CopyThingModel Copies the TSL model of a product to another product.
PublishThingModel Publishes the TSL model of a product.
ListThingTemplates Queries all product categories that are predefined in IoT Platform.
GetThingTemplate Queries the standard TSL model information about a specified category.
ListThingModelVersion Queries the TSL model versions of a specified product.
GetThingModelTsl Queries the TSL model of a specified product.
ImportThingModelTsl Imports a TSL model to a specified product. Extended information cannot be imported.
QueryThingModelPublished Queries the details of a published TSL model of a specified product.
GetThingModelTslPublished Queries the basic information about a published TSL model of a specified product.
QueryThingModelExtendConfig Queries the extended information about the TSL model of a specified product.
QueryThingModelExtendConfigPublished Queries the extended information about a published TSL model.