JarCasting
JarCasting JarCasting

KNX Link

Project for KNX Link

License

License
GroupId

GroupId

li.pitschmann
ArtifactId

ArtifactId

knx-link
Last Version

Last Version

0.2.0
Release Date

Release Date
Type

Type

pom
Description

Description

KNX Link
Project for KNX Link
Project URL

Project URL

https://github.pitschmann.li
Source Code Management

Source Code Management

https://github.com/pitschr/knx-link

Download knx-link

Filename Size
knx-link-0.2.0.pom 14 KB
Browse

How to add to project

<!-- https://jarcasting.com/artifacts/li.pitschmann/knx-link/ -->
<dependency>
    <groupId>li.pitschmann</groupId>
    <artifactId>knx-link</artifactId>
    <version>0.2.0</version>
    <type>pom</type>
</dependency>
// https://jarcasting.com/artifacts/li.pitschmann/knx-link/
implementation 'li.pitschmann:knx-link:0.2.0'
// https://jarcasting.com/artifacts/li.pitschmann/knx-link/
implementation ("li.pitschmann:knx-link:0.2.0")
'li.pitschmann:knx-link:pom:0.2.0'
<dependency org="li.pitschmann" name="knx-link" rev="0.2.0">
  <artifact name="knx-link" type="pom" />
</dependency>
@Grapes(
@Grab(group='li.pitschmann', module='knx-link', version='0.2.0')
)
libraryDependencies += "li.pitschmann" % "knx-link" % "0.2.0"
[li.pitschmann/knx-link "0.2.0"]

Dependencies

test (6)

Group / Artifact Type Version
org.junit.jupiter : junit-jupiter-engine jar 5.5.2
org.junit.jupiter : junit-jupiter-params jar 5.5.2
org.junit.platform : junit-platform-runner jar 1.5.2
org.assertj : assertj-core jar 3.14.0
org.mockito : mockito-inline jar 3.2.0
ch.qos.logback : logback-classic jar 1.2.3

Project Modules

  • knx-core
  • knx-core-plugins
  • knx-logic
  • knx-examples

Build Status Coverage Status License: GPL v3 Maven Central

KNX Link

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.

Known limitations

  • 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)

Prerequisites

  • 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 224.0.23.12 multicast address will be used)

Architecture

Architecture

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 --routing argument.

Using tunneling mode we need Network Address Translation (NAT) in some cases; this must be enabled using --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 effect.

KNX Client

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.

DPT Description DPT Description DPT Description
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)
10.xxx Time 20.xxx 8-Bit Enumeration

Quick Start Guides

Send a WRITE request frame to KNX

Class: li.pitschmann.knx.examples.write.Main

Arguments:

  • -ga, --groupAddress the KNX group address which has a write flag
  • -dpt,--dataPointType the KNX Data Point Type
  • -v, --value a sequence of commands that is compatible with KNX Data Point Type argument

Switching lamp on KNX group address 1/2/50

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 times.

Send a READ request frame to KNX

Class: li.pitschmann.knx.examples.read.Main

Arguments:

  • -ga, --groupAddress the KNX group address which has a read flag
  • -n, --loops number of read requests

Read the actual status of a lamp on KNX group address 1/2/113

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

Programming

Core Development

For development with KNX Core there is a dedicated page available.

Plugin Development

For plugin there is a dedicated page available.

Versions

Version
0.2.0
0.1.0
0.0.4
0.0.3
0.0.2
0.0.1