通用物模型
页面导读
适用场景适合定义产品属性、功能、事件，并沉淀可复用的通用物模型。
前置条件已明确设备能力、数据类型、读写方向、单位、取值范围和是否需要历史存储。
操作路径通用物模型 → 新增模型 → 产品详情 → 产品模型 → 新增或导入通用物模型。
验收点模型标识唯一，设备端上报字段与平台标识一致，产品发布后数据可正常解析。
使用入口与推荐流程
- 先从设备协议或硬件说明中梳理设备属性、可执行功能、事件和标签。
- 进入 设备管理 → 通用物模型 沉淀可复用模型，或在产品详情的产品模型中直接新增。
- 为每个标识符确认数据类型、单位、读写性、历史存储、图表展示和分享权限。
- 产品发布并接入设备后，通过运行状态、数据采集、事件日志、规则场景和组态变量验证模型是否可用。
物模型的具体介绍
1、概述
物模型是产品数字化的描述，定义了产品的功能，物模型将不同品牌不同品类的产品功能抽象归纳，形成“标准物模型”，便于各方用统一的语言描述、控制、理解产品功能。 物模型由若干条“参数”组成，参数按描述的功能类型不同，又分为属性、功能和事件。
2、功能说明
物模型是物理空间中的实体（如传感器设备、消防装置、园区、工厂等）在云端的数字化表示，属性、功能、事件三个维度，分别描述了该实体是什么、能做什么、可以对外提供哪些信息、可以自定义补充哪些信息。定义了物模型的这三个维度，即完成了产品功能的定义。
| 类型 | 说明 |
|---|---|
| 属性 | 用于描述设备运行时具体信息和状态。例如，环境监测设备所读取的当前环境温度、智能灯开关状态、电风扇风力等级等。属性可分为读、写和上报三种类型，即支持读取、设置属性、设备上报属性。 当属性数据来源为“规则”时，则称该属性为规则属性。 |
| 功能 | 指设备可供外部调用的指令或方法。服务调用中可设置输入和输出参数。输入参数是服务执行时的参数，输出参数是服务执行后的结果。相比于属性，服务可通过一条指令实现更复杂的业务逻辑，例如执行某项特定的任务。 |
| 事件 | 设备运行时，主动上报给云端的信息，一般包含需要被外部感知和处理的信息、告警和故障。事件中可包含多个输出参数。例如，某项任务完成后的通知信息；设备发生故障时的温度、时间信息；设备告警时的运行状态等。事件可以被订阅和推送。 |
3、物模型支持的数据类型
| 参数 | 说明 | 示例 |
|---|---|---|
| int | 整型 | 100 |
| double | 小数型 | 100.45 |
| boolean | 布尔型。采用0（false）或1（true）来定义布尔值 | 1表示是、0表示否 |
| enum | 枚举型。定义枚举项的参数值和参数描述。 | [{key:1,value:1}] |
| string | 字符串 | 你好！fastbee平台 |
| array | 数组。需声明数组内的元素类型、数组元素个数和元素标识。需确保同一个数组元素类型相同。 | [1, 2, 3, 4, 5, 6] |
| Object | 对象型 | [{id:"Object",name:"对象",datatype:{type:"object",params:[{key1:value1}]}}] |
提示
注意：在产品详情页-产品模型新增或导入通用物模型时，如果物模型是数组或对象，会被自动拆分成多个非数组、对象类型物模型
4、操作步骤
1.登陆fastbee物联网平台
2.左侧导航栏，选择设备管理->通用物模型，点击新增按钮，创建通用物模型
3.左侧导航栏，选择设备管理->产品管理，进入产品详情页->产品模型，产品必须先点击**取消发布**才能编辑
4.然后点击 "新增" 或 "导入通用物模型" 按钮，根据设备实际情况，合理设计物模型
4.1、物模型定义
在接入一个设备时，首先根据设备以及设备接入文档(报文说明)， 将设备所属产品物模型的属性、功能以及事件设计好
属性用于定义一些指标数据，如：电压，温度等。 属性都应该是简单的数据类型
功能用于定义设备具有的一些可执行动作
事件用于定义设备在特定条件时，发生的动作、告警或故障等信息
4.2、物模型新增
| 配置项 | 说明 |
|---|---|
| 模型名称 | 必填，物模型名称 |
| 模型标识 | 必填，后端识别的标识符（注意：同一产品下不同物模型标识符是唯一的） |
| 模型排序 | 必填，物模型展示顺序 |
| 模型类别 | 必选，属性、功能、事件 |
| 模型特性 | 勾选 属性：图表展示、实时监测、是否只读数据、历史存储、分享权限； 功能：是否只读数据、是否进行历史存储、分享权限； 事件：默认只读、是否进行历史存储、分享权限 |
| 数据类型 | 单选下拉框，整数、小数、布尔、枚举、字符串、数组、对象 |
| 取值范围 | 仅整数和小数显示，取值区间，最小值和最大值 |
| 单位 | 仅整数和小数显示，如：元，℃ |
| 步长 | 仅整数和小数显示，取值间隔，步长是指设备上报或下发数值时，递增或递减的间隔。 |
| 计算公式 | 仅整数和小数显示，加减乘除计算 |
| 布尔值 | 布尔类型显示，0、1对应文本（打开或关闭） |
| 展示方式 | 仅枚举类型显示，单选下拉框 |
| 枚举项 | [{key:1,value:1}] |
| 最大长度 | 仅字符串类型显示，字符串的最大长度 |
| 数组类型 | 仅数组类型显示，单选，整数、小数、字符串、对象 |
| 元素个数 | 仅数组类型显示，数组元素个数 |
| 元素标识 | 仅数组类型显示，每个元素的序号标识，可根据具体情况配置，比如：子设备 1、3、5 |
| 对象参数 | 仅 数组--对象 类型显示，在数组中添加具体的对象参数 |
模型各特性说明：
- 图表展示：勾选则会以图表方式展示，仅支持整数和小数
- 实时监测：需要设备支持，通过实时监测主题/{productId}/{deviceNum}/monitor/post上报物模型数据，仅支持整数和小数
- 是否只读数据：勾选后不能下发指令
- 历史存储：设备每次上报的数据都会存储到关系型数据库或者时序型数据库
- 分享权限：勾选后终端用户才可分享该物模型给其他终端用户
5、配置物模型
5.1、配置物模型
- 配置设备模型分为: 属性properties，功能functions，事件events
- 注意：属性、事件类物模型历史存储到iot_device_log表，功能类物模型历史存储到iot_function_log表
5.2、模型数据结构
数据结构：
java
{
"properties":[...属性],
"functions":[...功能],
"events":[...事件],
"tags":[...标签]
}属性
用于定义设备属性，描述设备运行时的具体信息和状态。
例如: 设备温度，co2等。 平台可主动下发指令获取设备属性，设备也可以通过消息上报属性。
数据结构
java
{
"properties": [
{
"id": "co2",
"name": "二氧化碳",
"isChart": 1,
"isMonitor": 1,
"isHistory": 1,
"isSharePerm": 0,
"isReadonly": 1,
"datatype": {
"max": 6000,
"min": 100,
"step": 1,
"type": "integer",
"unit": "ppm"
}
},
{
"id": "temperature",
"name": "空气温度",
"isChart": 1,
"isMonitor": 1,
"isHistory": 1,
"isSharePerm": 0,
"isReadonly": 1,
"datatype": {
"max": 120,
"min": -20,
"step": 0.1,
"type": "decimal",
"unit": "℃"
}
}
]
}功能
根据设备可供外部调用的指令或方法，定义设备功能。平台可主动调用设备功能。例如：设备运行档位、开关操作等。
数据结构：
java
{
"functions": [
{
"id": "status",
"name": "上报状态",
"isHistory": 0,
"isSharePerm": 0,
"isReadonly": 0,
"datatype": {
"type": "enum",
"showWay": "button",
"enumList": [
{
"text": "更新状态",
"value": "update_status"
}
]
}
},
{
"id": "irc",
"name": "射频遥控",
"isHistory": 1,
"isSharePerm": 0,
"isReadonly": 0,
"datatype": {
"type": "enum",
"showWay": "button",
"enumList": [
{
"text": "遥控学习",
"value": "FFXX01"
},
{
"text": "遥控清码",
"value": "FFXX02"
},
{
"text": "打开开关",
"value": "FFXX03"
},
{
"text": "关闭开关",
"value": "FFXX04"
},
{
"text": "暂停",
"value": "FFXX05"
},
{
"text": "锁定",
"value": "FFXX06"
}
]
}
},
{
"id": "report_monitor",
"name": "上报数据",
"isHistory": 0,
"isSharePerm": 0,
"isReadonly": 0,
"datatype": {
"max": 10,
"min": 1,
"step": 1,
"type": "integer",
"unit": "次数"
}
},
{
"id": "switch",
"name": "设备开关",
"isHistory": 1,
"isSharePerm": 0,
"isReadonly": 0,
"datatype": {
"type": "bool",
"trueText": "打开",
"falseText": "关闭"
}
},
{
"id": "gear",
"name": "运行档位",
"isHistory": 1,
"isSharePerm": 0,
"isReadonly": 0,
"datatype": {
"type": "enum",
"showWay": "select",
"enumList": [
{
"text": "低速档位",
"value": "0"
},
{
"text": "中速档位",
"value": "1"
},
{
"text": "中高速档位",
"value": "2"
},
{
"text": "高速档位",
"value": "3"
}
]
}
},
{
"id": "message",
"name": "屏显消息",
"isHistory": 1,
"isSharePerm": 0,
"isReadonly": 0,
"datatype": {
"type": "string",
"maxLength": 1024
}
},
{
"id": "reset",
"name": "设备重启",
"isHistory": 1,
"isSharePerm": 0,
"isReadonly": 0,
"datatype": {
"type": "enum",
"showWay": "button",
"enumList": [
{
"text": "重启",
"value": "restart"
}
]
}
},
{
"id": "array_01_light_color",
"name": "灯光色值1",
"isHistory": 1,
"isSharePerm": 0,
"isReadonly": 0,
"datatype": {
"max": 100,
"min": 0,
"step": 1,
"type": "integer",
}
}
]
}事件
用于设备的额外属性，添加拓展字段。例如：环境温度过高、设备发生异常等。
数据结构：
java
{
"functions": [],
"events": [
{
"id": "height_temperature",
"name": "环境温度过高",
"isHistory": 1,
"isSharePerm": 0,
"isReadonly": 0,
"datatype": {
"max": 100,
"min": 0,
"step": 0.1,
"type": "decimal",
"unit": "℃"
}
},
{
"id": "exception",
"name": "设备发生异常",
"isHistory": 1,
"isSharePerm": 0,
"isReadonly": 0,
"datatype": {
"type": "string",
"maxLength": 1024
}
}
]
}6、通用物模型与产品的关系
创建通用物模型后，不同产品都可以导入通用物模型使用；
7、产品与设备物模型关系
产品有物模型配置，一个产品可以添加多个设备，设备会继承产品下所有的物模型配置。
8、多租户
- admin账号创建的通用物模型属于系统公有，不做租户隔离，所有账号都能看见；
- 非admin账号创建的通用物模型属于私有，做租户隔离、用户隔离，根据数据权限划分展示；
9、模型运用界面
- 前端通过模型定义动态展示设备运行状态或者设备操作界面
- 服务端可通过统一的API获取设备模型并进行相关操作，如：在发送设备消息时进行参数校验， 在收到设备消息进行类型转换处理
- PC端默认展示运行状态和数据采集页面
- 移动端默认展示状态和数据模式
- 移动端状态模式界面支持自定义，可在产品应用配置点击配置，在配置界面根据自己需求自定义界面，配置好后点击启用
10、物模型设计规范
物模型决定后续设备上报、平台显示、规则触发、告警、组态和数据中心的可用性。设计时建议遵循以下规范：
| 规则 | 建议 |
|---|---|
| 标识符 | 使用英文、数字和下划线，避免中文、空格和特殊符号 |
| 命名 | 能表达业务含义，例如 temperature、switch、voltage |
| 数据类型 | 按真实数据选择，数值不要全部用字符串 |
| 单位 | 温度、电压、电流、流量等数值建议配置单位 |
| 读写性 | 只能设备上报的设为只读，平台可控制的设为读写 |
| 历史存储 | 需要趋势、报表、告警分析的数据才开启历史 |
| 枚举值 | 枚举键值稳定，不要频繁修改已上线设备使用的值 |
| 数组对象 | 提前规划索引和子字段命名，避免后期变更影响解析 |
上报与显示验收
| 验收项 | 正常表现 |
|---|---|
| 属性上报 | 设备运行状态能看到最新属性值 |
| 功能下发 | 平台下发后设备收到指令并回传结果 |
| 事件上报 | 事件日志出现对应记录 |
| 历史数据 | 开启历史后，数据中心可查询历史值 |
| 规则触发 | 规则或场景能选择到对应变量 |
| 组态绑定 | 组态变量列表能选择对应物模型 |
| 移动端展示 | 状态模式或数据模式能正常展示 |
常见问题
上报成功但运行状态不显示
检查上报 id 是否与标识符一致，产品是否已发布，设备是否使用该产品，数据类型是否能被平台转换。
修改物模型后设备仍按旧模型展示
检查产品是否重新发布，设备详情是否刷新，前端缓存是否清理。已经上线设备需要确认是否继承最新模型。
数组或对象数据无法正确解析
检查数组索引前缀、对象子字段命名、数据是否按字符串约定传递，参考 MQTT 文档中的数组对象说明。
规则里选不到变量
检查物模型是否启用，产品是否发布，场景或规则绑定的产品和设备是否正确。
二次开发入口
| 类型 | 路径或接口 | 说明 |
|---|---|---|
| Vue3 页面 | vue3/src/views/iot/product | 产品物模型配置入口 |
| Vue3 API | vue3/src/api/iot | 物模型相关请求 |
| 后端接口 | /iot/model | 物模型管理接口 |
| 后端接口 | /iot/template | 通用物模型模板 |
| 数据模块 | springboot/fastbee-iot-data | 物模型数据入库和查询 |
| 协议模块 | springboot/fastbee-protocol | 上报数据解析与转换 |