KNXnet/IP

Connection String Options

Name

Type

Default Value

Required

Description

Name

KNXNet/IP

Code

knxnet-ip

Maven Dependency

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

Default Transport

udp

Supported Transports

udp

Config options:

knxproj-file-path

FILE

Path to the knxproj file. The default KNXnet/IP protocol doesn’t provide all the information needed to be able to fully decode the messages.

knxproj-password

STRING

Optional password needed to read the knxproj file.

group-address-num-levels

INT

KNX Addresses can be encoded in multiple ways. Which encoding is used, is too not provided by the protocol itself so it has to be provided externally:

- 3 Levels: {main-group (5 bit)}/{middle-group (3 bit)}/{sub-group (8 bit)}
- 2 Levels: {main-group (5 bit)}/{sub-group (11 bit)}
- 1 Level: {sub-group (16 bit)}

The default is 3 levels. If the knxproj-file-path this information is provided by the file.

connection-type

STRING

LINK_LAYER

Type of connection used to communicate. Possible values are:

- 'LINK_LAYER' (default): The client becomes a participant of the KNX bus and gets it’s own individual KNX address.
- 'RAW': The client gets unmanaged access to the bus (be careful with this)
- 'BUSMONITOR': The client operates as a busmonitor where he can’t actively participate on the bus. Only one 'BUSMONITOR' connection is allowed at the same time on a KNXnet/IP gateway.

request-timeout

INT

10000

Maximum time (in milliseconds) to wait for a reply during the KNXnet/IP search, connect and tunnelling exchanges.

Transport config options:

udp

udp.local-address

STRING

Local address to bind to. If not set, binds to all interfaces.

udp.local-port

INT

Local port to bind to. 0 uses ephemeral port.

udp.read-timeout

INT

Socket read timeout in milliseconds. 0 means no timeout.

udp.max-packet-size

INT

65507

Maximum UDP packet size in bytes.

udp.send-buffer-size

INT

Send buffer size in bytes. 0 uses system default.

udp.receive-buffer-size

INT

Receive buffer size in bytes. 0 uses system default.

udp.broadcast

BOOLEAN

false

Enable SO_BROADCAST for sending broadcast packets.

udp.reuse-address

BOOLEAN

false

Enable SO_REUSEADDR to allow multiple bindings to the same address/port.

udp.share-socket

BOOLEAN

false

Share the underlying UDP socket across multiple transport instances. When true, instances with the same localAddress:localPort will share a socket. This is useful for protocols where multiple logical connections share one UDP port.

udp.multicast-ttl

INT

Time-to-live for multicast packets (1-255).

Individual Resource Address Format

KNX Addresses usually have one of the following structures:

3-level Address: {main-group(0-15)}/{middle-group(0-15)}/{sub-group(0-255)}
2-level Address: {main-group(0-15)}/{sub-group(0-4095)}
1-level Address: {sub-group(0-65535)}

Depending on the group-address-type configured in the connection string or defined in the knxproj-file configured by the knxproj-file-path connection string parameter, the corresponding address pattern has to be used.

However, when subscribing for events, each segment allows using of the wildcard character *. If the addresses used in the KNX installation are structured, this way it is possible to, for example (depending on the scheme used):

Collect all information for a given level of your building: 1//
Collect all information for a given room: 2/4/*
Collect all information about heating in all rooms: //50

Don’t use wildcards when explicitly reading or writing data, this is only supported when subscribing to events.