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

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

本手册适用于单属性推送模式:一条上报报文中的每个字段都是独立的属性点(如 DDM.SIS.0DCS_00BHT03GT001XQ001),经脚本处理后转为扁平 Key:Value 结构,「属性标识」 即 Key。

💡 若项目为单设备推送模式(一条报文包含一个设备的多个属性字段),请参考 《viSCADA 设备类配置与设备添加操作手册(单设备推送模式)》 。

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 指向正确的数据节点)
• 能正确将数据模型映射为 Key:Value 结构
• 能正确识别属性字段(如 DDM.SIS.0DCS_00BHT03GT001XQ001),详见《项目数据对接文档》

6 属性配置

6.1 操作入口

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

图 6 物模型属性列表

图 7 新增属性页面

6.2 字段说明

脚本处理后的典型数据结构为 Key:Value,其中 Key 即 「属性标识」:

{
    "DDM.SIS.0DCS_00BHT03GT001XQ001": 96.66479555734657,
    "DDM.SIS.0DCS_00BHT03GT001XQ001_time": 1635320374000,
    "DDM.SIS.0DCS_00BHT03GT001XQ002": 25.33885302270709,
    "DDM.SIS.0DCS_00BHT03GT001XQ003": 7.804157681671977
}

对每个需要入库、展示或上报的字段,按下表逐条配置:

6.3 标准化名称与 PID

标准化名称格式为 标准化字段名@PID,由两部分组成:

完整示例: m_001t@20260119 —— 含义:将该属性映射到 PID 为 20260119 的设备上的标准字段 m_001t。

⚠️ PID 唯一性要求:同一 PID 下各属性的标准化名称(字段名@PID)必须唯一,否则会导致跨属性映射冲突。同一 PID 可被不同设备类型、不同设备复用。

6.4 采集时间字段成对配置

当数据模型同时包含主值字段与对应的 _time 时间字段时,建议「主值字段 + 时间字段」成对配置:

💡 命名规则: 时间字段的标准化名称 = 主标准化字段名 + _time,@PID 保持一致。

6.5 配置效果

图 8 属性配置完成后的效果图

6.6 属性字段梳理模板

建议在配置前先以表格形式梳理所有字段,再逐条录入平台:

7 设备实例添加

7.1 操作入口

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

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

图 10 新增设备表单

7.2 字段说明

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

⚠️ 设备实例的 PID 必须与属性配置中标准化名称的 @PID 完全一致,否则数据将无法落到目标设备。

7.3 配置效果

图 11 设备实例配置效果

8 常见问题

9 附录:数据模型示例

9.1 原始数据模型

平台接收到的原始上报报文结构如下(为节省篇幅,仅列举 2 条,实际场景为多条并列):

[
    {
        "Key": "DDM.SIS.0DCS_00BHT03GT001XQ001",
        "Value": {
            "ExpandName": "0DCS_00BHT03GT001XQ001",
            "PointDescribe": "主冷却水泵房变压器A高压断路器高压侧电流",
            "PointName": "DDM.SIS.0DCS_00BHT03GT001XQ001",
            "PointTime": "2021-10-27 15:39:34",
            "PointUnit": "A",
            "PointValue": 96.66479555734657
        }
    },
    {
        "Key": "DDM.SIS.0DCS_00BHT03GT001XQ002",
        "Value": {
            "ExpandName": "0DCS_00BHT03GT001XQ002",
            "PointDescribe": "主冷却水泵房变压器A有功功率",
            "PointName": "DDM.SIS.0DCS_00BHT03GT001XQ002",
            "PointTime": "2021-10-27 15:39:34",
            "PointUnit": "KW",
            "PointValue": 25.33885302270709
        }
    }
]

9.2 脚本处理后的 Key:Value 结构

经输入脚本解析后,数据转换为平台可直接识别的扁平 Key:Value 结构:

{
    "DDM.SIS.0DCS_00BHT03GT001XQ001": 96.66479555734657,
    "DDM.SIS.0DCS_00BHT03GT001XQ002": 25.33885302270709,
    "DDM.SIS.0DCS_00BHT03GT001XQ003": 7.804157681671977
}

ℹ️ 属性配置时,「属性标识」 需直接使用左侧的 Key 值(如 DDM.SIS.0DCS_00BHT03GT001XQ001),与脚本输出保持一一对应。