物的模型TSL
更新时间：2018-08-16 17:55:13
TSL概念
物模型是对设备是什么，能做什么的描述，包括设备身份标识、连接状态、描述信息，以及设备的属性（properties）、服务(services)、事件(events)，后三者构成了设备的功能定义。阿里IoT通过定义一种物的描述语言来描述物模型，称之为 TSL（即 Thing Specification Language）。
产品功能
在每个产品中，都需要定义一套物的模型，即“功能定义”。每个产品有两类功能：
| 功能类型 | 描述 |
|---|---|
| 标准功能 | 根据ICA数据标准，平台为每个品类创建了默认的标准功能，分为可选和必选 |
| 自定义功能 | 如果标准功能不符合您的设备特征，您也可以自定义功能 |
而功能的组成为三要素：属性、事件、服务。分别用于：
| 功能三要素 | 描述 |
|---|---|
| 属性 | 设备的功能模型之一，一般用于描述设备运行时的状态，如环境监测设备所读取的当前环境温度等。属性支持get和set，应用系统可发起对属性的读取和设置请求 |
| 服务 | 设备的功能模型之一，可被外部调用的能力或方法，包含输入参数和输出参数，相比于下发指令设置属性值，服务可通过一条指令实现更复杂的业务逻辑，如执行某项特定的任务 |
| 事件 | 设备的功能模型之一，运行时的事件，相比于属性状态，事件一般而言包含设备需要被外部感知和处理的通知信息，可包含多个输出参数，如某项任务完成的信息或者设备发生故障/告警时的温度等，事件可以被订阅和推送 |
根据步骤在控制台完成功能定义后，平台将自动生成 JSON 格式的 TSL，以下是一个完整的 TSL 的示例，供您参考。
功能审核
由于平台目前遵循ICA数据标准，所以自定义的部分需要平台审核，处理周期为1个工作日内，一般不会阻塞您的开发进展。在审核完成之前，平台暂无法使用未通过审核的自定义功能。审核期间，状态如下：
自动生成TSL
功能定义完成后，平台能够根据“标准功能” 和（通过审核后）“自定义功能”，自动生成一份Json格式的TSL。
TSL字段描述说明
{
"schema": "物的TSL描述schema",
"link": "云端系统级uri,用来调用服务/订阅事件",
"profile": {
"productKey": "产品key",
"deviceName": "设备名称"
},
"properties": [
{
"identifier": "属性唯一标识符(产品下唯一)",
"name": "属性名称",
"accessMode": "属性读写类型，只读(r)，只写(w)，读写(rw)",
"required": "是否是必选属性",
"dataType": {
"type": "属性类型: int(原生)，float(原生)，double(原生), text(原生)，date(String类型UTC毫秒)，bool(0或1的int类型)，enum(int类型), struct(结构体类型，可包含前面6种类型)",
"specs": {
"min": "属性最小值(int,float,double类型特有)",
"max": "属性最大值(int,float,double类型特有)",
"unit": "属性单位",
"unitName": "单位的名称"
}
}
}
],
"events": [
{
"name": "事件名称",
"identifier": "事件唯一标识符",
"desc": "事件描述",
"type": "事件类型(info,alert,error)",
"required": "是否是必选事件",
"outputData": [
{
"identifier": "参数唯一标识符",
"name": "参数名称",
"dataType": {
"type": "参数类型: int(原生)，float(原生)，double(原生), text(原生)，date(String类型UTC毫秒)，bool(0或1的int类型)，enum(int类型), struct(结构体类型，可包含前面6种类型)",
"specs": {
"min": "参数最小值(int,float,double类型特有)",
"max": "参数最大值(int,float,double类型特有)",
"unit": "参数单位",
"unitName": "单位的名称"
}
}
}
],
"method": "事件对应的方法名称(根据identifier生成)"
}
],
"services": [
{
"name": "服务名称",
"identifier": "服务唯一标识符",
"desc": "服务描述",
"required": "是否是必选服务",
"inputData": [
{
"identifier": "入参唯一标识符",
"name": "入参名称",
"dataType": {
"type": "入参类型: int(原生)，float(原生)，double(原生), text(原生)，date(String类型UTC毫秒)，bool(0或1的int类型)，enum(int类型), struct(结构体类型，可包含前面6种类型)",
"specs": {
"min": "入参最小值(int,float,double类型特有)",
"max": "入参最大值(int,float,double类型特有)",
"unit": "入参单位",
"unitName": "单位的名称"
}
}
}
],
"outputData": [
{
"identifier": "出参唯一标识符",
"name": "出参名称",
"dataType": {
"type": "出参类型: int(原生)，float(原生)，double(原生), text(原生)，date(String类型UTC毫秒)，bool(0或1的int类型)，enum(int类型), struct(结构体类型，可包含前面6种类型)",
"specs": {
"min": "出参最小值(int,float,double类型特有)",
"max": "出参最大值(int,float,double类型特有)",
"unit": "出参单位",
"unitName": "单位的名称"
}
}
}
],
"method": "服务对应的方法名称(根据identifier生成)"
}
]
}
TSL样例
{
"schema": "http://aliyun/iot/thing/desc/schema",
"link": "/sys/q408EXte2fy/airCondition/thing/",
"profile": {
"productKey": "q408EXte2fy",
"deviceName": "airCondition"
},
"properties": [
{
"identifier": "fan_doule_property",
"name": "风扇双精度型属性",
"accessMode": "r",
"required": true,
"dataType": {
"type": "double",
"specs": {
"min": "0.0",
"max": "100.0",
"unit": "g/ml",
"unitName": "毫升"
}
}
},
{
"identifier": "fan_int_property",
"name": "风扇整数型属性",
"accessMode": "rw",
"required": true,
"dataType": {
"type": "int",
"specs": {
"min": "0",
"max": "100",
"unit": "g/ml",
"unitName": "毫升"
}
}
},
{
"identifier": "batch_enum_attr_id",
"name": "风扇枚举型属性",
"accessMode": "r",
"required": true,
"dataType": {
"type": "enum",
"specs": {
"0": "one",
"1": "two",
"2": "three"
}
}
},
{
"identifier": "fan_float_property",
"name": "风扇浮点型测试",
"accessMode": "r",
"required": true,
"dataType": {
"type": "float",
"specs": {
"min": "0.0",
"max": "100.0",
"unit": "g/ml",
"unitName": "毫升"
}
}
},
{
"identifier": "fan_text_property",
"name": "风扇字符型属性",
"accessMode": "r",
"required": true,
"dataType": {
"type": "text",
"specs": {
"length": "64",
"unit": "g/ml",
"unitName": "毫升"
}
}
},
{
"identifier": "fan_date_property",
"name": "风扇时间型属性",
"accessMode": "r",
"required": true,
"dataType": {
"type": "date",
"specs": {}
}
},
{
"identifier": "batch_boolean_attr_id",
"name": "风扇布尔型属性",
"accessMode": "r",
"required": true,
"dataType": {
"type": "bool",
"specs": {
"0": "close",
"1": "open"
}
}
},
{
"identifier": "fan_struct_property",
"name": "风扇结构型属性",
"accessMode": "r",
"required": true,
"dataType": {
"type": "struct",
"specs": [
{
"identifier": "fan_struct_property_float_child",
"name": "风扇双精度型属性",
"dataType": {
"type": "double",
"specs": {
"min": "0.0",
"max": "100.0",
"unit": "g/ml",
"unitName": "毫升"
}
}
},
{
"identifier": "fan_struct_property_float_child",
"name": "风扇结构型属性浮点子属性",
"dataType": {
"type": "float",
"specs": {
"min": "0.0",
"max": "255.0",
"unit": "°",
"unitName": "度"
}
}
},
{
"identifier": "fan_struct_property_int_child",
"name": "风扇结构型属性整数子属性",
"dataType": {
"type": "int",
"specs": {
"min": "0",
"max": "255",
"unit": "°",
"unitName": "度"
}
}
},
{
"identifier": "fan_struct_property_text_child",
"name": "风扇结构型属性字符子属性",
"dataType": {
"type": "text",
"specs": {
"length": "200",
"unit": "unit",
"unitName": "单位"
}
}
},
{
"identifier": "fan_struct_property_date_child",
"name": "风扇结构型属性时间子属性",
"dataType": {
"type": "date",
"specs": {}
}
},
{
"identifier": "fan_struct_property_enum_child",
"name": "风扇结构型属性枚举子属性",
"dataType": {
"type": "enum",
"specs": {
"0": "one",
"1": "two",
"2": "three"
}
}
},
{
"identifier": "fan_struct_property_boolean_child",
"name": "风扇结构型属性布尔子属性",
"dataType": {
"type": "bool",
"specs": {
"0": "close",
"1": "open"
}
}
}
]
}
}
],
"events": [
{
"name": "alarm",
"identifier": "alarm",
"desc": "警报",
"type": "info",
"required": true,
"outputData": [
{
"identifier": "errorCode",
"name": "错误码",
"dataType": {
"type": "text",
"specs": {
"length": "255",
"unit": ""
}
}
}
],
"method": "thing.event.alarm.post"
},
{
"identifier": "post",
"name": "post",
"type": "info",
"required": true,
"desc": "属性上报",
"method": "thing.event.property.post",
"outputData": [
{
"identifier": "fan_doule_property",
"name": "风扇双精度型属性",
"dataType": {
"type": "double",
"specs": {
"min": "0.0",
"max": "100.0",
"unit": "g/ml",
"unitName": "毫升"
}
}
},
{
"identifier": "fan_int_property",
"name": "风扇整数型属性",
"dataType": {
"type": "int",
"specs": {
"min": "0",
"max": "100",
"unit": "g/ml",
"unitName": "毫升"
}
}
},
{
"identifier": "batch_enum_attr_id",
"name": "风扇枚举型属性",
"dataType": {
"type": "enum",
"specs": {
"0": "one",
"1": "two",
"2": "three"
}
}
},
{
"identifier": "fan_float_property",
"name": "风扇浮点型测试",
"dataType": {
"type": "float",
"specs": {
"min": "0.0",
"max": "100.0",
"unit": "g/ml",
"unitName": "毫升"
}
}
},
{
"identifier": "fan_text_property",
"name": "风扇字符型属性",
"dataType": {
"type": "text",
"specs": {
"length": "64",
"unit": "g/ml",
"unitName": "毫升"
}
}
},
{
"identifier": "fan_date_property",
"name": "风扇时间型属性",
"dataType": {
"type": "date",
"specs": {}
}
},
{
"identifier": "batch_boolean_attr_id",
"name": "风扇布尔型属性",
"dataType": {
"type": "bool",
"specs": {
"0": "close",
"1": "open"
}
}
},
{
"identifier": "fan_struct_property",
"name": "风扇结构型属性",
"dataType": {
"type": "struct",
"specs": [
{
"identifier": "fan_struct_property_double_child",
"name": "风扇双精度型属性",
"dataType": {
"type": "double",
"specs": {
"min": "0.0",
"max": "100.0",
"unit": "g/ml",
"unitName": "毫升"
}
}
},
{
"identifier": "fan_struct_property_float_child",
"name": "风扇结构型属性浮点子属性",
"dataType": {
"type": "float",
"specs": {
"min": "0.0",
"max": "255.0",
"unit": "°",
"unitName": "度"
}
}
},
{
"identifier": "fan_struct_property_int_child",
"name": "风扇结构型属性整数子属性",
"dataType": {
"type": "int",
"specs": {
"min": "0",
"max": "255",
"unit": "°",
"unitName": "度"
}
}
},
{
"identifier": "fan_struct_property_text_child",
"name": "风扇结构型属性字符子属性",
"dataType": {
"type": "text",
"specs": {
"length": "200",
"unit": "unit",
"unitName": "单位"
}
}
},
{
"identifier": "fan_struct_property_date_child",
"name": "风扇结构型属性时间子属性",
"dataType": {
"type": "date",
"specs": {}
}
},
{
"identifier": "fan_struct_property_enum_child",
"name": "风扇结构型属性枚举子属性",
"dataType": {
"type": "enum",
"specs": {
"0": "one",
"1": "two",
"2": "three"
}
}
},
{
"identifier": "fan_struct_property_boolean_child",
"name": "风扇结构型属性布尔子属性",
"dataType": {
"type": "bool",
"specs": {
"0": "0",
"1": "1"
}
}
}
]
}
}
]
}
],
"services": [
{
"name": "upgrade",
"identifier": "upgrade",
"desc": "升级服务",
"inputData": [
{
"identifier": "model",
"name": "模型",
"dataType": {
"type": "int",
"specs": {
"min": "1",
"max": "100",
"unit": "cm"
}
}
},
{
"identifier": "mac",
"name": "mac号",
"dataType": {
"type": "text",
"specs": {
"length": "255"
}
}
}
],
"outputData": [
{
"identifier": "firmVersion",
"name": "固件版本号",
"dataType": {
"type": "int",
"specs": {
"min": "1",
"max": "100",
"unit": ""
}
}
}
],
"method": "thing.service.upgrade"
},
{
"identifier": "set",
"name": "set",
"required": true,
"desc": "属性设置",
"method": "thing.service.property.set",
"inputData": [
{
"identifier": "fan_int_property",
"name": "风扇整数型属性",
"accessMode": "rw",
"required": true,
"dataType": {
"type": "int",
"specs": {
"min": "0",
"max": "100",
"unit": "g/ml",
"unitName": "毫升"
}
}
}
],
"outputData": []
},
{
"identifier": "get",
"name": "get",
"required": true,
"desc": "属性获取",
"method": "thing.service.property.get",
"inputData": [
"fan_doule_property",
"fan_int_property",
"batch_enum_attr_id",
"fan_float_property",
"fan_text_property",
"fan_date_property",
"batch_boolean_attr_id",
"fan_struct_property"
],
"outputData": [
{
"identifier": "fan_doule_property",
"name": "风扇双精度型属性",
"dataType": {
"type": "double",
"specs": {
"min": "0.0",
"max": "100.0",
"unit": "g/ml",
"unitName": "毫升"
}
}
},
{
"identifier": "fan_int_property",
"name": "风扇整数型属性",
"dataType": {
"type": "int",
"specs": {
"min": "0",
"max": "100",
"unit": "g/ml",
"unitName": "毫升"
}
}
},
{
"identifier": "batch_enum_attr_id",
"name": "风扇枚举型属性",
"dataType": {
"type": "enum",
"specs": {
"0": "one",
"1": "two",
"2": "three"
}
}
},
{
"identifier": "fan_float_property",
"name": "风扇浮点型测试",
"dataType": {
"type": "float",
"specs": {
"min": "0.0",
"max": "100.0",
"unit": "g/ml",
"unitName": "毫升"
}
}
},
{
"identifier": "fan_text_property",
"name": "风扇字符型属性",
"dataType": {
"type": "text",
"specs": {
"length": "64",
"unit": "g/ml",
"unitName": "毫升"
}
}
},
{
"identifier": "fan_date_property",
"name": "风扇时间型属性",
"dataType": {
"type": "date",
"specs": {}
}
},
{
"identifier": "batch_boolean_attr_id",
"name": "风扇布尔型属性",
"dataType": {
"type": "bool",
"specs": {
"0": "close",
"1": "open"
}
}
},
{
"identifier": "fan_struct_property",
"name": "风扇结构型属性",
"dataType": {
"type": "struct",
"specs": [
{
"identifier": "fan_struct_property_double_child",
"name": "风扇双精度型属性",
"dataType": {
"type": "double",
"specs": {
"min": "0.0",
"max": "100.0",
"unit": "g/ml",
"unitName": "毫升"
}
}
},
{
"identifier": "fan_struct_property_float_child",
"name": "风扇结构型属性浮点子属性",
"dataType": {
"type": "float",
"specs": {
"min": "0.0",
"max": "255.0",
"unit": "°",
"unitName": "度"
}
}
},
{
"identifier": "fan_struct_property_int_child",
"name": "风扇结构型属性整数子属性",
"dataType": {
"type": "int",
"specs": {
"min": "0",
"max": "255",
"unit": "°",
"unitName": "度"
}
}
},
{
"identifier": "fan_struct_property_text_child",
"name": "风扇结构型属性字符子属性",
"dataType": {
"type": "text",
"specs": {
"length": "200",
"unit": "unit",
"unitName": "单位"
}
}
},
{
"identifier": "fan_struct_property_date_child",
"name": "风扇结构型属性时间子属性",
"dataType": {
"type": "date",
"specs": {}
}
},
{
"identifier": "fan_struct_property_enum_child",
"name": "风扇结构型属性枚举子属性",
"dataType": {
"type": "enum",
"specs": {
"0": "one",
"1": "two",
"2": "three"
}
}
},
{
"identifier": "fan_struct_property_boolean_child",
"name": "风扇结构型属性布尔子属性",
"dataType": {
"type": "bool",
"specs": {
"0": "close",
"1": "open"
}
}
}
]
}
}
]
}
]
}