Calimero Project

Free KNX network library

client - server - device

View on GitHub

Calimero provides the KNX (secure) protocol stack for clients, KNXnet/IP servers, and devices.

The library's objective is to offer clean and lean interfaces to KNX functionality, including

  • KNXnet/IP (secure) tunneling, routing, local device management, and bus monitoring
  • Access over KNX IP, KNX USB, KNX RF USB, TP-UART, and FT1.2
  • Process communication
  • Management procedures
  • KNX property access
  • Datapoint type and property type translation
  • Network buffering for state- and command-based datapoint values
  • BAOS (Bus Access Object Server) client support (protocol v2.1)
  • A protocol API that resembles OSI layers 2 to 7
!
 With the exception of KNX Secure, KNX communication protocols do not offer features of cryptographic protocols, e.g., entity authentication. If you intend to permit external access, ensure security policies by applying appropriate mechanisms, e.g., use a virtual private network (VPN).

Calimero is designed to operate on embedded systems. Minimum Java runtime requirements:

  • Versions ≤ 2.3 require J2ME CDC FP
  • Version 2.4 requires JRE 8 (profile compact1)
  • Version 2.5 requires JDK 11 (java.base), support for KNX IP Secure & Data Secure
  • Version 3.0 (snapshot) requires JDK 17 (java.base), Java module support

Project Structure

The project is structured into several repositories. Calimero-core is the main Java library. (Being a library, you can not simply "run" it like an ordinary application. For that, use the calimero-tools or calimero-gui repositories). The core library contains functionality to be invoked by a user application. A setup also requires KNX capable endpoints, e.g., a KNXnet/IP server. To create applications which just use client functionality, only calimero-core is required.

Setup

For running Java programs, you need a Java runtime, together with any other third party libraries you might want to use. Runtimes are available for download from Oracle and other vendors.

Put the Calimero *.jar files (or the extracted class folders) into the classpath searched by the Java class loader or into the current working directory. One way to extract a jar file into your working directory using the terminal: 

$ jar -xf my-library.jar
Alternatively, import the Calimero source code into your development environment.

The README of each repository provides further details building Calimero using Gradle.

When using KNXnet/IP and network interfaces, make sure that

  • you configured the network interfaces correctly,
  • you are using the intended network interface,
  • firewall settings don't block KNXnet/IP traffic.

The first two points are especially relevant on multi-homed computers, i.e., those having several installed network interfaces. Take care with NAT (Network Address Translation) and IPv6 addresses, because KNXnet/IP works with IPv4 by default.

!
 Giving preference to IPv4 using -Djava.net.preferIPv4Stack=true as Java VM argument can avoid address assignment problems on some operating systems.

Please refer to dedicated documentation for your particular execution environment.

Usage

The README of each Calimero repository provides further details on invocation, as well as using the Gradle build tool for execution.

Show information about the core library on the command-line: 
$ java -jar "calimero-core-3.0-SNAPSHOT.jar"
Calimero 3.0 is modularized; using the Java module system, the command-line would look like this: 
$ java -p . -m io.calimero.core
Calimero tools are executed in the terminal. Starting a search for KNXnet/IP devices is done via: 
$ java -cp "calimero-core-3.0-SNAPSHOT.jar;calimero-tools-3.0-SNAPSHOT.jar" io.calimero.tools.Discover search
Or, using the module path: 
$ java -p . -m io.calimero.tools discover
!
 On Windows, the classpath entries of -cp are separated by a ;, on Linux/MacOS : is used.

Docker images

Calimero tools and Calimero server are also available as Docker images on Docker Hub.