IoT物模型概述
IoT物模型概述
一、什么是物模型
物模型指将物理空间中的实体数字化，并在云端构建该实体的数据模型。在物联网平台中，定义物模型即定义产品功能。完成功能定义后，系统将自动生成该产品的物模型。物模型描述产品是什么，能做什么，可以对外提供哪些服务。
物模型使用JSON格式的文件描述。它是物理空间中的实体，如传感器、车载装置、楼宇、工厂等在云端的数字化表示，从属性、服务和事件三个维度，分别描述了该实体是什么，能做什么，可以对外提供哪些信息。定义了这三个维度，即完成了产品功能的定义。
二、物模型功能定义
属性（Property）： 一般用于描述设备运行时的状态，如设备音量开关状态、环境监测设备所读取的当前环境温度等。属性可以通过读、写操作来实现对设备功能参数的查询和修改；
服务（Service）： 设备可被外部调用的能力或方法，可设置输入参数和输出参数。相比于属性，服务可通过一条指令实现更复杂的业务逻辑，如执行设备固件升级类的某项特定的任务；
事件（Event）： 设备运行时的事件。事件一般包含需要被外部感知和处理的通知信息，可包含多个输出参数。如，某项任务完成的信息，或者设备发生故障或告警时的温度等，事件可以被订阅和推送。
详情见“四、乐橙云物模型格式”。
三、物模型相关协议
| 序号 | 接口功能 | 描述 |
|---|---|---|
| 1 | getProductModel：获取产品物模型 | 根据产品id，获取产品IoT物模型 |
| 2 | iotDeviceControl：请求物模型中Service方法 | 通过物模型操作设备物模型中指定Service方法 |
| 3 | getIotDeviceProperties：获取IoT物模型中指定的Property属性值 | 基于产品物模型，获取指定的Property属性值 |
| 4 | setIotDeviceProperties：设置IoT物模型中指定的Property属性值 | 基于产品物模型，设置指定的Property属性值 |
四、乐橙云IoT物模型模板
{
"schema": "1.0。物模型格式模板的版本, 当前为1.0",
"profile": {
"identifier": "产品型号唯一标识符（标识唯一的产品型号，不同于SN， SN是标识唯一设备）"
},
"//": "物模型属性",
"properties": [
{
"identifier": "属性唯一标识符（产品下唯一）",
"ref": "0。属性引用编号（产品下唯一，必须为数字值字符串，用在协议通信中）",
"name": "属性名称，如：电量",
"description": "本属性的注释说明，用于开发人员理解协议，与desc有区别, desc为bool或单字段的说明",
"accessMode": "rw，属性读写类型：读（r）写（w），只读为r，读写为rw",
"defaultData": "$value。可能是单个值,也可能是数组,访问前先判断, 原为defaultValue",
"//": "基本数据类型有: int, text, bool, date, enum；复杂数据类型有：struct, array。以bool示例",
"dataType": {
"//": "查询或设置时已统一为数字0或1，0即false，1即true，不再使用bool值",
"type": "bool"
},
"desc": "1开|0关",
"dataType": {
"type": "int(原生整型,不包含float类型，转为int类型处理)",
"specs": {
"unit": "属性单位，属性补充描述类定义，所有类型都可以携带",
"//": "int类型特有, 取值范围, 最小值~最大值",
"range": [
0,
9
],
"//": "步长",
"step": 1
}
},
"//": "下述展示其他类型的dataType数据值",
"//": "text示例",
"dataType": {
"//": "text(原生字符串 最长255)",
"type": "text"
},
"//": "date示例",
"dataType": {
"//": "date(格式为YYYY-MM-DD hh:mm:ss的text类型)",
"type": "date"
},
"//": "enum示例",
"dataType": {
"type": "enum(枚举类型，枚举项为int类型)",
"specs": {
"//": "枚举值，enum 类型特有",
"list": [
{
"value": 0,
"desc": "value描述"
},
{
"value": 1,
"desc": "value描述"
}
]
}
},
"//": "struct示例",
"dataType": {
"type": "struct(结构对象类型，可包含以上基本类型)",
"//": "specs为数组，因为包含多个基本类型",
"specs": [
{
"identifier": "标识符",
"ref": "1001",
"name": "名称",
"desc": "描述",
"defaultData": "$value",
"dataType": {
"type": "int"
}
},
{
"identifier": "标识符",
"ref": "1002",
"name": "名称",
"desc": "描述",
"defaultData": "$value",
"dataType": {
"type": "text"
}
}
]
},
"//": "array示例",
"dataType": {
"type": "array（数组类型，可包含以上基本类型及struct类型）",
"specs": {
"//": "数组大小，默认最大128（数组特有）。",
"size": 8,
"item": {
"//": "数组元素的类型",
"type": "int"
}
}
},
"//": "array & struct示例",
"dataType": {
"type": "array（数组类型，可包含以上基本类型及struct类型）",
"specs": {
"//": "数组大小，默认最大128（数组特有）",
"size": 4,
"item": {
"//": "数组元素的类型",
"type": "struct",
"specs": [
{
"ref": "1001",
"name": "名称",
"desc": "描述",
"defaultData": "$value",
"dataType": {
"type": "int"
}
},
{
"ref": "1002",
"name": "名称",
"desc": "描述",
"defaultData": "$value",
"dataType": {
"type": "text"
}
}
]
}
}
},
"//": "错误码定义,可选",
"errorCodes": [
{
"//": "错误码枚举定义",
"code": 40000,
"msg": "错误码描述"
}
]
}
],
"//": "物模型服务",
"services": [
{
"identifier": "服务唯一标识符（产品下唯一）",
"ref": "30。服务引用编号（产品下唯一，必须为数字值字符串，用在协议通信中）",
"name": "服务名称",
"description": "服务的注释说明",
"inputData": [
{
"identifier": "入参唯一标识符",
"ref": "40。入参引用编号（产品下唯一，必须为数字值字符串，用在协议通信中）",
"name": "入参名称",
"desc": "入参描述",
"dataType": {
"//": "同属性中的定义"
}
}
],
"outputData": [
{
"identifier": "出参唯一标识符",
"ref": "50。出参引用编号（产品下唯一，必须为数字值字符串，用在协议通信中）",
"name": "出参名称",
"desc": "出参描述",
"dataType": {
"//": "同属性中的定义"
}
}
],
"//": "错误码定义,可选",
"errorCodes": [
{
"//": "错误码枚举定义",
"code": 40000,
"msg": "错误码描述"
}
],
"method": "服务对应的方法名称（根据identifier生成）"
}
],
"//": "物模型事件",
"events": [
{
"identifier": "事件唯一标识符（产品下唯一）",
"//": "事件引用编号（产品下唯一，必须为数字值字符串，用在协议通信中）",
"ref": "10",
"name": "事件名称",
"description": "事件的注释说明",
"//": "事件类型（info、alert、error）",
"type": "error",
"outputData": [
{
"identifier": "参数唯一标识符",
"//": "参数引用编号（产品下唯一，必须为数字值字符串，用在协议通信中）",
"ref": "20",
"name": "参数名称",
"desc": "参数描述",
"dataType": {
"//": "同属性中的定义"
}
}
],
"method": "事件对应的方法名称（根据identifier生成）"
}
]
}