A Thing Specification Language (TSL) model digitalizes a physical entity and builds a data model for the entity in the cloud. In IoT Platform, a TSL model includes a set of features that are defined for a product. After you define features for a product, IoT Platform generates a TSL model for the product. A TSL model describes what a product is, what the product can do, and what services the product can provide.

A TSL model is a JSON-formatted file. A TSL model digitalizes a physical entity, such as a sensor, vehicle-mounted device, building, and factory. A TSL model also describes what the entity is, what the entity can do, and what information the entity can provide based on the properties, services, and events. After properties, services, and events are defined for a product, the feature definition of the product is complete.

Product features are classified into the following types: property, service, and event.

Feature type Description
Property Defines a type of data that devices can collect, for example, the temperature data that is collected by an environmental sensor. Properties support the GET and SET request methods. Application systems can make requests to obtain and set properties.
Service Defines a device capability or method that can be invoked by the required applications. You can set input and output parameters. Compared with properties, services can be invoked by using a command to implement complex business logic, such as performing a specific task.
Event Defines a device runtime event. Events contain notifications that require further actions or responses. You can set multiple output parameters. For example, an event may be a notification about the completion of a task, a system failure, or a temperature alert. You can subscribe to or publish events.

Format of a TSL model

On the Define Feature tab, you can click TSL Model to view a JSON-formatted TSL model.

Format:

{
    "schema": "The URL that you can visit to view the TSL model",
    "profile ":{
        productKey: "Specify the productKey",
    },
    "properties": [
        {
            "identifier": "The ID of each property. Each ID must be unique for a product",
            "name": "Property name",
            "accessMode": "The level of access to the property. Valid values: r: read-only and rw: read/write",
            "required": "Whether the service is required for a standard feature",
            "dataType": {
                "type": "The data type of the event. Valid values: int32, float, double, text, date (UNIX timestamps in the STRING format. Unit: milliseconds.), bool (0 or 1), enum (integers), struct (a struct that can include int, float, double, text, date, bool, and enum values), and array (an array that supports int, double, float, text, and struct data types).",
                "specs": {
                    "min": "The minimum value. This parameter is available only for properties of the int, float, and double types.",
                    "max": "The maximum value. This parameter is available only for properties of the int, float, and double types.",
                    "unit": "The unit of the property.",
                    "unitName": "The name of the unit.",
                    "size":"The array size. By fault, the maximum size is 128. This parameter is available only for arrays.",
                    "step": "The step size. The value is a string.",
                    "item": {
                        "type":"The data type of an array element. "
                    }
                }
            }
        }
    ],
    "events": [
        {
            "identifier": "The ID of each event. Each ID must be unique for a product. The post event is pre-defined and used to report properties.",
            "name": "The event name.",
            "desc": "The event description.",
            "type": "The event type. Valid values: info, alert, and error.",
            "required": "Whether the event is required for a standard feature.",
            "outputData": [
                {
                    "identifier": "The ID of each output parameter. Each ID must be unique.",
                    "name": "The name of the output parameter.",
                    "dataType": {
                        "type": "The data type of the parameter. Valid values: int32, float, double, text, date (UNIX timestamps in the STRING format. Unit: milliseconds.), bool (0 or 1), enum (integers), struct (a struct that can include int, float, double, text, date, bool, and enum values), and array (an array that can include int, double, float, text, and struct values).",
                        "specs": {
                            "min": "The minimum value. This parameter is available only for output parameters of the int, float, and double types.",
                            "max": "The maximum value. This parameter is available only for output parameters of the int, float, and double types.",
                            "unit": "The unit of the output parameter.",
                            "unitName": "The unit name.",
                            "size":"The array size. The maximum size is 128. This parameter is available only for arrays.",
                            "step": "The step size. The value is a string.",
                            "item": {
                                "type":"The data type of an array element. "
                            }
                        }
                    }
                }
            ],
            "method": "The name of a method that can access the event. The name is generated based on the value of the identifier parameter."
        }
    ],
    "services": [
        {
            "identifier": "The ID of each service. Each ID must be unique for a product. The set and get services are pre-defined. The value of the accessMode parameter for a property specifies whether these services can access the property.",
            "name": "The service name.",
            "desc": "The service description.",
            "required": "Whether the service is required for a standard feature.",
            "callType": "The call type. Valid values: async: asynchronous call, and sync: synchronous call",
            "inputData": [
                {
                    "identifier": "The ID of each input parameter. Each ID must be unique.",
                    "name": "The name of the input parameter.",
                    "dataType": {
                        "type": "The data type of the parameter. Valid values: int32, float, double, text, date (UNIX timestamps in the STRING format. Unit: milliseconds.), bool (0 or 1), enum (integers), struct (a struct that can include int, float, double, text, date, bool, and enum values), and array (an array that can include int, double, float, text, and struct values).",
                        "specs": {
                            "min": "The minimum value. This parameter is available only for input parameters of the int, float, double types.",
                            "max": "The maximum value. This parameter is available only for input parameters of the int, float, double types.",
                            "unit": "The unit of the input parameter.",
                            "unitName": "The name of the unit.",
                            "size":"The array size. The maximum size is 128. This parameter is available only for arrays.",
                            "step": "The step size. The value is a string.",
                            "item": {
                                "type":"The type of an array element."
                            }
                        }
                    }
                }
            ],
            "outputData": [
                {
                    "identifier": "The ID of each output parameter.",
                    "name": "The name of the output parameter.",
                    "dataType": {
                        "type": "The data type of the parameter. Valid values: int32, float, double, text, date (UNIX timestamps in the STRING format. Unit: milliseconds.), bool (0 or 1), enum (integers), struct (a struct that can include int, float, double, text, date, bool, and enum values), and array (an array that can include int, double, float, text, and struct values).",
                        "specs": {
                            "min": "The minimum value. This parameter is available only for output parameters of the int, float, and double types.",
                            "max": "The maximum value. This parameter is available only for output parameters of the int, float, and double types.",
                            "unit": "The unit of parameter.",
                            "unitName": "The name of the unit.",
                            "size":"The array size. By default, the maximum size is 128. This parameter is available only for arrays.",
                            "step": "The step size. The value is a string.",
                            "item": {
                                "type":"The data type of an array element."
                            }
                        }
                    }
                }
            ],
            "method": "The name of a method that can access the service. The name is generated based on the value of the identifier parameter."
        }
    ]
}

