KNXnet/IP

banner

KNXnet/IP 是 KNX 的 IP 隧道与路由扩展。KNX 是一种现场总线，广泛用于家居和楼宇自动化中的照明、供暖、百叶窗等楼宇服务。设备在总线上通过组地址交换报文；驱动程序通过 IP 网络上的 KNXnet/IP 接口接入该总线。

支持的操作

名称	值	说明
	`read`	支持 Go 和 Java。读取某个组地址的值。需要已知数据点类型，其来源可以是标签上的 `:DPT…` 后缀，也可以是已加载的 ETS 项目。
	`write`	支持 Go 和 Java。写入某个组地址的值。同样需要数据点类型，要求与 `read` 相同。
	`subscribe`	支持 Go 和 Java。订阅总线上的报文。每个地址段都可以使用通配符，因此订阅可以覆盖整个线路、整个房间，或整个安装范围内的某类数据点。
	`browse`	支持 Go 和 Java，但返回结果不同。Java 列出已加载的 ETS 项目中已知的组地址，并按浏览查询进行过滤。Go 直接连接到总线上的设备，既可以按 KNX 个体地址枚举设备（设备查询），也可以列出已连接设备的通信对象（通信对象查询）。

连接字符串

KNXnet/IP 连接字符串的格式如下：

knxnet-ip://{ip-address}[:{port}]?{options}

udp 是唯一受支持的传输方式，同时也是默认方式，因此在连接字符串中被省略。端口默认为 3671：

knxnet-ip://192.168.42.28

连接字符串选项

名称

类型

默认值

是否必填

说明

名称

KNXNet/IP

代码

knxnet-ip

Maven 依赖

<dependency>
  <groupId>org.apache.plc4x</groupId>
  <artifactId>plc4j-driver-knxnetip</artifactId>
  <version>1.0.0</version>
</dependency>

默认传输协议

udp

支持的传输协议

udp

配置选项：

knxproj-file-path

FILE

knxproj 文件的路径。默认的 KNXnet/IP 协议并未提供完全解码消息所需的全部信息。

knxproj-password

STRING

读取 knxproj 文件所需的可选密码。

group-address-num-levels

INT

KNX 地址可以用多种方式编码。由于协议本身并不提供使用哪种编码的信息，因此必须由外部提供：

- 3 级地址：\{主组（5 位）}/\{中间组（3 位）}/\{子组（8 位)}
- 2 级地址：\{主组（5 位）}/\{子组（11 位)}
- 1 级地址：\{子组（16 位)}

默认为 3 级地址。如果为 knxproj-file-path，则该信息由文件提供。

connection-type

STRING

LINK_LAYER

所使用的连接类型。可取的值有：

- LINK\_LAYER（默认）：客户端成为 KNX 总线的参与者，并获得自己的独立 KNX 地址。
- RAW：客户端获得对总线的非受管访问权限（请谨慎使用）。
- BUSMONITOR：客户端以总线监视器的方式运行，无法主动参与总线通信。在一个 KNXnet/IP 网关上，同一时间只允许建立一个 BUSMONITOR 连接。

request-timeout-ms

INT

10000

在 KNXnet/IP 查找、连接与隧道交换期间等待回复的最大时间（以毫秒为单位）。

传输配置选项：

udp

udp.local-address

STRING

绑定到的本地地址。如未设置，则绑定到所有网卡接口。

udp.local-port

INT

要绑定的本地端口。0 表示使用临时端口。

udp.read-timeout-ms

INT

以毫秒为单位的套接字读取超时时间。0 表示不超时。

udp.max-packet-size

INT

65507

以字节为单位的 UDP 最大报文大小。

udp.send-buffer-size

INT

以字节为单位的发送缓冲区大小。0 表示使用系统默认值。

udp.receive-buffer-size

INT

以字节为单位的接收缓冲区大小。0 表示使用系统默认值。

udp.broadcast

BOOLEAN

false

为发送广播数据包启用 SO_BROADCAST。

udp.reuse-address

BOOLEAN

false

启用 SO_REUSEADDR 以允许将多个绑定关联到同一地址/端口。

udp.share-socket

BOOLEAN

false

