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>0.12.0</version>
</dependency>

Default Transport

udp

Supported Transports

  • udp

  • pcap

  • raw

Config options:

knxproj-file-path

STRING

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

3

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.

Transport config options:

udp

udp.local-port

INT

-1

Some connections require a UDP listener to listen on a fixed port.
Use this configuration option in order to define the port number of the local port.

pcap

pcap.replay-speed-factor

FLOAT

1.0

Numeric value for changing the replay speed:
- 1 = Normal speed (default)
- 0 = Maximum speed
- 0.5 = Half speed
- 2 = Double speed

pcap.loop

BOOLEAN

false

Should the replay start at the beginning of the file as soon as the end is reached?
- true = Automatically start again
- false = Stop at the end (default)

pcap.filter

STRING

Filter expression used to filter out unwanted packets from the replay.

pcap.support-vlans

BOOLEAN

false

Should VLan packets be automatically unpacked?

pcap.protocol-id

INT

-1

When provided, filters all packets to let only packets matching this ethernet protocol-id pass.

raw

raw.resolve-mac-address

BOOLEAN

If set to true, the transport will automatically resolve the MAC address for a given IP address (Allows connecting to a raw-socket device using the devices host-name or ip-address).

raw.support-vlans

BOOLEAN

false

Should VLan packets be automatically unpacked?

raw.protocol-id

INT

-1

When provided, filters all packets to let only packets matching this ethernet protocol-id pass.

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.