Add a TSL model manually

Limits

• TSL model features are not supported for MQTT-based instances. Therefore, you cannot add TSL models to these instances.

• TSL models must be configured in modules. The total number of default and custom modules per product cannot exceed 200.

• If a product is published, you cannot edit its TSL model. To edit the TSL model, you must first revoke the product.

• You can edit a historical version of a TSL model to create a new version.

• A maximum of 10 historical versions can be saved for a TSL model. Older versions are automatically overwritten.

• After you edit a TSL model, you must publish it for the changes to take effect.

For more information about the limits on defining TSL models, see Limits.

Add custom modules

You can add custom modules to manage TSL model features for different business scenarios.

1. Log on to the IoT Platform console.

2. In the upper-left corner of the console, select the region where your instance is located.

3. On the Instance Overview tab, under All Environments, find your instance and click the instance card.

4. In the navigation pane on the left, choose Device Management > Products. In the product list, find the desired product and click View in the Actions column.

5. On the product details page, click the Feature Definition tab, and then click Edit Draft.

6. Click the Add icon, configure the parameters, and then click Confirm.

   Parameter	Description
   Module Name	Supports Chinese characters, letters, Japanese characters, digits, and underscores (_). The name must be 4 to 30 characters in length. A Chinese or Japanese character is counted as one character.
   Module Identifier	The unique identifier of the module, also known as the module ID. It must be unique within the product. Supports uppercase and lowercase letters, digits, and underscores (_). The identifier must be up to 30 characters in length.
   Module Description	Enter a description or note for the module. The description can be up to 4,096 characters in length.

   After you add a custom module, it does not appear in the module list on the Feature Definition tab until you add features to it and publish the TSL model.

Add TSL model features

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

2. Optional: From the Historical Versions drop-down list, select a historical version. Click Restore This Version to use the selected version as the draft for editing.

3. Add standard features. If you selected a Standard Category when you created the product, IoT Platform provides predefined standard features for that category.

   The Standard function plan includes mandatory and optional functions. The usage is as follows:

   • Required features: These features are automatically added to the default module of the TSL model and cannot be deleted.

   • Optional features: Click Add Standard Feature. In the dual list box that appears, select the standard features for your product from the left-side list.

     You can click Add All or Delete All.

   • General operations: You can click Edit in the Actions column for a feature to modify its definition.

     Important

     You cannot modify the Feature Type, Identifier, or Data Type of a standard feature.