If the node type of a product is gateway sub-device and the networking and data format is Modbus, OPC UA, or custom, you can view the extended information of the TSL model.

Example of a Modbus product:

{
  "profile ":{
    productKey: "The product key of the product.",
  },
  "properties": [
    {
      "identifier": "The ID of each property. Each ID must be unique for the product.",
      "operateType": "The operation type. Valid values: coilStatus, inputStatus, holdingRegister, and inputRegister.",
      "registerAddress": "The register address.",
      "originalDataType": {
        "type": "The type of original data. Valid values: int16, uint16, int32, uint32, int64, uint64, float, double, string, and bool.",
        "specs": {
          "registerCount": "The number of registers. This parameter is available only for properties of the string type.",
          "swap16": "This parameter specifies whether to swap the first and last 8 bits of the 16-bit data in the register. This parameter is available for all properties, except for properties of the string and bool types.",
          "reverseRegister": "This parameter specifies whether to swap the first and last 16 bits of the original 32-bit data. This parameter is available for all properties, except for properties of the string and bool types."
        }
      },
      "scaling": "The zoom factor. This parameter is available for all properties, except for properties of the string and bool types.",
      "trigger": "The data report method. Valid values: 1: specifies to report data at a specific time and 2: specifies to report changes."
    }
  ]
}

            

Procedure

  1. In the IoT Platform console, add features. For more information, see Add a TSL feature and Batch add TSL features.
  2. Implement the TSL model of a product. For more information, see the Link SDK documentation.
  3. After the TSL model is implemented, the devices of the product can report properties and events to IoT Platform. IoT Platform can send commands to devices to set properties or call services. For more information, see Device properties, events, and services. IoT Platform can call the SetDeviceDesiredProperty API operation to specify the required value for a device property. For more information about how a device can obtain the required value of a property, see Desired device property values.