在多个传输实例之间共享底层 UDP 套接字。为 true 时，localAddress:localPort 相同的实例将共享同一个套接字。这对于多个逻辑连接共用同一个 UDP 端口的协议非常有用。

udp.multicast-ttl

INT

组播数据包的生存时间（1-255）。

标签地址

地址的实现方式有 Go 和 Java 两种。请参阅协议支持矩阵]，了解各实现方式的功能。

通用格式

标签用于指定 KNX 组地址，使用三级结构之一，并可选地以数据点类型作为后缀：

{main-group}
{main-group}/{sub-group}
{main-group}/{middle-group}/{sub-group}
{address}:DPT{main}[.{sub}]

名称	说明
1 级地址	仅 `{main-group}`，取值 0-65535。
2 级地址	`{main-group}/{sub-group}`，主组 0-31，子组 0-2047。
3 级地址	`{main-group}/{middle-group}/{sub-group}`，主组 0-31，中间组 0-7，子组 0-255。
DPT 后缀（可选）	`:DPT{main}[.{sub}]`，例如 `:DPT9.001`。参见下文的数据点类型后缀]。

期望使用哪一种级数，由 group-address-num-levels 连接字符串参数控制，或由所加载的 knxproj-file-path 工程中记录的级数决定。

	Go 还额外接受任意段中的括号列表或范围，例如 `1/2/[3,4]` 或 `1/[1-3]/`。Java 的解析器在每个位置只接受纯数字串或单个；`1/2/[3,4]` 会被 Java 拒绝。本页描述的是 Java 语法——具体接受哪些形式请参阅 Go 驱动自身的源码。

数据点类型后缀

地址可以带有一个可选的数据点类型后缀 :DPT{main}[.{sub}]，它告诉驱动如何解释线路上传输的值：

1/2/3:DPT9.001

KNX 协议不传输组地址的数据类型，因此驱动必须从别处获取它。如果未配置 knxproj-file-path，则读写时必须加上该后缀——不带后缀的纯 1/2/3 请求会因无法解析数据点类型而失败。浏览同样需要 knxproj-file-path。

不过，在订阅事件时，每一段都允许使用通配符 *。如果 KNX 安装中使用的地址是有结构的，就可以据此实现例如（取决于所用方案）：

收集建筑中某一指定层级的全部信息：1//
收集某一指定房间的全部信息：2/4/*
收集所有房间中供暖相关的全部信息：//50

	在显式读写数据时不要使用通配符——这仅在订阅事件时受支持。

数据类型

线路上的值使用 KNX 数据点类型（DPT）来解释，由 DPT{main}[.{sub}] 标识——例如 DPT1（1 位布尔值）、DPT5（8 位无符号数）或 DPT9.001（2 字节浮点数，单位为 °C 的温度）。数据点类型在存在 :DPT… 标签后缀时取自该后缀，否则取自已加载的 knxproj-file-path ETS 项目中该组地址的条目。如果后缀中未给出子编号（写的是 DPT9 而不是 DPT9.001），驱动会将其解析为该主编号下注册的第一个子类型。

示例

地址	含义
`1/2/3`	三级组地址
`12/3000`	二级组地址
`12345`	一级组地址
`1/2/3:DPT9.001`	三级组地址，按 2 字节浮点数解码
`//*`	（仅限订阅）任意层级的所有组地址

表 1. 示例

注意事项与提示

浏览查询

browse 使用独立的查询语法，而不是标签地址：三级中的每一级都可以是字面数字或通配符 **，整个查询本身也可以是 ** 或 **，表示全部。

查询	含义
或 `*`	所有组地址
`1/*`	主组 1 下的所有组地址
`1/2/*`	主组 1、中间组 2 下的所有组地址
`1/2/3`	恰好为组地址 `1/2/3`
`*/2/3`	中间组 2、子组 3 的所有组地址

表 2. 支持的浏览查询

协议细节

KNXnet/IP 设备可以在网络上被发现。KNX 安装的配置与设置细节（包括如何通过 knxproj-file-path 提供 ETS 项目）由上文的连接串选项涵盖。

支持的操作

连接字符串

连接字符串选项

udp

标签地址

通用格式

数据点类型后缀

数据类型

示例

注意事项与提示

浏览查询

协议细节

评论