驱动schema说明
本文将详细介绍 数据接入驱动 的 schema 的格式, 以及如何根据自己的需求定义 schema.
介绍
每个 数据接入驱动 进程为一个驱动实例, 每个驱动实例可以配置多个 模型(工作表), 每个模型中可以添加多个 设备.
驱动实例、模型(工作表) 和 设备 都可以有独立的配置信息, 可以相同也可以不同.
数据接入驱动 的 schema 就是用于定义 数据接入驱动 的配置信息, 其中包括 驱动实例配置, 模型配置(工作表) 和 设备配置, 分别对应 驱动实例、模型(工作表) 和 设备 的配置信息. 其中每一项中又包含 驱动配置、数据点配置 和 命令配置 3 个部分.
通常情况下, 驱动实例配置, 模型配置(工作表) 和 设备配置 的配置是相同的, 但有些场景中会有所不同. 但一般只有 驱动配置 内容不同, 但 数据点配置 和 命令配置 通常情况是相同的.
一般在实现 数据接入驱动 时, 需要将 驱动实例配置, 模型配置(工作表) 和 设备配置 进行合并, 合并后的配置才是设备的最终配置, 配置的优先级从高到低为 设备 > 模型(工作表) > 驱动实例.
整体格式介绍
schema 内容是 Json Schema, 在 设备配置 页面中, 会根据 schema 的内容动态生成配置表单.
最外层定义了 driver、model 和 device 3 个配置项, 分别对应 驱动实例配置, 模型配置(工作表) 和 设备配置. 如下所示:
{
"driver": {...}, // 驱动实例配置
"model": {...}, // 模型配置(工作表)
"device": {...} // 设备配置
}
每个配置项中都包含 settings, tags 和 commands 3 个部分, 分别对应 驱动配置, 数据点配置 和 命令配置. 以 driver 为例, 展开后整体格式如下所示:
{
"driver": {
"properties": {
"settings": { // 驱动配置
"title": "实例配置",
"type": "object",
"properties": {}, // 驱动配置项
"required": [] // 驱动配置项中的必填项列表
},
"tags": { // 数据点配置
"title": "数据点",
"type": "array",
"items": {
"type": "object",
"properties": {}, // 数据点配置项
"required": [] // 数据点配置项中的必填项列表
}
},
"commands": { // 命令配置
"title": "命令",
"type": "array",
"items": {
"type": "object",
"properties": {}, // 命令配置项
"required": [] // 命令配置项中的必填项列表
}
}
}
}
}
只需要关注 properties 和 required 的内容即可, 其他内容都是固定的.
详细说明
接下来会分别详细介绍 驱动配置, 数据点配置 和 命令配置 的格式.
驱动配置说明
驱动配置 为驱动进行数据采集所需要的配置项. 例如想通过 MQTT 接收设备发送的数据, 驱动必须要知道 MQTT 服务器地址、端口、用户名、密码以及订阅的主题等信息, 这些信息就是 驱动配置.
驱动配置 的 properties 为配置项列表, required 为必填项列表. 以 MQTT 为例, 驱动配置 的 properties 和 required 如下所示:
{
"driver": {
"properties": {
"settings": {
"title": "实例配置",
"type": "object",
"properties": {
"server": {
"type": "string",
"title": "服务器地址",
"descripption": "MQTT 服务器地址. 例如: tcp://127.0.0.1:1883"
},
"username": {
"type": "string",
"title": "用户名",
},
"password": {
"type": "string",
"title": "密码",
"fieldType": "password"
},
"topic": {
"type": "string",
"title": "主题",
"descripption": "接收数据的主题. 例如: /data/#"
},
"network": {
"type": "object",
"title": "通讯监控参数",
"properties": {
"timeout": {
"title": "通讯超时时间(s)",
"description": "经过多长时间仪表还没有任何数据上传，认定为通讯故障",
"type": "number"
}
}
}
},
"required": ["server", "username", "password", "topic"]
}
}
}
}
驱动配置 中的 network 为固定字段, 用于配置设备通讯超时参数. 即当该设备下的所有数据点在指定时间内没有数据上传, 则认为该设备通讯故障. 该设备的状态会变为 离线.
根据上述配置, 在页面中动态生成的表单如下图所示:
数据点配置说明
数据点 为从设备上采集到的数据列表, 例如设备上有 温度、湿度、电压 等, 这些就是 数据点. 而 数据点配置 就是用来定义和描述数据点信息以及平台在接收到数据后如何处理这些数据.
需要注意的是, 数据点配置 并不是用来定义一个设备有哪些 数据点, 而是用来定义每个数据点的特征, 让驱动程序知道如何去采集这个数据点的数据.
例如: OPC-UA 协议中, 订阅数据时需要提供 NamespaceIndex, Identifier 和 IdentifierType 等信息, 这些信息在服务器中标识唯一的数据点.
此时就需要在 数据点配置 中定义这些信息, 以便驱动程序在采集数据时能够正确的订阅到数据点.
例如设备通过 MQTT 发送 温度 和 湿度 两个数据, 数据格式为 {"T": 25, "H": 50}, 此时需要在平台中定义 温度 和 湿度 两个数据点用来接收这些数据, 并且需要告诉平台 T 为 温度 数据, 单位为 ℃; H 为 湿度 数据, 其单位为 %RH. 所以在 数据点配置 中定义一个 key 用于标识该数据点的数据在设备发送的 json 数据的 key.
而 数据点配置 的 properties 为配置项列表, required 为必填项列表. 如下所示:
{
"driver": {
"properties": {
"settings": {},
"tags": {
"title": "数据点",
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"title": "标识",
"description": "数据点的标识, 用于在数据点列表中唯一标识数据点"
},
"name": {
"type": "string",
"title": "名称",
"description": "数据点的名称"
},
"key": {
"type": "string",
"title": "键",
"description": "数据点在 JSON 对象中的 key"
}
},
"required": ["id", "name", "key"]
}
}
}
}
}
根据上述配置, 在页面中动态生成的表单如下图所示:
红框内为根据 tags 动态生成的内容, 其它内容均为平台自带内容
然后添加两个数据点, 分别为 温度 和 湿度, 并且将 key 设置为 T 和 H, 如下图所示:
id 和 name 为固定配置, 分别为 数据点标识 和 数据点的名称. 而且需要将 id 和 name 设置为必填项.
通过 schema 定义的 数据点配置 只是整个数据点配置中的一部分, 还有一些配置是平台定义的. 例如: 标识、名称、单位以及一些其它处理功能等.
命令配置说明
命令 为平台向设备发送的指令, 例如: 开灯、关灯、重启 等. 而 命令配置 就是用来定义和描述如何向设备发送命令以及发送内容.
例如通过平台向设备发送 重启 控制命令. 以 MQTT 为例, 发送一条命令，需要知道命令发送的 Topic, Qos 和发送内容等信息, 所以在 命令配置 中定义这些信息, 以便驱动程序在发送命令时能够正确的发送命令.
{
"driver": {
"properties": {
"settings": {},
"commands": {
"title": "命令",
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"title": "名称"
},
"ops": {
"type": "array",
"title": "指令",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"title": "主题",
"description": "发送消息的主题. 例如: /cmd/control",
},
"message": {
"type": "string",
"title": "消息",
"description": "发送的消息. 例如: {\"cmd\":\"start\"}",
},
"qos": {
"type": "number",
"title": "QoS",
"description": "消息质量. 0,1,2",
"enum": [0, 1, 2],
"enum_title": ["QoS0", "QoS1", "QoS2"]
},
},
"required": ["name", "message"]
}
}
}
}
}
}
}
}
根据上述配置, 在页面中动态生成的表单如下图所示:
红框内为根据 commands 动态生成的内容, 其它内容均为平台自带内容
然后控制设备重启的命令, 目标 Topic 为 /command, Qos 为 1, 消息内容为 restart, 如下图所示:
完整配置示例
{
"driver": {
"properties": {
"settings": {
"title": "实例配置",
"type": "object",
"properties": {
"server": {
"type": "string",
"title": "服务器地址",
"descripption": "MQTT 服务器地址. 例如: tcp://127.0.0.1:1883"
},
"username": {
"type": "string",
"title": "用户名",
},
"password": {
"type": "string",
"title": "密码",
"fieldType": "password"
},
"topic": {
"type": "string",
"title": "主题",
"descripption": "接收数据的主题. 例如: /data/#"
},
"network": {
"type": "object",
"title": "通讯监控参数",
"properties": {
"timeout": {
"title": "通讯超时时间(s)",
"description": "经过多长时间仪表还没有任何数据上传，认定为通讯故障",
"type": "number"
}
}
}
},
"required": ["server", "username", "password", "topic"]
},
"tags": {
"title": "数据点",
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"title": "标识",
"description": "数据点的标识, 用于在数据点列表中唯一标识数据点"
},
"name": {
"type": "string",
"title": "名称",
"description": "数据点的名称"
},
"key": {
"type": "string",
"title": "键",
"description": "数据点在 JSON 对象中的 key"
}
},
"required": ["id", "name", "key"]
}
},
"commands": {
"title": "命令",
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"title": "名称"
},
"ops": {
"type": "array",
"title": "指令",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"title": "主题",
"description": "发送消息的主题. 例如: /cmd/control",
},
"message": {
"type": "string",
"title": "消息",
"description": "发送的消息. 例如: {\"cmd\":\"start\"}",
},
"qos": {
"type": "number",
"title": "QoS",
"description": "消息质量. 0,1,2",
"enum": [0, 1, 2],
"enum_title": ["QoS0", "QoS1", "QoS2"]
},
},
"required": ["name", "message"]
}
}
}
}
}
}
},
"model": {},
"device": {},
}