The Calimero Project

Free KNX network libraries

client - server - device
View on GitHub

The Calimero Project provides Java libraries of the KNX protocol stack for clients, KNXnet/IP servers, and KNX devices.

!
NEW  KNX IP Secure (UDP) in Calimero v2.5 (snapshots)
  • Server support for client-side KNX IP Secure
  • Core library supports KNX IP Secure Tunneling, Routing, Device Management

The libraries' objectives are to offer clean and lean interfaces to KNX functionality, including

  • KNXnet/IP (secure) tunneling, routing, local device management, and bus monitoring
  • KNX IP, KNX USB, KNX RF USB, TP-UART, and FT1.2 access
  • Process communication
  • Management procedures
  • KNX property access
  • Datapoint type and property type translation
  • Network buffering for state- and command-based datapoint values
  • A protocol API that resembles OSI layers 2 to 7
!
With the exception of KNX IP 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. The libraries are compatible with Java Standard-Edition (J2SE) environments commonly deployed on home computers. Minimum Java Runtime Environment (JRE) requirements:

  • Versions ≤ 2.3 require J2ME CDC FP
  • Version 2.4 requires JRE 8 (profile compact1)
  • Version 2.5 (dev) requires JRE 9 (java.base), recommended JRE 11 (java.base)
    • 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-x.jar is required.

      Show information about the core library on the command-line:
      $ java -jar "calimero-core-2.5-SNAPSHOT.jar"

      Setup

      For running Java programs, you need a Java Runtime Environment (JRE), together with any other third party libraries you might want to use. Runtimes are available for download from Oracle, as Open JDK builds, 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.

      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

      Calimero tools are executed in the terminal. Starting a search for KNXnet/IP devices is done via (replace x with your version):
      $ java -cp "calimero-x.jar;calimero-tools-x.jar" tuwien.auto.calimero.tools.Discover -s
      !
      On Windows, the classpath entries of -cp are separated by a ;, on Linux/MacOS : is used.