物模型指将物理空间中的实体数字化,并在云端构建的该实体的数据模型,用于描述实体的功能。下面介绍物模型相关概念和使用方法。

物模型TSL(Thing Specification Language)是一个JSON格式的文件。它是物理空间中的实体,如传感器、车载装置、楼宇、工厂等在云端的数字化表示,从属性、服务和事件三个维度,分别描述了该实体是什么、能做什么、可以对外提供哪些信息。定义了物模型的这三个维度,即完成了产品功能的定义。

物模型将产品功能类型分为三类:属性、服务和事件。

功能类型 说明
属性(Property) 一般用于描述设备运行时的状态,如环境监测设备所读取的当前环境温度等。属性支持GET和SET请求方式。应用系统可发起对属性的读取和设置请求。
服务(Service) 设备可被外部调用的能力或方法,可设置输入参数和输出参数。相比于属性,服务可通过一条指令实现更复杂的业务逻辑,如执行某项特定的任务。
事件(Event) 设备运行时的事件。事件一般包含需要被外部感知和处理的通知信息,可包含多个输出参数。如,某项任务完成的信息,或者设备发生故障或告警时的温度等,事件可以被订阅和推送。

物模型TSL格式

您可以在产品的功能定义页面,单击物模型TSL,查看JSON格式的TSL。

物模型TSL的JSON字段结构如下:

