Introduction to Thing Specification Language

The Thing Specification Language (TSL) refers to a description file provided for the configuration between the end-side and the server, which is used to describe the configuration items supported by the end-side and the constraints corresponding to the configuration items.

Overview

The SenseLink platform supports devices to define the TSL. The data model consisting of the configuration (properties, status) of the actual device facilitates the management of the device through the cloud.

Function Type	Description
Properties	Include parameter naming, parameter types, control types, check rules for each function of the product. Triggered by the device or platform to modify
Status	The status of a peripheral component of the device. The platform only reads but does not write, and only maintains the latest status, such as door magnetism status, thermal imaging system connection status, bluetooth lock battery

TSL

TSL is a JSON format file that is reported by the device when it first accesses SenseLink and is stored in the backend. As you open the details of a device on the web, the web can then dynamically load the TSL and TSL values corresponding to the device. This allows you to ensure consistency between the remote configuration function in the cloud and the local function of the device without upgrading the backend service.

TSL Usage Flow

1.Add TSL to the app and complete the creation based on TSL Data Structure 2.Create the required language pack. For its format, please see TSL internationalization. 3.After completing the development, you can report properties and events on the device, and set properties and invoke services on the cloud, and view the interface call steps Update Process 4.The attributes, events and completed service call data reported from the device will be displayed on the Device Settings tab of Device Details page of the corresponding device in the SenseLink console after passing the data verification.

TSL Structure

TSL is a json file containing "engineVersion", "modelVersion" at the top level: "0.0.1", "deviceType" basic information and related setting status "properties", "status" composition:

{
  "engineVersion": "0.0.1",//Engine version
  "modelVersion": "0.0.1", //Model version
  "deviceType": "sps", // Device type
  "properties": [/*... */], // Function configuration items
  "status": [/*...*/]// Device peripheral status
}

Properties

Properties is composed of several modules, each containing multiple set items. Each setting item, also known as fields element, is a description and function definition for each setting item.