4. Add custom features.

   Click Add Custom Feature. You can define custom properties, services, and events for the product.

   • Custom properties: In the Add Custom Feature dialog box, select Property as the feature type. After you set the parameters, click Confirm.

     The following table describes the property parameters.

     Parameter	Description
     Feature Name	The name of the property, such as electricity consumption. The feature name must be unique within a product. Supports Chinese characters, letters, Japanese characters, digits, hyphens (-), underscores (_), forward slashes (/), and periods (.). The name must start with a Chinese character, letter, Japanese character, or digit, and be up to 30 characters in length. When you enter a feature name, matching standard features from the standard feature library are filtered for your selection. You can refer to the standard features for configuration. Note When the gateway protocol is Modbus, standard properties are not supported. Only custom properties are supported.
     Identifier	The unique identifier of the property. It must be unique within the product. This is the value of the identifier parameter in the Alink JSON format. It serves as the key for the property data reported by the device. The cloud uses this identifier to validate and accept the data. Supports letters, digits, and underscores (_). The identifier can be up to 50 characters in length, such as PowerConsumption. Note The following system-reserved parameters cannot be used as an identifier: set, get, post, property, event, time, and value.
     Data Type	int32: A 32-bit integer. You must define a value range, step size, and unit symbol. float: A single-precision floating-point number. You must define a value range, step size, and unit symbol. double: A double-precision floating-point number. You must define a value range, step size, and unit symbol. enum: An enumeration. Define the parameter value and description for each enum value, such as 1 for heating mode and 2 for refrigeration mode. bool: A Boolean value. Use 0 or 1 to define the Boolean value, such as 0 for off and 1 for on. text: A string. You must define the data length of the string. The maximum length is 10,240 bytes. date: A timestamp. The format is a String type UTC timestamp in milliseconds. struct: A JSON object. Define a JSON struct and add JSON parameter items. For example, define the color of a light as a struct composed of Red, Green, and Blue parameters. Nested structs are not supported. array: An array. You must declare the element type and the number of elements in the array. The element type can be int32, float, double, text, or struct. Ensure that all elements in an array are of the same type. The number of elements is limited to 1 to 512. Note When the device protocol is Modbus, you do not need to set this parameter.
     Value Range	If the data type is int32, float, or double, you can set the value range for the property.
     Step Size	The minimum granularity of change for the property value. If the data type is int32, float, or double, you can set the step size as needed. For example, when defining a temperature property for a thermometer product, set the data type to int32, the step size to 2, the unit to °C, and the value range to 0-100. This means the device reports the temperature value every time it changes by two degrees, such as 0°C, 2°C, 4°C, 6°C, 8°C, and so on.
     Unit	You can select None for the unit or choose a unit based on your requirements.
     Read/Write Type	Read and Write: The supported request methods are GET (retrieve) and SET (configure). Read-only: The only supported request method is GET (retrieve). Note When the gateway protocol is Modbus, you do not need to set this parameter.
     Description	Enter a description or note for this feature. The description can be up to 100 characters in length.
     Extended Description	The extended description defines the mapping from the device communication protocol to the standard TSL model. It corresponds to the extended configuration in the TSL model. This parameter is displayed and required only when you add a property to a TSL model for a product where Node Type is Gateway Sub-device and Gateway Protocol is Custom, OPC UA, or Modbus. If Gateway Protocol is Custom, enter the custom configuration information in JSON format. The length is limited to 1,024 characters. If Gateway Protocol is OPC UA, set the node name. The node name must be unique within the property dimension. If Gateway Protocol is Modbus, set the following parameters: Operation Type: Discrete Input (read-only, 0x02) Coil (read-only, 0x01) Coil (read/write, read uses 0x01, write uses 0x05) Coil (read/write, read uses 0x01, write uses 0x0F) Coil (write-only, 0x05) Coil (write-only, 0x0F) Holding Register (read-only, 0x03) Holding Register (read/write, read uses 0x03, write uses 0x06) Holding Register (read/write, read uses 0x03, write uses 0x10) Holding Register (write-only, 0x06) Holding Register (write-only, 0x10) Input Register (read-only, 0x04) Register Address: Hexadecimal format. Must start with 0x and be in the range of 0x0 to 0xFFFF, such as 0xFE. Raw Data Type: Supports int16, uint16, int32, uint32, int64, uint64, float, double, string, bool, and bits. Bit Position: This parameter is available when the raw data type is bits. Select the position of the data. Value Range: This is the value range of the raw data after it is processed by the scaling factor. Data outside this range is discarded. IoT Platform has set default value ranges for each operation type: Coil type: 0 to 1 Discrete Input type: 0 to 1 Holding Register type: -2147483648 to 2147483647 Input Register type: -2147483648 to 2147483647 Swap high and low bytes within a register: Specifies whether to swap the first 8 bits and the last 8 bits of the 16-bit data in the register (byte1byte2 -> byte2byte1). true: Swap. false: Do not swap. Swap register order: Specifies whether to swap the first 16 bits and the last 16 bits of the 32-bit raw data (byte1byte2byte3byte4 -> byte3byte4byte1byte2). true: Swap. false: Do not swap. Scaling Factor: An integer or a floating-point number. The default value is 1. It cannot be 0 or a negative number. Data Reporting Method: Options are Report on Schedule and Report on Change.

   • Custom services: In the Add Custom Feature dialog box, select Service as the feature type. After you set the parameters, click Confirm.

     Note

     If the gateway protocol is Modbus, you cannot define any services.

     The following table describes the service parameters.

     Parameter	Description
     Feature Name	The service name. Supports Chinese characters, letters, Japanese characters, digits, hyphens (-), underscores (_), forward slashes (/), and periods (.). The name must start with a Chinese character, letter, Japanese character, or digit, and be up to 30 characters in length. When you enter a feature name, matching standard features from the standard feature library are filtered for your selection. You can refer to the standard features for configuration.
     Identifier	The unique identifier of the service. It must be unique within the product. This is the value of the identifier parameter for the service in the Alink JSON format. Supports letters, digits, and underscores (_). The identifier can be up to 50 characters in length. Note The following system-reserved parameters cannot be used as an identifier: set, get, post, property, event, time, and value.
     Invocation Method	Asynchronous: For an asynchronous invocation, the cloud returns the result immediately after the call is executed, without waiting for a response message from the device. Synchronous: For a synchronous invocation, the cloud waits for a response from the device. If the device does not respond, the call times out.
     Input Parameters	Set the input parameters for the service. This is optional. Click Add Parameter to add input parameters for the service in the dialog box that appears. If the gateway protocol is OPC UA, you must set the parameter index to mark the order of the parameters. Note The following system-reserved parameters cannot be used as an identifier for an input parameter: set, get, post, property, event, time, and value. You can use a property as an input parameter or define a custom parameter. For example, when defining an automatic irrigation service, you can use the defined properties irrigation time and irrigation amount as input parameters. When this service is called, these parameters are passed, and the irrigation device performs precise irrigation according to the set time and amount. A service can have a maximum of 20 input parameters.
     Output Parameters	Set the output parameters for the service. This is optional. Click Add Parameter to add output parameters for the service in the dialog box that appears. If the gateway protocol is OPC UA, you must set the parameter index to mark the order of the parameters. Note The following system-reserved parameters cannot be used as an identifier for an output parameter: set, get, post, property, event, time, and value. You can use a property as an output parameter or define a custom parameter. For example, you can use the defined property soil humidity as an output parameter. When the cloud calls the automatic irrigation service, the current soil humidity data is returned. A service can have a maximum of 20 output parameters.
     Extended Description	The extended description defines the mapping from the device communication protocol to the standard TSL model. It corresponds to the extended configuration in the TSL model. This parameter is displayed and required only when you add a TSL model for a product where Node Type is Gateway Sub-device and Gateway Protocol is Custom or OPC UA. If Gateway Protocol is Custom, you must pass the custom configuration in JSON format. The length cannot exceed 1,024 characters. If Gateway Protocol is OPC UA, set the node name. The node name must be unique within the service dimension.
     Description	Enter a description or note for this service feature. The description can be up to 100 characters in length.

   • Custom events: In the Add Custom Feature dialog box, select Event as the feature type. After you set the parameters, click Confirm.

     Note

     If the gateway protocol is Modbus, you cannot define any events.

     The following describes the event parameters.

     Parameter	Description
     Feature Name	The name of the event. Supports Chinese characters, letters, Japanese characters, digits, hyphens (-), underscores (_), forward slashes (/), and periods (.). The name must start with a Chinese character, letter, Japanese character, or digit, and be up to 30 characters in length. When you enter a feature name, matching standard features from the standard feature library are filtered for your selection. You can refer to the standard features for configuration.
     Identifier	The unique identifier of the event. It must be unique within the product. This is the value of the identifier parameter for the event in the Alink JSON format. It serves as the key for the event data reported by the device, such as ErrorCode. Supports letters, digits, and underscores (_). The identifier can be up to 50 characters in length. Note The following system-reserved parameters cannot be used as an identifier: set, get, post, property, event, time, and value.
     Event Type	You can handle business logic and perform statistical analysis for different event types. Information: Refers to general notifications reported by the device, such as the completion of a task. Alert: Refers to sudden or abnormal situations reported by the device during operation. Alert information has a high priority. Fault: Refers to sudden or abnormal situations reported by the device during operation. Fault information has a high priority.
     Output Parameters	The output parameters for this event. Click Add Parameter to add an output parameter for the service in the dialog box that appears. You can use a property as an output parameter or define a custom parameter. For example, you can use the defined property voltage as an output parameter. When the device reports this fault event, it will carry the current voltage value of the device, which can be used to further determine the cause of the fault. If the gateway protocol is OPC UA, you must set the parameter index to mark the order of the parameters. Note The following system-reserved parameters cannot be used as an identifier for an output parameter: set, get, post, property, event, time, and value. An event can have a maximum of 50 output parameters.
     Extended Description	The extended description defines the mapping from the device communication protocol to the standard TSL model. It corresponds to the extended configuration in the TSL model. This parameter is displayed and required only when you add a TSL model for a product where Node Type is Gateway Sub-device and Gateway Protocol is Custom or OPC UA. If Gateway Protocol is Custom, you must pass the custom configuration in JSON format. The length cannot exceed 1,024 characters. If Gateway Protocol is OPC UA, set the node name. The node name must be unique within the event dimension.
     Description	Enter a description or note for this event feature. The description can be up to 100 characters in length.

