Calimero Project

Free KNX network library

client - server - device

View on GitHub

The Calimero project provides the KNX protocol stack for clients, KNXnet/IP servers, and devices.

!
 NEW  Calimero v2.5 supports KNX IP Secure & Data Secure

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
  • 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
  • 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. The library is 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 requires 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 is required.

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 as Open JDK builds, or 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.

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/library provides further details on invocation, as well as using Gradle and Maven for building and execution.

Show information about the core library on the command-line: 
$ java -jar "calimero-core-2.6-SNAPSHOT.jar"
Calimero tools are executed in the terminal. Starting a search for KNXnet/IP devices is done via: 
$ java -cp "calimero-2.6-SNAPSHOT.jar;calimero-tools-2.6-SNAPSHOT.jar" tuwien.auto.calimero.tools.Discover search
!
 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.