Skip to content

驱动配置 ​

drivers 段定义南向(southbound)采集驱动。每个驱动实例连接一台工业设备,按标签列表周期性采集数据点。

yaml
drivers:
  - name: plc-modbus
    type: modbus-tcp
    settings:
      host: 192.168.1.100
      port: 502
      slave-id: 1
      timeout: 3s
      retry: 3
    tags:
      - name: temperature
        address: "40001"
        type: float32
        group: sensors
        interval: 1s
        deadband: 0.2

驱动通用字段 ​

每个驱动实例共享以下顶层字段,settings 的具体内容随 type 不同而变化。

字段类型必填默认值说明
namestring是—驱动实例名称,全局唯一,用于规则匹配与 API 引用
typestring是—驱动协议类型,见下表
settingsobject是—协议专属连接参数
tagsarray是 ¹—标签(数据点)采集定义列表
tags-filestring否—从外部 YAML 文件加载标签列表,适合数百以上采集点场景 ¹
tags-intervalduration否—tags-file 的热重载间隔(如 30s),为空则仅启动时加载一次

¹ tags 与 tags-file 至少配置其一;两者同时配置时,文件标签在前,内联标签在后追加,标签名在两者间必须唯一。

支持的驱动类型:

type协议典型设备
modbus-tcpModbus TCPPLC、传感器网关、变频器
modbus-rtuModbus RTU(串口)RS-485 传感器、串口设备
modbus-rtuovertcpModbus RTU over TCP串口转以太网网关
modbus-udpModbus TCP over UDPUDP 设备
modbus-rtuoverudpModbus RTU over UDPUDP 上的 RTU 帧
modbus-tlsModbus TCP over TLS(mTLS)加密通信 PLC
s7Siemens S7 协议S7-200 / S7-300 / S7-400 / S7-1200 / S7-1500 PLC
opcuaOPC UA ClientSCADA、MES、OPC 服务器

INFO

驱动实例在核心启动时按列表顺序初始化。初始化失败(如必填的 host 缺失、地址无法解析、证书文件不可读)会导致整个引擎启动失败并回滚已启动的组件——核心以 fail-fast 拒绝带病运行。设备连接失败不阻塞启动:驱动转入 connecting 状态并在后台按重连参数重试。


Modbus TCP (modbus-tcp) ​

Modbus TCP 是工业现场最常见的以太网协议,CoreC 通过 TCP 502 端口与从站通信。

yaml
- name: plc-modbus
  type: modbus-tcp
  settings:
    host: 192.168.1.100
    port: 502
    slave-id: 1
    timeout: 3s
    retry: 3

settings 字段 ​

字段类型必填默认值说明
hoststring是—设备 IP 地址或主机名
portint否502TCP 端口,Modbus 标准端口为 502
slave-idint否1从站地址(Modbus unit id)
timeoutduration否3s单次读写超时时间
retryint否3通信失败后的重试次数
reconnect-intervalduration否2s重连初始退避间隔
reconnect-max-intervalduration否30s重连退避上限
max-reconnect-failuresint否20断路器阈值,连续失败达到此值后将重连间隔提升至 5 分钟低频重试

地址格式 ​

Modbus 地址采用数字字符串,前缀决定功能码:

地址前缀区域功能码示例
0xxxx线圈(Coil)FC01 读 / FC05 写"00001"
1xxxx离散输入(Discrete Input)FC02 读(只读)"10001"
3xxxx输入寄存器(Input Register)FC04 读(只读)"30001"
4xxxx保持寄存器(Holding Register)FC03 读 / FC06 写 16 位 / FC16 写 32 位(跨寄存器)"40001"

写入只使用单点功能码:线圈用 FC05,保持寄存器 16 位用 FC06,32 位类型(uint32/int32)跨两个寄存器用 FC16;离散输入与输入寄存器为只读区,写入直接报错。

TIP

地址从 1 开始计数。"40001" 对应保持寄存器第 0 号(PLC 内部偏移 0),"40003" 对应偏移 2。多字节类型(如 float32)会自动跨寄存器读取。


Modbus RTU (modbus-rtu) ​

Modbus RTU 通过串口(如 RS-485)与从站通信,适用于串口传感器与现场设备。

yaml
- name: sensor-rtu
  type: modbus-rtu
  settings:
    serial-device: /dev/ttyUSB0
    baud-rate: 9600
    data-bits: 8
    parity: none
    stop-bits: 1
    slave-id: 1
    timeout: 3s
    retry: 3

