IoT 组件概览

rulego-components-iot 提供工业 IoT 协议采集与时序落盘能力，覆盖 **9 种采集协议 + 5 种时序数据库**。

需要额外引入扩展库： rulego-components-iot (opens new window)

两层抽象

层	包	职责
采集	pkg/iot_points	统一 Driver 接口（ReadPoints/WritePoints）、Point/Data 数据模型、模板渲染
落盘	pkg/tsdb	统一 Driver 接口（WritePoints/Query/Close）、SeriesPoint 数据模型

组件清单

通用节点

组件	说明
x/iotRead	通用采集读，按 driver 委派到具体协议读节点
x/iotWrite	通用采集写，按 driver 委派到具体协议写节点
x/tsdbWrite	通用时序写入，按 driver 委派到具体 TSDB 写节点
x/tsdbQuery	通用时序查询，按 driver 委派到具体 TSDB 查询节点，结果统一为 {Columns, Rows}

协议读写节点

协议	读节点	写节点	地址格式
Modbus	x/modbusRead	x/modbusWrite	Modicon（1-based）：40001=保持寄存器、30001=输入寄存器、00001=线圈、10001=离散输入
S7 西门子	x/s7Read	x/s7Write	DB1.DBD0, MW0, M0.1
EtherNet/IP	x/eipRead	x/eipWrite	标签名: MyDB.Temperature
OPC UA	x/opcuaRead	x/opcuaWrite	ns=2;s=Temperature
SNMP	x/snmpRead	x/snmpWrite	OID: 1.3.6.1.2.1.1.3.0
MC 三菱	x/mcRead	x/mcWrite	D100, M10.1, W200
FINS 欧姆龙	x/finsRead	x/finsWrite	DM100, CIO10.0
DL/T 645	x/dlt645Read	x/dlt645Write	DI: 00-01-00-00
IEC 104	x/iec104Read	x/iec104Write	IOA: 100, 16385

各协议地址格式的完整语法与更多示例，详见对应组件文档（如 x/modbusRead 的 Modicon 地址说明、x/s7Read 的西门子地址说明）。

端点（被动接收）

端点	说明
endpoint/opcua	OPC UA 客户端定时/订阅读取
endpoint/snmp	SNMP Trap 接收（UDP 162）
endpoint/hj212	HJ 212 环保数采协议（TCP 监听）
endpoint/modbusServer	Modbus TCP 从站（主站写入触发规则链）

时序写入节点

组件	后端
x/opengeminiWrite	OpenGemini
x/influxdbWrite	InfluxDB 2.x
x/tdengineWrite	TDengine (REST)
x/timescaledbWrite	TimescaleDB (PostgreSQL)
x/promremoteWrite	Prometheus Remote Write

控制节点

组件	说明
x/control/timer	软PLC 定时器（TON 接通延时 / TOF 断开延时），可取消、可重触发
x/control/watchdog	看门狗，消息透传并重新武装，失联超时下发故障安全 JSON

统一数据契约

采集输出（iotRead → msg.Data）

[
  {"name": "温度", "value": 25.3, "timestamp": 1721900000000000000},
  {"name": "湿度", "value": 60, "timestamp": 1721900000000000000, "error": ""}
]

• name：点位名称
• value：采集值（类型由协议/点位 type 决定）
• timestamp：Unix 纳秒时间戳
• error：单点失败原因（成功时为空/不存在）

时序输入（tsdbWrite ← msg.Data）

[
  {"measurement": "device1", "tags": {"site": "A"}, "fields": {"temp": 25.3}, "timestamp": 0}
]

• measurement：测点表名
• tags：索引维度
• fields：数值字段
• timestamp：纳秒时间戳（0=当前时间）

采集 → 时序 衔接

x/tsdbWrite 配置 measurement 后可直接接收三类输入，无需额外转换节点：

输入形态	处理方式
SeriesPoint（已透视的时序点）	透传落盘
采集点数组（iot_points.Data，即 x/iotRead 的输出）	按 measurement/tags/fields 配置自动透视为 SeriesPoint
扁平 map（聚合/脚本输出的单层键值对）	逐行转换为 SeriesPoint

典型链路：

x/iotRead → x/tsdbWrite（配置 measurement）

点位表字段说明

采集点位（points）统一结构 iot_points.Point，各字段含义：

字段	类型	说明
name	string	点位名，输出时作为 Data.name（下游取值的键）
addr	string	协议寻址串，各 driver 自行解析（格式见上方「地址格式」表）
type	string	数据类型，统一枚举 BOOL/INT16/UINT16/INT32/UINT32/INT64/UINT64/FLOAT32/FLOAT64/STRING，driver 映射到协议原生类型
scale	float64	工程量缩放系数，工程量 = raw × scale + offset；不填（0）按不缩放
offset	float64	工程量偏移量；注意 scale=0 而 offset≠0 时结果为 offset（如需仅平移应配 scale=1）
endian	string	字节序 ABCD/CDAB/BADC/DCBA，仅多寄存器类型（INT32/FLOAT32 等）生效
value	string	写入值（写节点用，字符串形式，driver 按 type 解析）

