文档信息

修订记录

1 文档说明

1.1 文档目的

本文档指导实施工程师与运维人员在 viSCADA 平台中规范完成基于特定协议(HTTP、MQTT、Kafka、数据库等)的 YAML 配置,涵盖协议脚本录入、设备类关联、技术参数配置等核心环节。

完成本文档的学习后,您应能独立完成:

• 新增基于特定协议的数据采集与控制脚本
• 创建设备类并正确关联对应协议
• 配置设备通讯地址等核心技术参数
• 校验配置的正确性与生效状态
• 快速定位并排查常见配置问题

ℹ️ 版本说明:本版本示例与截图均以 HTTP 协议为蓝本,其他协议(MQTT、Kafka、数据库)的脚本细节将在后续版本中补充,但整体操作流程通用。

1.2 适用设备与业务

本文档适用于通过 HTTP、MQTT、Kafka、数据库等接口接入 viSCADA 平台,并需实现以下业务功能的设备:

• 设备实时数据采集
• 设备控制指令下发

1.3 前置条件

在开始配置前,请确认已满足以下条件:

1. 已获取 viSCADA 平台的登录与操作权限。
2. 已明确目标设备对外提供服务的协议类型。
3. 已获取设备准确有效的通讯地址(如 IP 地址、域名及端口号)。
4. 已确认 viSCADA 平台与目标设备之间网络互通,相关通讯端口正常开放。
5. (HTTP 协议专属) 已确认设备接口支持以下交互方式:
   • 使用 GET 请求获取实时数据
   • 使用 PUT 请求下发控制指令

2 整体配置流程

3 协议脚本说明

3.1 数据采集脚本

该脚本用于平台按固定周期从设备端拉取数据。

[[inputs.http]]
  interval = "60s"
  name_override = "${TEMPLATE_NAME}"
  urls = [
      "http://${attribute.address}/tags"
  ]
  method = "GET"
  insecure_skip_verify = true
  timeout = "300s"
  data_format = "json"
  json_query = ""
  json_timezone = "Asia/Shanghai"
  json_string_fields = [${STRING_FIELD}]

参数说明:

占位符说明:

💡 配置建议:除 interval 和 timeout 外,其余参数建议保持默认,不推荐随意修改。

3.2 控制脚本

该脚本用于平台向设备端发送控制指令。

control:
  - async: false
    carrier: "http"
    url: "http://${attribute.address}/tag/${tslProperty.name?url('UTF-8')}"
    method: "put"
    headers:
        Content-Type: "application/json"
    body: "${TARGET_VALUE}"
    timeout: 15000
    successStatusCodes:
        - 200
    successResponseBody:
        - "updated"

参数说明:

占位符说明:

⚠️ 严禁修改:successStatusCodes 和 successResponseBody 是平台判定控制指令是否执行成功的核心依据,修改后将导致平台误判设备状态。

4 YAML 技术参数配置

在构建 YAML 协议文件时,必须定义 attributes 节点。其中 address(设备通讯地址)为必填技术参数,用于配置目标设备的 IP 地址或域名(可含端口号)。

4.1 标准配置示例

