版本: 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 操作步骤

1. 进入 「设备类」 列表页，点击 「新建设备类」（如图 2）。

2. 在弹出的对话框中，按下表填写各字段（如图 3）：

   字段	是否必填	示例	说明
   「设备类 ID」	是	dcsPoint	设备类唯一标识，英文/数字
   「设备类名称」	是	DCS 点位	业务含义名称
   「标准化名称」	是	dcs_point	按统一规则命名，对应数仓字段
   「通讯协议」	是	OPCDA	下拉选择 2 导入协议文件 中上传的协议，或 API / MQTT
   「设备通讯类型」	是	直连设备	直连设备 / 网关子设备，按协议说明文档为准
   「时间格式」	否	yyyy-MM-dd HH:mm:ss	按《项目数据对接文档》填写
   「jsonQuery」	否	$.info[*]	API / MQTT 推送模式需填写，通常指向数据数组节点

3. 点击 「确认」 完成创建，新建的设备类出现在列表中。

💡 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 自动生成（如图 4）。
2. 仅当需要微调时，在编辑器内修改后点击 「保存」（如图 5）。
3. 需备份时点击 「导出脚本」；需回退初始状态时点击 「重置脚本」。

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

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

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

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
}

对每个需要入库、展示或上报的字段，逐条执行以下步骤：

1. 切换至 「物模型」 页签，点击 「添加属性」（如图 6）。

2. 在弹出的对话框中，按下表填写各字段（如图 7）：

   字段	是否必填	示例	说明
   「属性标识」	是	DDM.SIS.0DCS_00BHT03GT001XQ001	必须与 JSON 字段名（或脚本最终输出的 Key）一致
   「属性名称」	是	主冷却水泵房变压器A高压断路器高压侧电流	中文可读名称，以《设备点表资料》为准
   「标准化名称」	是	m_001t@20260119	格式为 标准化字段名@PID，详见 6.3 标准化名称与 PID
   「读写模式」	是	只读	仅采集选 「只读」；涉及下控选 「读写」
   「数据类型」	是	浮点	浮点 / 整数 / 字符串 / 布尔 / 时间
   「单位」	否	A	按字段业务属性填写，如 A、℃、kW
   「精度」	否	2	小数位数
   「范围」	否	0–100	取值范围
   「数据上报公式」	否	value * 0.1	需要平台侧计算后上报时配置，参考 计算公式配置说明
   「采集时间字段」	否	DDM.SIS.0DCS_00BHT03GT001XQ001_time	当数据模型含 XXX_time 时成对配置，详见 6.4 采集时间字段成对配置

3. 点击 「确认」 完成添加，属性出现在列表中（如图 8）。

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 操作步骤

1. 进入 「设备」 列表页，点击 「新增设备」（如图 9）。

2. 在弹出的对话框中选择对应设备类，按下表填写各字段（如图 10）：

   字段	是否必填	示例	说明
   「设备标识」	是	DCS-POINT-01	取值规则以协议说明文档为准；推送协议下通常为对接文档定义的「设备唯一标识字段」值
   「设备名称」	是	主冷却水泵房-DCS 点位	中文名称，建议包含位置 / 楼栋 / 楼层 / 房间 / 系统或回路等信息
   「标准化名称（PID）」	是	20260119	归属平台 / 系统的唯一标识，需与属性侧 @PID 保持一致
   「通讯类型 / 协议」	是	OPCDA	与设备类保持一致
   「位置 / 部门」	否	主冷却水泵房	便于后续检索与运维

3. 点击 「确认」 完成添加，设备出现在列表中（如图 11）。

⚠️ 「设备标识」 取值以协议说明文档为准。不同协议对设备标识的含义不同（推送协议通常为报文中的唯一标识字段值；直连协议可能为通讯地址、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），与脚本输出保持一一对应。