{
  "properties": [{
    "name": "group-name",
    "fields": [{ // Collection of configuration items
      "key": { // Description of the name of configuration items
        "name": "product_customer", // Name
        "desc": "vendor-customer" // used to describe name, with no real purpose
      },
      "value": {} // Description of optional values for configuration items
      ]
   }]
}

Field is composed of key and value. Key describes the name of the configuration item, and Value is the definition including the optional value, style, status of the configuration item. The following is an explanation of some fields. For more configuration, please see [TSL data structure] (# TSL data structure).

type: required, the type of the configuration item value, which can be int, float, string, boolean and others

ranges: optional, to express the interval of the value when the type is int, float, etc., including min: minimum value, max: maximum value, default: default value.

ui: optional, default as text, used to indicate web/device input control style.

List of available values for ui:

ui optional values	description
number	number picker
select	drop-down box
checkbox	multi-select box
radio	radio button
date	time picker
text	single-line text input
textarea	multi-line text input
image	image upload and display

options: optional, used when Value is exhaustible (such as wiegand32, wiegand34, and wiegand2602), generally used with select for ui.

Status

Refers to the status of a peripheral component of a device. The platform only reads and does not write, and only maintains the latest state. The JSON file contains name, enable, and options, corresponding to the name, display or not, and optional values. For more information, please see [TSL data structure] (# TSL data structure).

TSL Internationalization

Defines the display names of device types, attributes, and status of all TSL in the system on the device/web, and stores them separately by different languages. TSL internationalization is to explain the TSL values and names in layman's terms for the cloud console and reduce the difficulty of operation. Each language pack is composed of files in JSON format, and the corresponding Key is a translation for the corresponding part of the TSL.

Field	Description
deviceTypes	set of device types, e.g.: "deviceType": "spse"
groups	TSL categorization name, translation of name in Properties, e.g.: properties[{"name": "general", ...}]
fields	name of the configuration item, all "name" fields of fields under Properties
values	the value corresponding to the configuration, all values in TSL, including the value in Status
status	the display name of the device peripheral status, the "name" field under Status
common	common translation, e.g. "modelVersion": "Device model version"

For more information on data structure, please see Data structure of language pack.

Appendix

Update Process

Update Process

Data structure of language pack

An example of the data structure of the language pack is as follows.

{
  "versionInfo": {
    "version": "0.0.1",
    "log": "",
    "updated": "2020-04-21 12:00:00"
  },
  "common": {
    "modelVersion": "Device model version"
  },
  "deviceTypes": {
    "sps": "SensePass"
  },
  "groups": {
    "general": "General Settings"
  },
  "fields": {
    "identify_mode": "identify_mode"
  },
  "values": {
    "enable": "Enable",
    "disable": "Disable"
  },
  "status": {
    "door_status": "Magnetism Status"
  }
}

TSL Data Structure

An example of the JSON field structure for TSL is as follows:

{
  "engineVersion": "0.0.1",//Engine version
  "modelVersion": "0.0.1", //Model version
  "deviceType": "sps",
  "properties": [{
    "name": "features",
    "fields": [{
      "key": {
        "name": "identify_mode",
        "desc": "Enabled State"
      },
      "value": {
        "required": true, // required or not. It’s non-required by default if not set.
        "type": "int", //data type, must be set, including numeric, boolean, and string.
        "editable": true, // Editable or not. It cannot be edited by default if not set, 
        /*
        ** UI components must be set with the following types
        *** Number picker number
        *** Drop-down box select
        *** Multi-select box checkbox
        *** Radio button radio
        *** Time picker date
        *** Single line text input text
        *** Multi-line text input textarea
        *** Image upload and display image
        *** Default is text
        */
        "ui": "select",
        "ranges": [{
          "min": 1,
          "max": 2,
          "enable": "{open_way}==2", //js expression string or boolean value. It is enabled by default if not set. The fields in curly braces indicate the value to be replaced, e.g. if the open_way value is 2, the expression is parsed as "2==2".
          "default": 1.5
        },{
          "min": 3,
          "max": 4,
          "enable": "{open_way}==3",//js expression string or Boolean value. It is enabled by default if not set.
          "default": 3.5
        }],
        "step": 0.5,// Step size, only for values
        "precision": 1, // Precision, indicates the exact number of decimal places, non-negative integer, and works only for numeric values, not required
        "mult": true, //multiple-choice or not, not required. The passing parameter is a single value by default if it’s not set. Multiple values only work for dropdown and multi-select boxes.
        "enable": "{open_way}==1", // js expression string or boolean value, not required, indicates the display and hiding of the field via linkage control. If the enable property is not set, it is available by default.
        "size": 20, // string length, not required, only works for string and image base64
        "timeFormat": "yyyy-MM-dd HH:mm:ss", //if ui is date, the time format must be filled in. hh means 12 hours, HH means 24 hours
        "options": [{
          "value": 0,
          "name": "off",
          "enable": "{open_way}==2", // js expression string or boolean value. Returns true, indicating that the selected value can be used in the candidate item. If the enable property is not set, it is available by default.
        }, {
          "value": 1,
          "name": "on", // js expression string or boolean value. Returns true, indicating that the selected value can be used in the candidate item. If the enable property is not set, it is available by default.
          "enable": "{open_way}==3"
        }],
        //watch: indicates status listening
        /*
        ** The following example indicates that the value of the current field is associated with the use_mode field.
        ** When the use_mode field changes, the value of the current field is equal to the value after the expression is executed "{use_mode}==2?1.5:{use_mode}==1?2:{recognition_distance}"
        */
        "watch":{
          "use_mode": "{use_mode}==2?1.5:{use_mode}==1?2:{recognition_distance}"
        }
      },
    }]
  }],
  "status": [{
    "name": "wifi",
    "enable": true, // js expression string or boolean value. Controls the display condition of this field. If the enable property is not set, it is available by default.
    "options": [{
      "value": 0,
      "name": "off",
      "enable": "{open_way}==2", // js expression string or boolean value. Returns true, indicating that the selected value can be used in the candidate item. If the enable property is not set, it is available by default.
    },{
      "value": 1,
      "name": "on",
      "enable": "{open_way}==1", // js expression string or boolean value. Returns true, indicating that the selected value can be used in the candidate item. If the enable property is not set, it is available by default.
    }],
  }]
}