settings 字段 ​

字段类型必填默认值说明
serial-devicestring是—串口设备路径,如 /dev/ttyUSB0(Linux)或 COM3(Windows)
baud-rateint否9600波特率
data-bitsint否8数据位,7 或 8
paritystring否none校验位:none、even、odd;无法识别的取值导致驱动初始化失败
stop-bitsint否0(自动)停止位,1 或 2,0 表示由库按校验位自动选择
slave-idint否1从站地址(Modbus unit id)
timeoutduration否3s单次读写超时时间
retryint否3通信失败后的重试次数
reconnect-intervalduration否2s重连初始退避间隔
reconnect-max-intervalduration否30s重连退避上限
max-reconnect-failuresint否20断路器阈值,连续失败达到此值后将重连间隔提升至 5 分钟低频重试

地址格式与 Modbus TCP 相同。


Modbus RTU over TCP (modbus-rtuovertcp) ​

通过 TCP 连接传输 RTU 帧,常见于串口转以太网网关。

yaml
- name: rtu-gateway
  type: modbus-rtuovertcp
  settings:
    host: 192.168.1.80
    port: 502
    slave-id: 1
    timeout: 3s

settings 字段 ​

字段类型必填默认值说明
hoststring是—网关 IP 地址
portint否502TCP 端口
slave-idint否1从站地址
timeoutduration否3s单次读写超时时间
retryint否3通信失败后的重试次数
reconnect-intervalduration否2s重连初始退避间隔
reconnect-max-intervalduration否30s重连退避上限
max-reconnect-failuresint否20断路器阈值,连续失败达到此值后将重连间隔提升至 5 分钟低频重试

Modbus UDP (modbus-udp) ​

通过 UDP 传输 Modbus TCP 帧。

yaml
- name: modbus-udp
  type: modbus-udp
  settings:
    host: 192.168.1.90
    port: 502
    slave-id: 1
    timeout: 3s

settings 字段 ​

字段类型必填默认值说明
hoststring是—设备 IP 地址
portint否502UDP 端口
slave-idint否1从站地址
timeoutduration否3s单次读写超时时间
retryint否3通信失败后的重试次数
reconnect-intervalduration否2s重连初始退避间隔
reconnect-max-intervalduration否30s重连退避上限
max-reconnect-failuresint否20断路器阈值,连续失败达到此值后将重连间隔提升至 5 分钟低频重试

Modbus RTU over UDP (modbus-rtuoverudp) ​

通过 UDP 传输 RTU 帧。

yaml
- name: rtu-udp
  type: modbus-rtuoverudp
  settings:
    host: 192.168.1.91
    port: 502
    slave-id: 1
    timeout: 3s

settings 字段 ​

字段类型必填默认值说明
hoststring是—设备 IP 地址
portint否502UDP 端口
slave-idint否1从站地址
timeoutduration否3s单次读写超时时间
retryint否3通信失败后的重试次数
reconnect-intervalduration否2s重连初始退避间隔
reconnect-max-intervalduration否30s重连退避上限
max-reconnect-failuresint否20断路器阈值,连续失败达到此值后将重连间隔提升至 5 分钟低频重试

Modbus TLS (modbus-tls) ​

Modbus TCP over TLS,需要双向 TLS(mTLS)证书。

yaml
- name: modbus-tls
  type: modbus-tls
  settings:
    host: 192.168.1.100
    port: 802
    cert-file: /etc/corec/certs/client.crt
    key-file: /etc/corec/certs/client.key
    ca-file: /etc/corec/certs/ca.crt
    slave-id: 1
    timeout: 3s

settings 字段 ​

字段类型必填默认值说明
hoststring是—设备 IP 地址
portint否502TCP 端口(Modbus TLS 常用 802)
cert-filestring是—客户端证书 PEM 文件路径
key-filestring是—客户端私钥 PEM 文件路径
ca-filestring是—CA / 服务端证书 PEM 文件路径
slave-idint否1从站地址
timeoutduration否3s单次读写超时时间
retryint否3通信失败后的重试次数
reconnect-intervalduration否2s重连初始退避间隔
reconnect-max-intervalduration否30s重连退避上限
max-reconnect-failuresint否20断路器阈值,连续失败达到此值后将重连间隔提升至 5 分钟低频重试

Siemens S7 (s7) ​