attributes:
  - name: address
    content: "IP地址或者域名。示例: localhost:4444/127.0.0.1:4444"
    value_editable: true
    default_value:
    generic: false
    unit:
    required: true
    rule: REGEX
    rule_content:
        regex: ^(?:(?:(?:25[0-5]|2[0-4]\d|1?\d?\d)\.){3}(?:25[0-5]|2[0-4]\d|1?\d?\d)|(?=.{1,253}$)(?:[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?\.)+[A-Za-z]{2,})(?::(?:6553[0-5]|655[0-2]\d|65[0-4]\d{2}|6[0-4]\d{3}|[1-5]\d{4}|[1-9]\d{0,3}))?$

4.2 关键参数说明

4.3 address 填写规范

填写 address 时,仅录入设备的实际通讯地址,切勿添加 http:// 等协议前缀。

ℹ️ 平台保存时会调用正则表达式对地址格式自动校验。格式不合规时页面将拦截并提示,无法保存。

5 平台操作流程

5.1 新增协议脚本

操作路径:设备管控 → 协议管理

图 1 协议管理 - 新增脚本页面

操作步骤:

1. 登录 viSCADA 平台。
2. 在左侧导航栏依次点击**「设备管控」** → 「协议管理」。
3. 点击**「新增脚本」**按钮。
4. 填写脚本基础信息(例如将协议名称命名为 OPCAD)。
5. 将 3.1 数据采集脚本 与 3.2 控制脚本 分别复制并粘贴至对应编辑区域。
6. 检查脚本内容,确认所有 ${XXX} 占位符均完整保留。
7. 点击**「保存」**提交。

操作结果:

• 协议脚本成功入库
• 在后续设备类创建流程中,下拉列表内可选择该协议

5.2 新增设备类并关联协议

操作路径:设备管控 → 设备类

图 2 设备类 - 新增页面

操作步骤:

1. 在左侧导航栏依次点击**「设备管控」** → 「设备类」。
2. 点击**「新增设备类」**按钮。
3. 根据页面提示填写以下基础信息:
   • 设备类 ID
   • 设备类名称
   • 标准化名称
4. 在**「通讯协议」**下拉菜单中选择 5.1 新增协议脚本 中新增的协议(如 OPCAD)。
5. 将**「设备通讯类型」配置为「直连设备」**。
6. 点击**「保存」**提交。

操作结果:

• 成功创建新的设备类
• 新设备类已与指定的通讯协议完成绑定

5.3 查看、导出或编辑设备类脚本

操作路径:目标设备类详情页 →「脚本」标签页

图 3 设备类 - 脚本标签页

操作步骤:

1. 点击进入目标设备类的详情页。

2. 切换至顶部的**「脚本」**标签页,可直接查看当前设备类关联的协议脚本内容。

3. 根据需要执行以下操作之一:

   场景	操作	结果
   备份脚本	点击**「导出脚本」**	下载当前脚本文件
   修改脚本	编辑器内直接修改后点击**「保存」**	修改立即生效
   回退异常	点击**「重置脚本」**	恢复为协议初始配置

操作结果:

• 实现对当前设备类专属脚本的可视化管理、备份与热更新

5.4 配置技术参数 address

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

图 4 设备类 - 技术参数编辑模块

操作步骤:

1. 点击进入目标设备类的详情页。
2. 定位至**「技术参数编辑」**模块。
3. 点击**「+ 新增项」**按钮。
4. 在弹出的参数名称选项中选择 address。
5. 在参数值输入框中填写目标设备的通讯地址(例如 127.0.0.1:4444)。
6. 系统自动校验输入格式的合法性。
7. 校验通过后点击**「保存」**提交配置。

操作结果:

• 设备类的核心技术参数配置完毕
• address 参数正式生效,设备具备基本的通讯寻址能力

6 配置检查清单

为保障设备顺利接入,建议在配置完成后按下表逐项核对:

• 协议脚本已成功新增并保存
• 数据采集脚本已完整粘贴
• 控制脚本已完整粘贴
• 脚本内所有 ${XXX} 占位符均未被改动
• 设备类已成功创建并绑定了正确的协议
• address 技术参数已完成添加与配置
• address 格式校验通过(无协议前缀)
• 所有流程中的修改均已点击「保存」确认

7 注意事项

8 常见问题排查

若配置完成后设备仍离线或无法受控,请按以下链路逐级排查。

8.1 分层排查清单

8.2 控制下发失败专项排查

若设备数据采集正常,但控制下发失败,请通过抓包或测试工具(如 Postman)确认设备实际接口响应是否同时满足:

• HTTP 响应状态码为 200
• 响应体(Body)内容中包含 "updated" 关键字

ℹ️ 两个条件必须同时满足,缺一不可。

9 附录

9.1 常用地址配置参考

✅ 合法示例:

❌ 错误示例:

ℹ️ 完整的脚本与 YAML 技术参数模板已在 3 协议脚本说明 与 4 YAML 技术参数配置 中提供,请直接参考对应章节,无需在附录重复列出。