KNXnet/IP

banner

KNXnet/IP is the IP tunnelling and routing extension of KNX, the field bus used in home and building automation for lighting, heating, shutters and similar building services. Devices exchange telegrams addressed to group addresses over the bus; the driver reaches that bus through a KNXnet/IP interface on the IP network.

Supported Operations

Name Value Description

read

Go and Java. Reads the value of a group address. Requires the datapoint type to be known, either from a :DPT… suffix on the tag or from a loaded ETS project.

write

Go and Java. Writes the value of a group address. Requires the datapoint type, same as read.

subscribe

Go and Java. Subscribes to telegrams on the bus. Each address segment may use a wildcard, so subscriptions can span a whole line, a whole room, or a whole datapoint across the installation.

browse

Go and Java, with different results. Java lists the group addresses known to a loaded ETS project, filtered by a browse query. Go connects live to devices on the bus, either enumerating them by KNX individual address (a device query) or listing a connected device’s communication objects (a communication object query).

Connection String

The KNXnet/IP connection string has the following format:

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

udp is the only supported transport and is the default, so it is omitted from the connection string. The port defaults to 3671:

knxnet-ip://192.168.42.28

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

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.

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

0

Local port to bind to. 0 uses ephemeral port.

udp.read-timeout-ms

INT

0

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

0

Send buffer size in bytes. 0 uses system default.

udp.receive-buffer-size

INT

0

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

1

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

Tag Addresses

Addressing is implemented in Go and Java. See the protocol support matrix for what each implementation does.

General Format

A tag names a KNX group address, using one of three levels of structure, optionally suffixed with a datapoint type:

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

1-level address

{main-group} alone, 0-65535.

2-level address

{main-group}/{sub-group}, main-group 0-31, sub-group 0-2047.

3-level address

{main-group}/{middle-group}/{sub-group}, main-group 0-31, middle-group 0-7, sub-group 0-255.

DPT suffix (optional)

:DPT{main}[.{sub}], e.g. :DPT9.001. See Datapoint Type Suffix below.

Which of the three level counts is expected is controlled by the group-address-num-levels connection string parameter, or by the levels recorded in a loaded knxproj-file-path project.

Go additionally accepts a bracketed list or range in any segment, such as 1/2/[3,4] or 1/[1-3]/. Java’s parser only ever accepts a bare digit run or a lone in each position; 1/2/[3,4] is rejected by Java. This page documents the Java syntax - consult the Go driver’s own source for what it accepts.

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 use of the wildcard character *. If the addresses used in the KNX installation are structured, this makes it 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.

Data Types

The value on the wire is interpreted using a KNX Datapoint Type (DPT), identified as DPT{main}[.{sub}] - for example DPT1 (1-bit boolean), DPT5 (8-bit unsigned) or DPT9.001 (2-byte float, temperature in °C). The datapoint type comes from the :DPT… tag suffix when present, and otherwise from the group address’s entry in a loaded knxproj-file-path ETS project. When a sub-number is not given in the suffix (DPT9 rather than DPT9.001), the driver resolves it to the first sub-type registered under that main number.

Examples

Table 1. Examples
Address Meaning

1/2/3

a 3-level group address

12/3000

a 2-level group address

12345

a 1-level group address

1/2/3:DPT9.001

a 3-level group address, decoded as a 2-byte float

//*

(subscribe only) every group address, at any level

Notes and Tips

Browse Queries

browse takes a separate query syntax, not a tag address: each of the three levels may be a literal number or the wildcard , and the whole query may itself be or ** to mean everything.

Table 2. Accepted browse queries
Query Meaning

or *

every group address

1/*

every group address under main-group 1

1/2/*

every group address under main-group 1, middle-group 2

1/2/3

exactly group address 1/2/3

*/2/3

every group address with middle-group 2, sub-group 3

Protocol Details

KNXnet/IP devices can be discovered on the network. Configuration and setup particulars for KNX installations, including how to supply an ETS project via knxproj-file-path, are covered by the connection string options above.