通过 ISO-on-TCP(102 端口)连接西门子 S7 系列 PLC,支持 S7-200、S7-300、S7-400、S7-1200、S7-1500。

yaml
- name: siemens-s7-300
  type: s7
  settings:
    host: 192.168.1.200
    port: 102
    rack: 0
    slot: 2
    timeout: 5s

settings 字段 ​

字段类型必填默认值说明
hoststring是—PLC IP 地址
portint否102ISO-on-TCP 端口,通常无需修改
rackint否0机架号,标准机架为 0
slotint否2槽号,见下表
timeoutduration否5s单次读写超时时间
idle-timeoutduration否60s连接空闲超时时间
reconnect-intervalduration否2s重连初始退避间隔
reconnect-max-intervalduration否30s重连退避上限
max-reconnect-failuresint否20断路器阈值,连续失败达到此值后将重连间隔提升至 5 分钟低频重试

slot 取值 ​

PLC 型号slot说明
S7-2002需 CP 243-1 以太网模块
S7-3002CPU 位于机架 0 槽 2
S7-4002(典型)视实际机架配置而定
S7-12001CPU 集成 PN 接口
S7-15001CPU 集成 PN 接口

地址格式 ​

S7 地址直接使用 STEP 7 / TIA Portal 中的符号:

地址形式含义推荐类型
DB<n>.DBD<x>数据块双字(32 位)float32 / int32 / uint32
DB<n>.DBW<x>数据块字(16 位)int16 / uint16
DB<n>.DBB<x>数据块字节(8 位)int8 / uint8
DB<n>.DBX<x>.<bit>数据块位bool
I<x>.<bit> / IB IW ID输入区位/字节/字/双字bool / int8 / int16 / int32
Q<x>.<bit> / QB QW QD输出区位/字节/字/双字bool / int8 / int16 / int32
M<x>.<bit> / MB MW MD位存储区位/字节/字/双字bool / int8 / int16 / int32

位偏移取值 0–7,超出该范围的位地址视为无效。E/A 可分别替代 I/Q(德式记法)。

yaml
tags:
  - name: reactor_temp
    address: "DB1.DBD0"   # DB1 双字 0,Float32
    type: float32
  - name: emergency_stop
    address: "I0.0"       # 输入位 0.0
    type: bool

批量读合并 ​

一次轮询内,同内存区(DB 场景下同 DB 号)且地址相邻或间隙 ≤32 字节的多个非位标签会合并为一次 PLC 读请求(单段上限 480 字节,超长连续区间自动分段);间隙超限的稀疏标签各自独立读,位标签(DBX/I/Q/M 位)始终逐个读。合并段内任一读失败时,该段全部标签标 QualityBad。


OPC UA (opcua) ​

作为 OPC UA 客户端连接 SCADA、MES 或独立 OPC 服务器,支持轮询与订阅两种采集模式。

yaml
- name: opc-server
  type: opcua
  settings:
    endpoint: "opc.tcp://192.168.1.50:4840"
    mode: polling
    timeout: 5s

settings 字段 ​

字段类型必填默认值说明
endpointstring是—OPC UA 端点 URL,格式 opc.tcp://host:port
modestring否polling采集模式:polling 或 subscription
timeoutduration否5s连接与单次操作超时时间
security-policystring否—安全策略,如 None、Basic256Sha256
security-modestring否—安全模式,如 None、Sign、SignAndEncrypt
usernamestring否—用户名认证(未设置时使用匿名认证)
passwordstring否—密码认证
cert-filestring否—客户端证书 PEM 文件路径
key-filestring否—客户端私钥 PEM 文件路径
subscription-intervalduration否500ms订阅模式下的发布间隔
subscription-bufferint否1024订阅通道缓冲容量
max-batch-sizeint否1000单次读请求的最大节点数
reconnect-intervalduration否2s重连初始退避间隔
reconnect-max-intervalduration否30s重连退避上限
max-reconnect-failuresint否20断路器阈值,连续失败达到此值后将重连间隔提升至 5 分钟低频重试

mode 取值 ​

取值行为适用场景
polling按标签 interval 周期主动读服务端不支持订阅、或需精确控制采集频率
subscription由服务端在数据变化时推送实时性要求高、希望减少无效轮询

WARNING

并非所有 OPC UA 服务端都支持 subscription 模式。若服务端拒绝创建订阅,驱动会记录 warn 日志并自动回退到轮询采集,无需修改配置。若通过 API 调用 Subscribe() 而驱动处于 polling 模式,则返回 subscribe not supported by this driver 错误。

