A reactive, non-blocking Java library for KNX Net/IP communication.
The purpose of this library is designed for developers to allow their applications to communicate with KNX world via KNX Net/IP device (either a KNX router or a KNX interface) and it supports tunneling and routing modes.
For examples, to get a quick start see examples below. It contains few main classes to get a quick basic understanding how the communication with KNX can be done in programmatically way; see knx-core and knx-core-plugins.
For a demo application see knx-demo-tty-monitor.
- No KNX Secure which are offered by newest generation of KNX Net/IP devices (because I do not have a KNX router that supports KNX secure)
- Java 11+
- Make sure that you have Java 11+ installed and running as Java 11+
- Tunneling: KNX Router or Interface
- One free tunneling connection available
- IP-Address (optional, if not provided - the auto-discovery service will be used)
- Routing: KNX Router only
- Filter table on your KNX router device is properly configured, otherwise packets won't be forwarded
- IP Multicast Address that is used by your KNX router (optional, if not provided, the default 188.8.131.52 multicast address will be used)
The communication between KNX Net/IP device and the KNX client is reactive and non-blocking which allows a very fast communication and we may have multiple channels simultaneously open:
- Discovery Channel for discovery service (multicast)
- Description Channel for receiving description information
- Control Channel for tunneling; control-related frames like connect, disconnect and connection state
- Data Channel for tunneling; data-related frames like read/write requests from and to KNX
- Multicast Channel for routing; data-related frames
Communication mode (Tunneling, NAT, Routing)
According to the KNX specification the communication is defaulted to tunneling mode and without
Network Address Translation (NAT). If you have multiple KNX Net/IP devices and want to specify
the IP-Address use the
--ip <address[:port]>. If the communication should be using routing instead
of tunneling then it must be explicitly defined using
Using tunneling mode we need Network Address Translation (NAT) in some cases; this must be
--nat parameter. When NAT enabled, then the Control Channel and Data Channel
will use a shared channel. One practical example, where we need NAT would be e.g. dockerized image.
NAT is suitable for tunneling mode only, in routing mode it has no
All data-related frames of all KNX group addresses that is sent by KNX Net/IP device will be fetched and handled by the KNX client and it offers:
- Status Pool to fetch the latest status and data about the KNX group address
- Event Pool for more advanced and detailed diagnosis and stores the original request and response frames frame belongs to which request frame for more advanced and detailed diagnosis
- Statistic to get basic statistic how many bytes/frames/type of frames were sent or received
- Plugin Injector allowing to extend KNX client with plugin, for example: auditing, long-term event logging, and much more.
- Data Point Type Translator to translate human-friendly (e.g. "on", "off"), Java data types (e.g. true, false) into KNX compatible byte representation; and vice versa
Data Point Types
This KNX library (incl. KNX Client) supports following data point types below and is designed to translate data point types in a fluent way into a KNX byte-array compatible format.
|1.xxx||Binary||11.xxx||Date (Year: 1990..2089)||21.xxx||8-Bit Flagged Messages|
|2.xxx||Controlled Binary||12.xxx||4-Octet Unsigned Value||22.xxx||16-Bit Flagged Messages|
|3.xxx||Controlled Step/Interval||13.xxx||4-Octet Signed Value||23.xxx||2-Bit Enumeration|
|4.xxx||Character||14.xxx||4-Octet Float Value|
|5.xxx||8-Bit Unsigned Value||15.xxx||Access Data|
|6.xxx||8-Bit Signed Value||16.xxx||14-Octet Characters|
|7.xxx||2-Octet Unsigned Value||17.xxx||Scene Number|
|8.xxx||2-Octet Signed Value||18.xxx||Controlled Scene Number|
|9.xxx||2-Octet Float Value||19.xxx||Date and Time (Year: 1900..2155)|
Quick Start Guides
Send a WRITE request frame to KNX
--groupAddressthe KNX group address which has a write flag
--dataPointTypethe KNX Data Point Type
--valuea sequence of commands that is compatible with KNX Data Point Type argument
Switching lamp on KNX group address
Perform a DPT1 - Switch (
1.001) write request action on KNX group address
1/2/50 to switch
on and then
off a lamp. For demo purposes the delay between commands is hardcoded with two seconds.
# Tunneling (auto-discovery) java -cp <file>.jar li.pitschmann.knx.examples.write.Main -ga 1/2/50 -dpt 1.001 -v on off # Tunneling (auto-discovery with NAT) java -cp <file>.jar li.pitschmann.knx.examples.write.Main --nat -ga 1/2/50 -dpt 1.001 -v on off # Tunneling (IP Address) java -cp <file>.jar li.pitschmann.knx.examples.write.Main --ip 192.168.1.16 -ga 1/2/50 -dpt 1.001 -v on off # Tunneling (IP Address with NAT) java -cp <file>.jar li.pitschmann.knx.examples.write.Main --ip 192.168.1.16 --nat -ga 1/2/50 -dpt 1.001 -v on off # Routing java -cp <file>.jar li.pitschmann.knx.examples.write.Main --routing -ga 1/2/50 -dpt 1.001 -v on off
For sequence of commands you may use e.g.
(-v|--value) on off on off to switch on/off the lamp twice
Send a READ request frame to KNX
--groupAddressthe KNX group address which has a read flag
--loopsnumber of read requests
Read the actual status of a lamp on KNX group address
Send a read request frames to KNX group address
1/2/113 up to
10 times. For demo purposes the delay
between read requests is hardcoded with one second.
# Tunneling (auto-discovery) java -cp <file>.jar li.pitschmann.knx.examples.read.Main -ga 1/2/113 -n 10 # Tunneling (auto-discovery with NAT) java -cp <file>.jar li.pitschmann.knx.examples.read.Main --nat -ga 1/2/113 -n 10 # Tunneling (IP Address) java -cp <file>.jar li.pitschmann.knx.examples.read.Main --ip 192.168.1.16 -ga 1/2/113 -n 10 # Tunneling (IP Address with NAT) java -cp <file>.jar li.pitschmann.knx.examples.read.Main --ip 192.168.1.16 --nat -ga 1/2/113 -n 10 # Routing java -cp <file>.jar li.pitschmann.knx.examples.read.Main --routing -ga 1/2/113 -n 10
For development with KNX Core there is a dedicated page available.
For plugin there is a dedicated page available.