Telegraf KNX 输入插件knx_listener接入指南从 KNX 家庭自动化总线采集指标到 InfluxDB【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf导读knx_listener是 Telegraf 提供的一个服务型输入插件Service Input它通过 KNX-IP 接口连接到 KNX 家庭自动化总线实时监听总线上的组地址Group-Address消息并将解析后的数值、单位与来源物理地址写入指定 measurement。阅读本文后你将掌握该插件的完整配置语法service_type、service_address、measurement子表、DPTDatapoint-Type到测量值的映射规则、输出字段与标签结构以及其底层基于knx-go的连接、解包与断线重连机制。插件概览功能定位服务型输入插件通过 KNX-IP 接口隧道或路由模式连接 KNX 总线接收组事件并转换为 Telegraf 指标。引入版本Telegraf v1.19.0 起提供见 README.md 顶部徽标。类别标识️ iot物联网场景 all支持所有平台。实现位置knx_listener.go注册名称为inputs.knx_listener见 plugins/inputs/all/knx_listener.go。底层依赖KNX 协议交互由开源库knx-gogithub.com/vapourismo/knx-go/knx与.../knx/dpt完成支持的 DPT 类型以该库的实现为准。服务型输入插件Service Input的特殊性该插件属于服务型输入插件。与普通插件按固定interval轮询采集不同服务型插件会启动一个后台服务持续监听总线事件。根据 docs/includes/service_input.md 的说明它有两点关键差异interval设置可能不生效无论是全局还是插件级别的interval都不会驱动该插件采集数据——数据的产生完全由 KNX 总线上的消息触发。--test、--test-wait、--once命令行选项可能无输出这些选项通常要求插件在限定时间内完成一次采集而服务型插件需要等待外部事件因此调试时应改用真实总线数据或测试环境仓库提供了dummy接口类型供本地验证见下文源码分析。此外所有插件都支持一些通用配置项如修改指标、标签、字段、设置别名、调整插件顺序等详见 docs/CONFIGURATION.md#plugins。配置详解完整配置示例位于 sample.conf该文件同时被//go:embed嵌入二进制作为插件默认样例配置见 knx_listener.go 的SampleConfig()实现。# Listener capable of handling KNX bus messages provided through a KNX-IP Interface. [[inputs.knx_listener]] ## Type of KNX-IP interface. ## Can be either tunnel_udp, tunnel_tcp, tunnel (alias for tunnel_udp) or router. # service_type tunnel ## Address of the KNX-IP interface. service_address localhost:3671 ## Measurement definition(s) # [[inputs.knx_listener.measurement]] # ## Name of the measurement # name temperature # ## Datapoint-Type (DPT) of the KNX messages # dpt 9.001 # ## Use the string representation instead of the numerical value for the # ## datapoint-type and the addresses below # # as_string false # ## List of Group-Addresses (GAs) assigned to the measurement # addresses [5/5/1] # [[inputs.knx_listener.measurement]] # name illumination # dpt 9.004 # addresses [5/5/3]顶层参数参数类型默认值说明service_typestringtunnelKNX-IP 接口类型可选tunnel_udp、tunnel_tcp、tunneltunnel_udp的别名或router。另有非公开值dummy用于本地测试。service_addressstring必填KNX-IP 接口地址格式为host:port默认示例为localhost:3671KNXnet/IP 标准端口 3671。在源码 knx_listener.go 中Start()根据service_type分支建立连接tunnel/tunnel_udp使用knx.DefaultTunnelConfig且UseTCP false调用knx.NewGroupTunnel()建立UDP 隧道连接tunnel_tcp同样使用knx.DefaultTunnelConfig但UseTCP true建立TCP 隧道连接router调用knx.NewGroupRouter()建立组路由连接dummy创建内存模拟接口knxDummyInterface见 knx_dummy_interface.go仅用于单元测试其他值返回错误invalid interface type。插件实例默认以ServiceType: tunnel初始化见 knx_listener.go 的init()注册逻辑与样例配置注释中的默认值一致。measurement 子表参数每个[[inputs.knx_listener.measurement]]子表定义一组测量规则参数类型默认值说明namestring必填生成的 measurement 名称即写入 InfluxDB 的测量名。dptstring必填该测量对应的 KNX Datapoint-Type如9.001表示 2 字节浮点温度值。仅能声明一个 DPT。as_stringboolfalse为true时字段值输出 DPT 的字符串表示如On/Off、Enable/Disable而非数值同时组地址也按字符串处理。addresses[]string必填归属该测量的 KNX 组地址GA列表格式如5/5/1两段式或1/0/1三段式。测量配置要点与约束每个 measurement 只包含一个DPT并为该 DPT 绑定一组地址。例如可以把所有温度传感器消息归入temperaturemeasurement。你可以自由地将同一个 DPT 的消息拆分到多个 measurement中以便按房间、按传感器类型分表。重要约束README 明确警告——不应将同一个组地址GA分配到多个 measurement这一约束在源码层面被强制执行Init()在构建gaTargetMapGA → measurement/DPT 映射时若发现重复地址会直接返回错误duplicate specification of address见 knx_listener.go。相关辅助工具knx-telegraf-config-generator一个外部社区工具可从 KNX 项目文件ETS 导出自动生成 Telegraf 配置省去手工编写大量measurement子表的工作README 相关章节。指标输出字段与标签收到 KNX 消息后插件将其写入配置指定的 measurement字段名为value并附带以下标签见 knx_listener.go标签说明groupaddressKNX 组地址对应数值来源unit数值的单位取自 DPT 元数据例如°C、luxsource发送该值的 KNX 物理地址关于字段类型源码中listen()在解包数据帧后会通过反射reflect.Indirect把knx-go的dpt.DatapointValue接口值还原为基础类型bool / int / uint / float / string以避免指标被静默丢弃见 knx_listener.go。当as_string true时则直接使用target.datapoint.String()输出字符串表示。关于字段类型归属若需确认某个 DPT 对应的具体数据类型与单位可查阅你的 KNX 项目ETS、KNX 规范或knx-go项目中对应 DPT 的实现如 knx_listener_test.go 中的测试用例覆盖了 1.001、5.001、9.001、13.xxx、14.xxx、16.000 等常见 DPT。示例输出Line Protocolillumination,groupaddress5/5/4,hostHugin,source1.1.12,unitlux value17.889999389648438 1582132674999013274 temperature,groupaddress5/5/1,hostHugin,source1.1.8,unit°C value17.799999237060547 1582132663427587361 windowopen,groupaddress1/0/1,hostHugin,source1.1.3 valuetrue 1582132630425581320从示例可见temperatureDPT 9.001输出带unit°C的浮点值illuminationDPT 9.004输出带unitlux的浮点值windowopen布尔类 DPT输出valuetrue且因布尔类型无单位示例中没有unit标签unit标签来自 DPT 元数据的Unit()方法。host标签由 Telegraf 全局配置自动添加。底层实现与运行机制启动与监听流程Start()knx_listener.go完成连接后会启动一个 goroutine 调用listen(acc)持续消费knxInterface.Inbound()通道中的knx.GroupEvent。核心处理逻辑忽略读请求GroupValue_Read请求被直接跳过——原因是此类消息要么因数据长度无效非 DPT1而解包失败要么因数据恒为0而产生错误的false值DPT1见 knx_listener.go。地址匹配以消息目标地址msg.Destination.String()查gaTargetMap未配置的 GA 会被忽略且通过gaLogbook记录以避免日志刷屏仅首次出现时输出一条Ignoring message ... for unknown GA日志。数据解包调用target.datapoint.Unpack(msg.Data)按 DPT 解析原始字节失败则记录错误并跳过。类型还原与输出按上文所述还原为基础类型后以acc.AddFields(measurement, fields, tags)写入指标。断线自动重连插件具备自动重连能力监听 goroutine 一旦退出如总线断开会置connected标志为false并向 accumulator 报告disconnected from bus错误knx_listener.go。随后的每个Gather()周期都会检查connected标志若发现断开则调用Start()重新连接直至成功knx_listener.go。Stop()负责关闭底层接口并等待监听 goroutine 退出knx_listener.go。TestReconnectknx_listener_test.go通过dummy接口验证了完整链路发送消息 → 关闭接口触发断连 → 断言disconnected from bus错误 → 调用Gather()触发重连 → 再次发送消息并成功采集。测试验证与 DPT 覆盖knx_listener_test.go 中的TestRegularReceives_DPT覆盖了超过 30 种地址/DPT 组合包括布尔类1.xxx1.001开/关字符串表示On/Off、1.002True/False、1.003Enable/Disable、1.009Close/Open、1.010Start/Stop浮点与百分比5.xxx、9.xxx5.001、5.003、5.004、9.001温度、9.004照度 lux、9.005、9.007有符号/无符号整数13.xxx13.001、13.002、13.010~13.015物理量14.xxx14.000~14.004、14.010、14.011字符串16.000hello world。TestRegularReceives_MultipleMessages验证了同一地址重复消息、以及未配置地址1/1/2的消息被忽略的行为与 README 中不应重复分配 GA的约束形成闭环。使用前提与限制KNX 基础设施需要一个可达的 KNX-IP 接口如 IP 网关/接口端口 3671或具备组路由能力的 KNX-IP 路由器。KNX 知识需要了解 KNX 组地址GA与 Datapoint-TypeDPT概念通常可从 ETS 项目文件获取对应关系。平台兼容插件标记为all跨平台可用dummy接口仅存在于测试代码路径不影响生产使用。事件驱动指标只在总线上出现消息时产生空闲时段不会有新数据写入。小结knx_listener将 KNX 家庭自动化总线与 Telegraf 指标管道无缝衔接通过简单的measurement子表即可完成 GA→DPT→measurement 的映射自动附带组地址、单位与来源物理地址标签底层由knx-go负责 KNXnet/IP 协议交互并内置断线自动重连。结合 sample.conf、knx_listener.go 与 knx_listener_test.go 的源码证据你可以快速将温度、照度、开关状态等 KNX 总线数据接入 InfluxDB构建完整的智能家居监控体系。【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