地址格式 ​

OPC UA 地址采用 NodeId 标准表示法:

形式示例说明
命名空间 + 字符串ns=2;s=Conveyor.Speed最常用,可读性强
命名空间 + 数字ns=1;i=1001引用数字 NodeId
仅数字i=2258Server.CurrentTime 等标准节点

标签配置(tags) ​

tags 列表定义驱动下每个数据点的采集规则。对应核心 TagConfig 结构。

yaml
tags:
  - name: temperature
    address: "40001"
    type: float32
    group: sensors
    interval: 1s
    scale: 1.0
    offset: 0.0
    deadband: 0.2

字段说明 ​

字段类型必填默认值说明
namestring是—标签名称,同一驱动内唯一,作为数据点的 tag 字段
addressstring是—设备地址,格式随驱动类型而异
typestring是—数据类型,见下表
groupstring否—分组名,用于规则按组匹配与传输主题渲染
intervalduration否引擎 default-tag-interval(默认 1s)采集周期,如 1s、500ms、200ms
scalefloat否1.0线性缩放系数,输出 = value * scale + offset
offsetfloat否0.0线性偏移量
deadbandfloat否0死区过滤阈值,变化量小于该值时不输出
read-timeoutduration否同 interval单次读取超时时间,独立于采集周期

支持的数据类型 ​

type位宽说明
bool1布尔
int88有符号 8 位整数
int1616有符号 16 位整数
int3232有符号 32 位整数
int6464有符号 64 位整数
uint88无符号 8 位整数
uint1616无符号 16 位整数
uint3232无符号 32 位整数
uint6464无符号 64 位整数
float3232单精度浮点
float6464双精度浮点
string—字符串
bytes—原始字节

interval 写法 ​

采用 Go duration 字符串:

写法含义
200ms200 毫秒
500ms500 毫秒
1s1 秒
2s2 秒
1m1 分钟

TIP

调度器按 interval 把标签分组成采集任务:interval 相同(解析后等值,如 1s 与 1000ms)的标签合并为一次批量读请求,显著降低通信开销。group 仅用于规则匹配与主题渲染,不参与读取合并——需要合并的标签请使用相同的 interval。

settings 键名校验

每个驱动的 settings 支持的键在配置校验时即被检查:拼错的键(如 slve-id)会在 PUT /configs/POST /configs/validate 时直接报错并列出全部合法键,而不是静默忽略后用默认值连到错误的设备。各驱动支持的键以下文的配置表为准。

scale 与 offset ​

对原始读值做线性变换,常用于传感器量程转换:

text
输出值 = 原始值 × scale + offset
yaml
- name: pressure
  address: "40003"
  type: uint16
  scale: 0.01      # 寄存器存的是 100 倍工程值
  offset: 0.0
  interval: 1s

写入语义(反演):配置了 scale/offset 的标签,写入时默认接受工程值,驱动在编码前自动反演回原始值:

text
设备原始值 = (写入值 - offset) / scale

以 pressure(scale=0.01)为例:读取显示 1.5,下发 1.5,PLC 寄存器收到 150——读写往返一致。调试或原始报文下发场景可在写指令中传 "raw": true 跳过反演(见 数据 API)。bool/string/bytes 类型不参与变换。

变换覆盖全部数值类型(int8~int64、uint8~uint64、float32/float64);带变换的整型读取结果为 float64 工程值。

deadband ​

死区过滤:仅当本次读值与上次输出值的差值绝对值不小于 deadband 时才产生新数据点(即 |Δ| ≥ deadband 通过),用于抑制传感器抖动、减少上行流量。

质量穿透:bad 或 uncertain 质量的点始终通过死区过滤(不更新基线)——质量劣化必须对下游可见,且坏值不参与基线比较,避免污染基线导致后续正常值被误吞。仅 good 质量的点参与死区比较与基线更新。

yaml
- name: temperature
  address: "40001"
  type: float32
  deadband: 0.2    # 温度变化小于 0.2 时不输出
  interval: 1s

INFO

deadband 仅对数值类型(int*/uint*/float*)生效,bool、string、bytes 类型忽略该设置——非数值类型的每次采集值都会照常输出,且不参与基线比较。设为 0 表示禁用死区,每次采集都输出。

read-timeout ​

