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>1.0.0</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-ms

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-ms

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-31)}/{middle-group(0-7)}/{sub-group(0-255)}
2-level Address: {main-group(0-31)}/{sub-group(0-2047)}
1-level Address: {sub-group(0-65535)}

Depending on the group-address-num-levels 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.

Datapoint Type Suffix

An address may carry an optional datapoint-type suffix :DPT{main}[.{sub}], which tells the driver how to interpret the value on the wire:

1/2/3:DPT9.001

The KNX protocol does not transport the datatype of a group address, so the driver has to get it from somewhere. If no knxproj-file-path is configured, this suffix is required for reading and writing - a request for a plain 1/2/3 fails because the datapoint type cannot be resolved. Browsing likewise requires a knxproj-file-path.

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.