IoT Platform:Add a TSL feature

Usage notes

• You must configure TSL features in modules. The sum of the number of default modules and the number of custom modules in each product cannot exceed 20.

• If a product is published, you cannot modify the TSL model of the product. To modify a TSL model, you must unpublish the product for which the TSL model is defined.

• You can modify 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 modify 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. In the upper-left corner of the IoT Platform console, select the region where IoT Platform is activated.

3. On the All environment tab of the Overview page, find the instance that you want to manage and click the instance ID or instance name.

4. 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.

5. On the product details page, click the Define Feature tab, click Edit Draft, and then click Default Module or Add Module.

6. Optional. If you want to add a module, configure 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 a 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 must be 1 to 4096 characters in length.

7. Optional. Select a version from the Version History drop-down list, and click Roll Back. Then, you can modify the TSL model based on the historical version.

8. 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 in 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 in 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 (_). Example: PowerConsumption. Note You cannot set this parameter to one of the following reserved words: set, get, post, property, event, 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 or 1 to define a Boolean value. Examples: 0 indicates off and 1 indicates 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 can 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.
     The unit of the instance price.	You can select None or other values based on 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 the 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 configure 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 swap the first 8 bits and last 8 bits of the 16-bit integer in the register. Valid values: true: The system swaps the first 8 bits and last 8 bits. false: The system does not swap the first 8 bits and last 8 bits. Switch Register Bits Sequence: specifies whether to swap the first 16 bits and last 16 bits of the original 32-bit integer. Valid values: true: The system swaps the first 16 bits and last 16 bits. false: The system does not swap 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 service name. 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 in 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 one of the following reserved words: set, get, post, property, event, time, and value.
     Invocation 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. In the dialog box that appears, click + Add Parameter to add an input parameter. If the Gateway Connection Protocol parameter is set to OPC UA, you must configure 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, property, event, 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 and Sprinkling Amount properties as the input parameters. When IoT Platform invokes the Automatic Sprinkling service, the sprinkler device starts sprinkling based on the specified sprinkling interval and amount. You can add up to 20 input parameters for each service.
     Output Parameters	Optional. The output parameters of the service. In the dialog box that appears, click + Add Parameter to add an output parameter. If the Gateway Connection Protocol parameter is set to OPC UA, you must configure 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, property, event, 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, data that is 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 extended information. If the Gateway Connection Protocol parameter is set to Custom, specify a description in the 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 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. 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 in 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, property, event, time, and value.
     The type of the event.	You can perform logic processing or analysis for events of different types. Info: Devices report common notifications, such as a 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. In the dialog box that appears, click + Add Parameter to add an output parameter. 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 configure 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, property, event, time, and value. You can define up to 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 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 extended information. If the Gateway Connection Protocol parameter is set to Custom, specify a description in the 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 must be 1 to 100 characters in length.

Publish a TSL model

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 enter a version number and note.

   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 must be 1 to 100 characters in length.

3. If an online version is available, you must check the differences between the current version that you want to release and the online version.

   Click View Differences. In the View Differences panel, you can view the differences between the versions. After you confirm the settings, click Confirm. In the Release model online? dialog box, the checkbox is automatically selected.

   If you do not want to view the differences between the versions, 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.

Execution 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 API operations

What to do next

By default, TSL data that is submitted by the devices of a product is automatically written to a hot data storage space. You can stop the hot data storage service for some or all TSL models based on your business requirements.