说明 为了完整展示TSL的结构,以下示例中包含所有参数,不代表实际使用中可能出现的组合。参数后的文字为参数说明,非参数值。各参数的使用场景,请参见参数说明。
{
    "schema": "物模型结构定义的访问URL",
    "profile": {
        "productKey": "产品ProductKey"
    },
    "properties": [
        {
            "identifier": "属性唯一标识符(产品下唯一)",
            "name": "属性名称",
            "accessMode": "属性读写类型:只读(r)或读写(rw)。",
            "required": "是否是标准功能的必选属性",
            "dataType": {
                "type": "属性类型: int(原生)、float(原生)、double(原生)、text(原生)、date(String类型UTC毫秒)、bool(0或1的int类型)、enum(int类型,枚举项定义方法与bool类型定义0和1的值方法相同)、struct(结构体类型,可包含前面7种类型,下面使用"specs":[{}]描述包含的对象)、array(数组类型,支持int、double、float、text、struct)",
                "specs": {
                    "min": "参数最小值(int、float、double类型特有)",
                    "max": "参数最大值(int、float、double类型特有)",
                    "unit": "属性单位(int、float、double类型特有,非必填)",
                    "unitName": "单位名称(int、float、double类型特有,非必填)",
                    "size": "数组元素的个数,最大512(array类型特有)。",
                    "step": "步长(text、enum类型无此参数)",
                    "length": "数据长度,最大10240(text类型特有)。",
                    "0": "0的值(bool类型特有)",
                    "1": "1的值(bool类型特有)",
                    "item": {
                        "type": "数组元素的类型(array类型特有)"
                    }
                }
            }
        }
    ],
    "events": [
        {
            "identifier": "事件唯一标识符(产品下唯一,其中post是默认生成的属性上报事件。)",
            "name": "事件名称",
            "desc": "事件描述",
            "type": "事件类型(info、alert、error)",
            "required": "是否是标准功能的必选事件",
            "outputData": [
                {
                    "identifier": "参数唯一标识符",
                    "name": "参数名称",
                    "dataType": {
                        "type": "属性类型: int(原生)、float(原生)、double(原生)、text(原生)、date(String类型UTC毫秒)、bool(0或1的int类型)、enum(int类型,枚举项定义方法与bool类型定义0和1的值方法相同)、struct(结构体类型,可包含前面7种类型,下面使用"specs":[{}]描述包含的对象)、array(数组类型,支持int、double、float、text、struct)",
                        "specs": {
                            "min": "参数最小值(int、float、double类型特有)",
                            "max": "参数最大值(int、float、double类型特有)",
                            "unit": "属性单位(int、float、double类型特有,非必填)",
                            "unitName": "单位名称(int、float、double类型特有,非必填)",
                            "size": "数组元素的个数,最大512(array类型特有)。",
                            "step": "步长(text、enum类型无此参数)",
                            "length": "数据长度,最大10240(text类型特有)。",
                            "0": "0的值(bool类型特有)",
                            "1": "1的值(bool类型特有)",
                            "item": {
                                "type": "数组元素的类型(array类型特有)"
                            }
                        }
                    }
                }
            ],
            "method": "事件对应的方法名称(根据identifier生成)"
        }
    ],
    "services": [
        {
            "identifier": "服务唯一标识符(产品下唯一,其中set/get是根据属性的accessMode默认生成的服务。)",
            "name": "服务名称",
            "desc": "服务描述",
            "required": "是否是标准功能的必选服务",
            "callType": "async(异步调用)或sync(同步调用)",
            "inputData": [
                {
                    "identifier": "入参唯一标识符",
                    "name": "入参名称",
                    "dataType": {
                        "type": "属性类型: int(原生)、float(原生)、double(原生)、text(原生)、date(String类型UTC毫秒)、bool(0或1的int类型)、enum(int类型,枚举项定义方法与bool类型定义0和1的值方法相同)、struct(结构体类型,可包含前面7种类型,下面使用"specs":[{}]描述包含的对象)、array(数组类型,支持int、double、float、text、struct)",
                        "specs": {
                            "min": "参数最小值(int、float、double类型特有)",
                            "max": "参数最大值(int、float、double类型特有)",
                            "unit": "属性单位(int、float、double类型特有,非必填)",
                            "unitName": "单位名称(int、float、double类型特有,非必填)",
                            "size": "数组元素的个数,最大512(array类型特有)。",
                            "step": "步长(text、enum类型无此参数)",
                            "length": "数据长度,最大10240(text类型特有)。",
                            "0": "0的值(bool类型特有)",
                            "1": "1的值(bool类型特有)",
                            "item": {
                                "type": "数组元素的类型(array类型特有)"
                                }
                            }
                        }
                    }
                }
            ],
            "outputData": [
                {
                    "identifier": "出参唯一标识符",
                    "name": "出参名称",
                    "dataType": {
                        "type": "属性类型: int(原生)、float(原生)、double(原生)、text(原生)、date(String类型UTC毫秒)、bool(0或1的int类型)、enum(int类型,枚举项定义方法与bool类型定义0和1的方法相同)、struct(结构体类型,可包含前面7种类型,下面使用"specs":[{}]描述包含的对象)、array(数组类型,支持int、double、float、text、struct)",
                        "specs": {
                            "min": "参数最小值(int、float、double类型特有)",
                            "max": "参数最大值(int、float、double类型特有)",
                            "unit": "属性单位(int、float、double类型特有,非必填)",
                            "unitName": "单位名称(int、float、double类型特有,非必填)",
                            "size": "数组元素的个数,最大512(array类型特有)。",
                            "step": "步长(text、enum类型无此参数)",
                            "length": "数据长度,最大10240(text类型特有)。",
                            "0": "0的值(bool类型特有)",
                            "1": "1的值(bool类型特有)",
                            "item": {
                                "type": "数组元素的类型(array类型特有)"
                            }
                        }
                    }
                }
            ],
            "method": "服务对应的方法名称(根据identifier生成)"
        }
    ]
}

若产品的节点类型是设备,且接入网关协议为Modbus、OPC UA或自定义时,可以查看物模型扩展配置信息。

Modbus协议产品的扩展配置可用于Modbus子设备的物联网边缘计算,请参见物联网边缘计算文档

Modbus协议产品的扩展配置数据结构如下:

