07 YAML协议编写导入 | EdgeAgent Docs

面向用户: 实施工程师 / 研发人员

本手册规范 viSCADA 平台对接 YAML 文件的编写、修改与导入全流程,指导实施人员按统一格式完成协议文件定义,并通过平台界面导入协议、创建设备类,最终实现设备接入。

1 文档目的

本手册旨在确保以下三项核心要求落地:

协议基础信息 + 技术参数(attributes)配置完整,符合校验规则
控制下发(MQTT/HTTP)配置精准,指令下发与结果校验正常
采集与处理(telegraf_scripts)脚本规范,数据采集、转换、转发全链路通畅

2 适用范围

viSCADA 平台的协议文件编写与协议模板更新场景。

3 参考资料

资料名称	用途	访问链接
YAML 说明文档	整体格式与基础配置说明	http://mrdoc.iheatingos.com/doc/11422/
attributes 说明	技术参数定义与校验规则详解	http://mrdoc.iheatingos.com/doc/11423/
telegraf 脚本配置说明	`function_type` / `telegraf_type` 定义	http://mrdoc.iheatingos.com/doc/11588

4 YAML 文件结构与配置

一个完整的 YAML 协议文件由四个模块组成,所有模块均为必填项:

图 1 YAML 协议文件的四个模块

4.1 协议基本信息

4.1.1 作用

定义协议标识、版本、适配的设备类型,确保平台能精准匹配协议。

4.1.2 关键配置项

配置项	说明	是否可改(内置协议)
`version`	协议版本,遵循「主版本.次版本」命名	✅
`name`	协议唯一标识	❌
`display_name`	协议显示名称	❌
`content`	协议说明,用于描述对接场景、设备厂商等	✅
`device_types`	支持的设备类型(多选,数字标识)	✅

device_types 支持的值:

数字	对应类型
1	直连设备
2	网关设备
3	网关子设备

4.1.3 操作步骤

填写协议版本(如 1.0)。
配置协议标识 name(唯一值,内置协议不可修改)。
填写显示名称 display_name(直观描述协议用途,内置协议不可修改)。
补充协议说明 content(简要说明对接场景、设备厂商等)。
勾选支持的设备类型(多选)。

4.1.4 配置示例


version: 1.0
protocol:
  name: "52"
  display_name: "三河室温采集数据对接(泰德尔v1)"
  content: "对接泰德尔品牌室温采集设备,用于三河项目室温数据采集"
  device_types:
    - 1
    - 2
    - 3

4.2 技术参数(attributes)

4.2.1 作用

定义设备接入时需配置的参数及校验规则,避免非法配置进入平台。

4.2.2 校验规则类型

规则类型	使用场景	`rule_content` 是否必填
`REGEX`	正则表达式校验(如 IP、URL 格式)	✅
`ENUM`	枚举值校验(如布尔开关、固定档位)	✅
`RANGE`	数值范围校验(如端口号 1–65535)	✅
`FOR_MQTT`	从 MQTT 消息体中动态获取	❌
`NONE`	无校验,允许任意值	❌

4.2.3 配置字段

字段	说明	默认值
`name`	参数名称(与设备侧字段一致)必填	——
`content`	参数说明	——
`value_editable`	是否可编辑	`false`
`default_value`	默认值	——
`generic`	是否通用参数	`false`
`required`	是否必填	`false`
`unit`	参数单位	——
`connection_param`	是否为连接参数	`false`
`rule`	校验规则类型必填	——
`rule_content`	校验规则内容(规则为 `REGEX`/`ENUM`/`RANGE` 时必填)	——

⚠️ 连接参数的特殊性:当 connection_param: true 时,该参数会出现在设备详情页的**「参数验证」**入口中,可用于连接预校验。建议将 IP、端口、账号密码等连接相关参数设为连接参数。

连接参数配置效果 图 2 连接参数在设备详情页的参数验证入口

4.2.4 操作步骤

罗列项目所需参数(参考「常见参数」,与设备厂商确认字段名称)。
为每个参数配置 4.2.3 中所列字段。
交叉校验:确保参数类型、校验规则与设备侧要求一致,避免配置冲突。

4.2.5 常见参数列表

参数名	含义
`SN`	设备序列号
`intelligentDeviceFlag`	是否为智能体设备
`intelligentGatewayFlag`	是否为智能体网关
`edgeLinkUrl`	边缘侧连接地址

4.2.6 配置示例