Publish the TSL model

1. In the lower-left corner of the Edit Draft page for Feature Definition, click Publish. The Publish TSL Model? dialog box appears.

2. Optional: Click Add Publication Note, and enter a version number and description.

   Parameter	Description
   Version Number	Set the version number for the current TSL model. You can manage TSL models based on version numbers later. The version number supports letters, digits, and periods (.). It can be 1 to 16 characters in length.
   Version Description	Describe the current version of the TSL model. Supports Chinese characters, letters, Japanese characters, digits, and special symbols. The description can be up to 100 characters in length. A Chinese or Japanese character is counted as one character.

3. If an online version exists, compare it with the new version to confirm the changes.

   Click Comparison Result to view the changes in the Comparison Result dialog box. After you confirm the changes, click Confirm and View. You are returned to the Publish TSL Model dialog box, and the "I have reviewed the comparison between the current version and the online version" check box is automatically selected.

   If you do not need to compare the versions, you can manually select the I have reviewed the comparison between the current version and the online version check box.

4. Click OK to publish the TSL model.

   After the TSL model is published, you are redirected to the Feature Definition tab of the product details page. You can view the version number and publication time of the published TSL model.

Results

After the TSL model is published, IoT Platform generates a published version of the TSL model for the product. On the Feature Definition tab of the Product Details page, you can perform the following operations:

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

• Click Generate Device-side Code to download the device-side code that IoT Platform generates based on the features you defined. Use this code for device-side development.

Related API operations

What to do next

By default, TSL model data reported by devices is automatically stored in hot data storage. You can disable data storage for some or all TSL model data based on your requirements. For more information, see Disable or enable data storage for a TSL model.

References

• To modify or delete existing TSL model modules, properties, events, or services, see Modify and delete a TSL model.

• To import a TSL model from a file or copy a TSL model from another product, see Add TSL models in batches.

• To learn how to use TSL models for communication between devices and IoT Platform, see Device communication using a TSL model.