说明 为了完整展示TSL的结构,以下示例中包含所有参数,不代表实际使用中可能出现的组合。参数后的文字为参数说明,非参数值。各参数的使用场景,请参见参数说明。
{
  "profile": {
    "productKey": "产品ProductKey"
  },
  "properties": [
    {
      "identifier": "属性唯一标识符(产品下唯一)",
      "operateType": "(线圈状态/离散量输入/保持寄存器/输入寄存器: coilStatus/inputStatus/holdingRegister/inputRegister)",
      "registerAddress": "寄存器地址",
      "originalDataType": {
        "type": "原始数据类型:int16、uint16、int32、uint32、int64、uint64、float、double、string、bool、customized data(按大端顺序返回hex data)",
        "specs": {
          "registerCount": "寄存器数据个数,string、customized data特有。",
          "swap16": "交换寄存器内高低字节,把寄存器内16位数据的前后8个bit互换(byte1byte2 -> byte2byte1),除string和bool外,其他数据类型特有。",
          "reverseRegister": "交换寄存器顺序,把原始数据32位数据的前后16个bit互换(byte1byte2byte3byte4 -> byte3byte4byte1byte2),除string和bool外,其他数据类型特有。"
        }
      },
      "scaling": "缩放因子,除string和bool外,其他数据类型特有。",
      "trigger": "数据上报方式。1代表按时上报,2代表变更上报。",
      "writeFunctionCode":"读写操作,对于不同的operateType,可选的取值不同。coilStatus:5代表读写(读0x01,写0x05),15代表读写(读0x01,写0x0F),0代表只读0x01,6代表只写0x05,15代表只写0x0F。inputStatus:0代表只读0x02。holdingRegister:6代表读写(读0x03,写0x06),16代表读写(读0x03,写0x10),0代表只读0x03,6代表只写0x06,16代表只写0x10。inputRegister:0代表只读0x04。",
      "writeOnly":"是否只写。0代表非只写,1代表只写。",
      "pollingTime":"采集间隔,单位是ms。无需传入,将使用设备配置的采集间隔。",
      "bitMask":"掩码,bool特有。取值:1、2、4、8、16、32、64、128、256、512、1024、2048、4096、8192、16384、32768,即1<<(0~15)。"
    }
  ]
}            

物模型使用流程

  1. 物联网平台控制台添加物模型,请参见单个添加物模型批量添加物模型
  2. 参见Link SDK文档,进行设备端物模型开发。
  3. 开发完成后,设备端可以上报属性和事件,云端可以设置属性和调用服务,参见设备属性、事件、服务。云端还可以设置设备期望属性值,请参见设备期望属性值
  4. 设备端上报的属性、事件和完成的服务调用数据,在通过强校验或弱校验后,将显示在物联网平台控制台对应设备的设备详情物模型数据页签。您的服务器可以通过服务端订阅云产品流转获得设备属性和事件数据,以及设备属性设置和服务调用指令响应结果。

物模型数据校验

设备上报物模型数据时,物联网平台将按设置的数据校验方式,根据物模型定义进行数据校验。

数据校验分为三种类型:

类型 适用范围 说明
强校验 对于2020年10月14日之前(不含当日)创建的产品,强校验为唯一的校验方式。 校验所有字段。

校验后,流转全量数据,通过流转消息内的标记来区分校验未通过的数据,请参见数据格式

校验后,数据展示在物联网平台控制台对应设备的设备详情物模型数据页签。

弱校验 对于2020年10月14日之后(含当日)创建的产品,弱校验为默认校验方式。 只校验设备数据的idetifier和dataType字段,不校验其他字段。

校验后,流转全量数据,通过流转消息内的标记来区分校验未通过的数据,请参见数据格式

校验后,数据展示在物联网平台控制台对应设备的设备详情物模型数据页签。

免校验 对于2020年10月14日之后(含当日)创建的产品,可以从弱校验切换到免校验。 对上报的数据不进行校验,流转全量数据。

数据不展示在物联网平台控制台对应设备的设备详情物模型数据页签。

说明
  • 免校验目前仅适用于白名单用户。如有需要,请提交工单,提供您的阿里云账号UID,申请成为白名单用户。
  • 仅支持从弱校验切换到免校验,不支持从免校验切换回弱校验。请谨慎操作。

对于2020年10月14日之后(含当日)创建的产品,开启免校验的方法:

物联网平台控制台对应实例下,在左侧导航栏选择设备管理 > 产品,进入产品详情页,在功能定义页签,关闭数据校验开关。