A Thing Specification Language (TSL) model is a data model that is defined for a product in IoT Platform. A TSL model is used to describe the features of a product. This topic describes the concepts and limits of a TSL model.

Features

A TSL model digitizes a physical entity in the cloud, such as a sensor, vehicle-mounted device, building, or factory. A TSL model includes the properties, services, and events of an entity. A TSL model describes what the entity is, what the entity can do, and what information the entity can provide. You can define the TSL features of a product from the dimensions of properties, services, and events.

Feature type Description
Property A property is a TSL feature that describes the status or information of a running device.

For example, a property can be the temperature information that is collected by an environmental monitoring device, the on or off state of a smart lamp, or the wind speed of an electric fan.

Properties are classified into read/write properties and read-only properties. You can specify values for read/write properties and read the values. You can only read the values of read-only properties.

Service A service is a command or method that is provided by a device for external invocation. You can configure input and output parameters for a service that you want to invoke. A service reads the values of the input parameters and returns the results in the output parameters.

Compared with properties, services can be invoked by using a command to implement complex business logic. For example, you can invoke a service to perform a specific task.

You can invoke a service in a synchronous or asynchronous manner.

Event An event contains the information that a device reports to IoT Platform for notification and processing when the device runs, including alerts and failures. An event can contain multiple output parameters.

For example, an event can be a notification when a task is completed, the temperature and failure time of a device when a failure occurs on the device, and the status of a device when an alert is triggered for the device.

You can subscribe to or deliver events.

IoT Platform allows you to define multiple sets of features for a product, including properties, services, and events. A TSL module indicates a set of features. Different TSL modules do not affect each other.

TSL modules allow you to resolve complex device modeling issues in industrial scenarios. You can develop devices of different features by using the same product.

For example, the properties of the electric fan heater product include Power Switch, Gear (high, medium, and low), and Indoor Temperature. You can add the first two properties in one module and all three properties in another module. Then, you can develop devices based on TSL modules. This way, different devices in the same product have different features.

IoT Platform provides the default module. You can add custom modules based on your business requirements. The total number of modules cannot exceed 20.

Important The features that were defined before January 1, 2021 are categorized into the default module.

Description

IoT Platform provides TSL to describe modules and product features.

You can define properties, services, or events in a TSL module based on your business scenario.

Each TSL file is in the JSON format. To view or export a JSON-formatted TSL model in the IoT Platform console, perform the following steps: On the Product Details page, click Define Feature. On the Define Feature tab, click TSL Model. For more information about TSL fields, see TSL parameters.

You can add one or more TSL models in IoT Platform. When you import multiple TSL models at the same time, you can create custom TSL files. For more information, see Limits.

Limits

For information about the limits of TSL features, see Limits. The following table describes the limits that apply when you import TSL files.

Operation Limit
Import a single TSL file The file suffix is .json. The file must be in the JSON format. The file size cannot exceed 512 KB. The size of the valid characters in the file cannot exceed 256 KB (256 × 1024 characters).

Valid characters do not include line feeds and alignment characters.

Import multiple TSL files
  • Multiple TSL files must be compressed into a .zip file. The size of the ZIP file cannot exceed 2.5 MB. The ZIP file can be decompressed. After a ZIP file that includes one or more TSL files is decompressed, each TSL file must follow the require data format.
  • The ZIP file must contain at least one valid TSL file. The ZIP file can contain a maximum of one default module file, and nine custom module files.
    Important The values of the functionBlockName and functionBlockId parameters in a custom module must be different from the values of the parameters in another custom module.

References