各字段支持 ${msg.xx} / ${metadata.xx} 模板。

字段协议支持情况（name/addr/type 全协议支持；工程量转换字段并非全协议生效）：

协议	scale/offset	endian
Modbus	✅	✅
S7 / EtherNet/IP	✅	—
MC 三菱	✅	—（固定 MELSEC 序）
FINS 欧姆龙	✅	—（固定大端）
DL/T 645	✅	—
SNMP / OPC UA / IEC 104	—（配了不生效）	—

在不支持 scale/offset 的协议上配置这些字段不会报错但也不生效，请按需使用。

统一结构的优势

优势	说明
下游协议无关	9 种协议输出完全相同的 [{name, value, timestamp, error}]——下游转换/过滤/落盘节点无需关心数据来自哪个协议
一套拓扑换任意后端	只改 driver 字段即可切换协议或 TSDB，规则链连线不变
逐点容错	单点失败标 error 继续采集，一个坏点不拖垮整批
模板驱动	所有点位字段支持 ${msg.xx} / ${metadata.xx}，动态采集/写入无需改拓扑
点位模板复用	统一的 name/addr/type 结构跨协议通用（scale/offset/endian 部分协议支持，见上表），导入一次到处使用
字节序感知	Modbus 点位级 Endian（ABCD/CDAB/BADC/DCBA）解码多寄存器类型，无需外部转换
连接池复用	同链 ref:// 机制让多个读写节点共享一条连接，减少 PLC 连接数

规则链 DSL 示例

采集 → 落盘（典型链路）

{
  "ruleChain": {"name": "iot-pipeline", "root": true},
  "metadata": {
    "nodes": [
      {"id": "n1", "type": "x/iotRead", "configuration": {
        "driver": "modbus", "server": "tcp://192.168.1.100:502",
        "points": [
          {"name": "voltage", "addr": "40001", "type": "FLOAT32", "scale": 0.1},
          {"name": "current", "addr": "40003", "type": "FLOAT32", "scale": 0.001}
        ]
      }},
      {"id": "n2", "type": "x/tsdbWrite", "configuration": {
        "driver": "timescaledb", "dsn": "postgres://user:pass@localhost:5432/iot?sslmode=disable",
        "measurement": "power_meter",
        "tags": [{"key": "deviceId", "value": "${metadata.deviceId}"}]
      }}
    ],
    "connections": [
      {"fromId": "n1", "toId": "n2", "type": "Success"}
    ]
  }
}

换协议只改 n1 的 driver（s7/opcua/snmp/fins/mc/iec104...），n2 不变。

遥控写入

{
  "ruleChain": {"name": "iot-control", "root": false},
  "metadata": {
    "nodes": [
      {"id": "w1", "type": "x/iotWrite", "configuration": {
        "driver": "iec104", "server": "192.168.1.20:2404", "commonAddr": 1,
        "points": [
          {"name": "breaker", "addr": "100", "type": "C_SC_NA_1", "value": "${msg.action}"}
        ]
      }}
    ],
    "connections": []
  }
}

Modbus 从站端点（写触发规则链）

{
  "ruleChain": {"name": "modbus-bridge", "root": true},
  "metadata": {
    "nodes": [
      {"id": "e1", "type": "endpoint/modbusServer", "configuration": {
        "server": "tcp://:5020", "unitId": 1
      }},
      {"id": "p1", "type": "jsTransform", "configuration": {
        "jsScript": "msg.receivedAt = Date.now(); return {msg: msg, metadata: metadata, msgType: msgType};"
      }},
      {"id": "w1", "type": "x/tsdbWrite", "configuration": {
        "driver": "influxdb", "url": "http://localhost:8086",
        "token": "my-token", "org": "rulego", "bucket": "iot"
      }}
    ],
    "connections": [
      {"fromId": "e1", "toId": "p1", "type": "ip"},
      {"fromId": "p1", "toId": "w1", "type": "Success"}
    ]
  }
}

更多场景组合示例见：IoT 场景示例

构建标签

• 默认编译：零 IoT 依赖，组件不注册
• with_iot 或 with_all：注册所有 IoT 组件

import (
    _ "github.com/rulego/rulego-components-iot/external/deviceio"
    _ "github.com/rulego/rulego-components-iot/external/tsdb"
)

点位模板

server 内置 6 个常用设备点位模板（三相电表/温湿度/OPC UA 仿真/S7-1200/IEC 104/SNMP 网络设备），前端"从模板"一键导入。模板存储在 data/iot/point-templates/，用户可增删改。