attributes:
  - name: SN
    content: 字符串,智能体设备标识
    value_editable: true
    default_value:
    generic: true
    unit:
    connection_param: false
    required: false
    rule: NONE
    rule_content:
 
  - name: intelligentDeviceFlag
    content: 是否是智能体设备
    value_editable: true
    generic: true
    connection_param: false
    required: false
    rule: ENUM
    rule_content:
      enum:
      - true
      - false
 
  - name: intelligentGatewayFlag
    content: 是否是智能体网关
    value_editable: true
    generic: true
    connection_param: false
    required: false
    rule: ENUM
    rule_content:
      enum:
      - true
      - false
 
  - name: edgeLinkUrl
    content: 边缘侧的连接地址
    value_editable: true
    generic: true
    connection_param: false
    required: false
    rule: REGEX
    rule_content:
      regex: ^(https?://).*

4.3 控制脚本(control_script)

4.3.1 作用

定义平台向设备下发控制指令的模板。

4.3.2 下发方式对比

下发方式	必需配置项	结果校验机制
MQTT	`broker`、`topic`、`qos`、鉴权信息、`body`(含占位符)	通过回调 `topic` 异步关联请求结果
HTTP	`url`、`method`、`headers`、`body`、`timeout`	通过状态码 + 响应体判定,或异步回调

4.3.3 操作步骤

选择下发方式(MQTT / HTTP,二选一或按需同时配置)。
按对应方式填写配置项(占位符需替换为项目实际值)。
配置结果校验规则:
- MQTT:通过回调 topic 关联请求
- HTTP:通过状态码 + 响应体判定

4.3.4 配置示例


control_script: |
  control:
    # 根据下发方式填写对应配置项
    # 详见《设备类详情》→《控制配置》→ info 图标中的变量说明

ℹ️ 控制脚本的完整变量与示例请参考:「设备类详情」→「控制配置」→ info 图标。

4.4 采集与处理脚本(telegraf_scripts)

4.4.1 作用

构建「数据采集 → 处理 → 转发」的流水线。

4.4.2 典型处理环节

HTTP 拉取数据
设备映射、字段改名/复用
补充维度 tag
topic/路径改写(适配网关)
字段标准化、类型转换、计算
拆分/复制生成标准数据流
补全时间字段
清理无效后缀/占位符替换,最终转发

4.4.3 脚本类型与排序规则

类型	`order` 取值	数量限制
输入脚本	`0`(固定)	1 个
处理脚本	`1` ~ `1500`	多个,按 order 升序执行
输出脚本	`10000`(固定)	1 个

4.4.4 数据存储版本

版本	说明
`V1`	默认版本
`V2`	新增对数据表字段类型不一致问题的处理,按需选择

4.4.5 操作步骤

配置「输入」脚本(order 固定为 0,负责数据采集)。
按需新增处理脚本(order 介于 1–1500,如设备名称匹配、字段转换等)。
配置「输出」脚本(order 固定为 10000,负责最终转发)。
选择数据存储版本(V1 默认,V2 用于处理数据表字段类型不一致问题)。

4.4.6 输入脚本示例


- name: "输入"
  order: 0
  function_type: 1
  telegraf_types:
    - 1
  data_storage_version: V1
  content: |
    [[inputs.http]]
      interval = "5s"
      timeout = "100s"
      precision = "1s"
      collection_jitter = "20s"
      name_override = "${TEMPLATE_NAME}"
      urls = [
        <#assign parts = DEVICE_NAME_LIST_WITH_CHARACTER?split(',')>
        <#list parts as part>
            <#assign device_name = part?remove_beginning('\\"')?remove_ending('\\"')>
            "http://nodered-service.dev.svc.cluster.local:1880/get/data/device?device_name=${device_name}"<#if part?has_next>,</#if>
        </#list>
      ]
      method = "GET"
      data_format = "json"
      json_query = "data"
      json_string_fields = ["*"]
      tag_keys = ["device_name"]

4.4.7 处理脚本示例(设备名称匹配)


- name: "设备名称匹配"
  order: 55
  function_type: 11
  telegraf_types:
    - 1
  data_storage_version: V1
  content: |
    [[processors.enum]]
        namepass= ["${TEMPLATE_NAME}${DEVICE_TYPE}"]
        alias = "${TEMPLATE_NAME}${DEVICE_TYPE}@marking"
        order = ${order@55}
        [[processors.enum.mapping]]
            tag = "device_name"
            dest ="device_id"
            [processors.enum.mapping.value_mappings]
                ${DEVICE_NAME_TO_DEVICE_ID_MAP}

ℹ️ function_type 与 telegraf_types 的完整取值与含义,参考 telegraf 脚本配置说明。

5 协议导入与设备类创建流程

5.1 打开协议管理

操作路径:后台管理 → 对接配置 → 协议管理

功能入口: 可查看已存在协议列表,或点击**「+新增协议」**进入导入页面。

协议管理页面 图 3 协议管理主页面

5.2 新增协议

操作步骤:

点击**「+新增协议」**按钮。
上传编写/修改完成的 YAML 文件(支持 .yaml / .yml 格式)。
填写核心信息(上传文件后自动识别,可手动修正):

字段对应 YAML 配置项
协议名称 display_name
协议版本 version
协议描述 content

字段	对应 YAML 配置项
协议名称	`display_name`
协议版本	`version`
协议描述	`content`

新增协议弹窗 图 4 新增协议上传界面

5.3 文件导入与校验

系统会在上传后自动进行合法性校验:

校验结果	后续动作
✅ 成功	点击「添加协议」完成导入,协议状态变为「启用」
❌ 失败	根据系统提示修正 YAML(如格式错误、参数缺失),重新上传

协议导入校验结果 图 5 协议导入校验结果

5.4 创建设备类并关联协议

将已导入的协议与设备类绑定,实现设备接入。

操作路径:后台管理 → 设备管控 → 设备类 → 新增设备类

操作步骤:

点击**「新增设备类」**按钮。

填写设备类信息:

字段	说明	必填
设备类名称	按项目规范命名(如「三河-泰德尔室温采集设备」)	✅
关联协议	选择已导入的目标协议(如「三河室温采集数据对接(泰德尔v1)」)	✅
设备类描述	简要说明设备类用途	⭕
所属组织	按项目需求选择	⭕

点击**「保存」**完成配置。

操作结果:

设备类创建完成,已与目标协议绑定
可用于后续设备接入配置