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生成)"
}
]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207