为标签单独设置读取超时时间,独立于采集周期 interval。默认不设置时读取超时等于 interval。在高频采集场景(如 interval: 200ms)下,网络抖动可能导致读取耗时接近 interval 而频繁超时;通过设置较大的 read-timeout(如 500ms)可以容忍更多抖动。反之,低频场景下可以设置较小的 read-timeout 避免一个卡住的连接阻塞调度过久。

注意:interval 相同的标签合并为同一个采集任务,任务内所有标签共用该组中最大的 read-timeout。

yaml
- name: temperature
  address: "40001"
  type: float32
  interval: 200ms
  read-timeout: 500ms   # 允许单次读取最多 500ms,而非默认的 200ms

Timestamp 语义 ​

所有驱动的数据点 timestamp 统一取 CoreC 主机本地时钟在采集/接收时刻的值(time.Now()),而非设备或服务器侧时间源:

  • Modbus 与 S7 协议本身不携带时间戳,始终以本地时钟打点;
  • OPC UA 轮询与订阅模式均以本机接收时刻打点,不采用服务器的 SourceTimestamp。

下游所有依赖 timestamp 的语义——derived tag 的 stale-guard 陈旧保护、API 的 is_stale 标注、dataAge 指标——都与本地时钟比较。统一时间源意味着:只要 CoreC 主机时钟正常(NTP 同步),即使 OPC UA 服务器时钟漂移,陈旧判定也不会误标点位为陈旧或误判新鲜。

质量戳(OPC UA):轮询与订阅两种模式都会把服务器的 StatusCode 映射为质量戳——OK → good;其余(含 Uncertain)保守映射为 bad(订阅模式下 bad 点不带值)。质量戳随后进入管线的 bad-quality 策略、死区质量穿透与告警规则,两条采集路径语义一致。


外部标签文件(tags-file) ​

当一个驱动的采集点数量较多(数十至数百以上),将所有标签内联在主配置文件中会使文件臃肿且难以维护。tags-file 允许将标签列表拆分到独立的 YAML 文件中。

基本用法 ​

主配置文件:

yaml
drivers:
  - name: plc-modbus
    type: modbus-tcp
    settings:
      host: 192.168.1.100
      port: 502
    tags-file: ./tags/plc-modbus-tags.yaml

外部标签文件(./tags/plc-modbus-tags.yaml)格式为 YAML 列表,与内联 tags 字段结构完全相同:

yaml
- name: temperature
  address: "40001"
  type: float32
  group: sensors
  interval: 1s
- name: pressure
  address: "40003"
  type: float32
  group: sensors
  interval: 1s
- name: pump_status
  address: "00001"
  type: bool
  group: actuators
  interval: 2s

内联与文件混用 ​

tags 与 tags-file 可同时配置。文件标签排列在前,内联标签追加在后。标签名在两者间必须唯一,否则配置校验会报错。

yaml
drivers:
  - name: plc-modbus
    type: modbus-tcp
    settings: { host: 192.168.1.100, port: 502 }
    tags-file: ./tags/plc-modbus-tags.yaml   # 文件中的标签
    tags:                                      # 内联标签(追加在后)
      - name: custom_tag
        address: "40010"
        type: float32
        interval: 5s

热重载 ​

配置 tags-interval 后,引擎会按指定间隔周期性检查标签文件。文件内容变化时(基于 SHA-256 校验),引擎自动移除旧标签的采集任务并按新标签列表重建驱动,无需重启或手动触发配置重载。

yaml
drivers:
  - name: plc-modbus
    type: modbus-tcp
    settings: { host: 192.168.1.100, port: 502 }
    tags-file: ./tags/plc-modbus-tags.yaml
    tags-interval: 30s   # 每 30 秒检查一次文件变化

热重载机制

  • 变更检测基于文件内容的 SHA-256 哈希,仅内容真正变化时才触发重载。
  • 重载过程为移除旧驱动实例并按新标签列表重新创建,期间该驱动短暂中断采集。
  • 文件是热重载的唯一事实来源:重载后标签列表被文件内容整体替换,主配置中的内联 tags 不再保留(仅启动时的首次加载会做"文件 + 内联"合并)。内联与文件混用的驱动请勿依赖 tags-interval 热重载。
  • 从文件中删除的标签会同时清空其缓存值。
  • tags-interval 为空时不启动 watcher,标签仅在启动时加载一次。
  • 通过 API PUT /configs 触发的全量配置重载会重新读取并合并标签文件。

Released under the MIT License.