面向用户: 实施工程师 / 项目经理 版本: viSCADA 1.8.0 及以上

本手册指导实施人员完成 viSCADA 平台设备类的完整配置流程,涵盖协议导入、设备类创建、技术参数、脚本查看、属性定义与设备实例添加。按本手册操作完成后,设备数据可正常上报、入库并用于后续展示与分析。

本手册适用于单设备推送模式:一条上报报文中包含一个设备的多个属性字段(如 cumulatedFlow、inTemp 等),属性标识与 JSON 字段一一对应。

1 整体流程

设备类配置的完整链路由「协议导入 → 设备类创建 → 技术参数(可选)→ 脚本查看 → 属性配置 → 设备实例」六个环节构成,任一环节失败都会导致数据无法落库。

图 1 设备类配置整体流程

2 导入协议文件

协议脚本通过 YAML 协议文件导入,由平台自动生成设备类可用的输入脚本。

操作路径: 「后台管理」 → 「协议管理」

操作步骤:

1. 进入 「协议管理」 页面,点击 「新增协议」。
2. 填写 「协议名称」 并上传 YAML 协议文件。
3. 点击 「添加协议」 完成提交,协议将在后续创建设备类时的 「通讯协议」 下拉中可选。

📌 YAML 协议文件由产品/研发方提供,详细导入流程与截图参见 《viSCADA YAML 协议文件导入与设备类创建操作说明》 。

💡 若本项目使用 API / MQTT 通讯方式且由《项目数据对接文档》直接提供脚本,可跳过本章,在 5 脚本查看与微调 中直接粘贴脚本。

3 创建设备类并关联协议

3.1 操作入口

操作路径: 「设备管控」 → 「设备类」 → 「新建设备类」

图 2 设备类列表页

图 3 新建设备类弹窗

3.2 字段说明

💡 jsonQuery 常见写法如 $.info[*],用于将上报报文中的数组展开为独立的数据条目。YAML 直连协议通常无需填写。

4 配置技术参数

📌 是否需要配置、配置哪些参数,以协议说明文档或《项目数据对接文档》为准。YAML 直连协议(如 OPCDA、Modbus 等)通常需配置通讯地址类技术参数;API / MQTT 推送模式一般不需要。

操作路径: 设备类详情页 → 「技术参数编辑」 模块

4.1 操作步骤

1. 点击 「+ 新增项」。
2. 在 「参数名称」 下拉中选择对接文档指定的参数。
3. 在 「参数值」 中按对接文档要求的格式填写。
4. 格式校验通过后点击 「确认」。

4.2 示例:OPCDA 协议的 address 参数

以 OPCDA 协议为例,其协议文件要求配置 address 参数:

⚠️ 配置 OPCDA 的 address 时,参数值仅填写 IP/域名及端口(如 127.0.0.1:4444),切勿携带 http://、https:// 等协议前缀,否则校验不通过。其他协议的参数名称与格式约束以对接文档为准。

5 脚本查看与微调

📌 YAML 协议文件导入后,平台会自动生成对应脚本,通常无需人工编辑。本章仅适用于:① API / MQTT 推送模式需粘贴《项目数据对接文档》提供的脚本;② 需要查看或微调已生成脚本的场景。

5.1 脚本类型

5.2 按协议配置脚本

API 协议:

1. 进入设备类详情页 → 「脚本」 页签 → 点击 「新增脚本」。
2. 将《项目数据对接文档》提供的脚本粘贴替换。
3. 点击 「保存」 完成配置。

MQTT 协议:

1. 进入设备类详情页 → 「脚本」 页签。
2. 找到 [[inputs.mqtt_consumer]] 节点 → 点击 「编辑」。
3. 将《项目数据对接文档》提供的脚本粘贴替换。
4. 点击 「保存」 完成配置。

YAML 导入协议(OPCDA / Modbus 等):

1. 进入设备类详情页 → 「脚本」 页签,确认脚本已由 YAML 自动生成。
2. 仅当需要微调时,在编辑器内修改后点击 「保存」。
3. 需备份时点击 「导出脚本」;需回退初始状态时点击 「重置脚本」。

图 4 输入脚本编辑页 - 列表视图

图 5 输入脚本编辑页 - 详情视图

⚠️ 脚本修改会影响该设备类下所有设备的解析逻辑,修改前请先点击 「导出脚本」 备份。

5.3 脚本配置检查清单

脚本配置完成后,请逐项核对:

• 能正确定位数据模型(jsonQuery 指向正确的数据节点)
• 能正确取到「设备唯一标识字段」(如 addressCode)
• 能正确识别属性字段(如 cumulatedFlow、flowRate),详见《项目数据对接文档》

6 属性配置

6.1 操作入口

操作路径: 设备类详情页 → 「物模型」 页签 → 「添加属性」

图 6 物模型属性列表

图 7 新增属性页面

6.2 字段说明

对每个需要入库、展示或上报的字段,按下表规则填写:

6.3 属性字段梳理模板

建议在配置前,先以表格形式梳理所有字段:

💡 大多数场景下 「属性标识」 与 JSON 字段名一致,因此省略「JSON 字段」列以避免冗余。若脚本中对字段做了重命名,则 「属性标识」 应以脚本最终输出的键名为准。

7 设备实例添加

7.1 操作入口

操作路径: 「设备管控」 → 「设备」 → 「新增设备」 → 选择对应设备类

图 8 设备列表页 - 新增设备入口

图 9 新增设备表单

7.2 字段说明

⚠️ 「设备标识」 取值以协议说明文档为准。不同协议对设备标识的含义不同(推送协议通常为报文中的唯一标识字段值;直连协议可能为通讯地址、NodeId 等),填写前请严格比对协议文档,注意大小写、空格、前后缀完全一致。

⚠️ PID 唯一性要求:同一系统内 「标准化名称(PID)」 必须唯一,不同设备类下也不建议复用同一 PID,除非项目已明确允许并完成冲突验证。

8 常见问题

9 附录:数据模型示例

以下为典型的上报 JSON 报文示例,用于辅助理解 jsonQuery 与字段配置:

{
  "msgType": "PUSH_METER_DATA",
  "token": "XXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "info": [
    {
      "addressCode": "YH001",
      "deviceSn": "0088001001",
      "reportTime": "2025-12-10 16:00:00",
      "collectTime": "2025-12-10 16:00:01",
      "cumulatedFlow": "1565.30",
      "inTemp": "25.56"
    }
  ]
}

对应配置: