Quickstart

Calimero Contents

Home
License
Download
Quickstart
Documentation
Support
Miscellaneous
Links

Calimero Quickstart

• Calimero Quickstart
  • Project Structure
  • Setup
  • Usage
  • Try it out
    • Discover your KNX network
    • Low-level listening to the KNX network
    • Take control over your components

This page helps you to get started with Calimero quickly. Its focus is to convince you that Calimero is suitable as communication layer for your KNX project. Since Calimero is a library for communicating with KNX devices from Java, do not expect fancy GUI applications that are ready for end-user consumption. The tools being described here are merely tech demos that show the capabilities of the library and prove that it does what is expected to do.

Project Structure

The project is structured into several repositories. Calimero Core is the main Java library. Being a library, you can not "start" or "run" it like an ordinary application. (To do this, you might refer to the Calimero Tools or the GUI). The library contains functionality to be invoked by user applications. It requires KNX capable endpoints and some UI/task. Nevertheless, the library contains a method main (tuwien.auto.calimero.Settings.main). It is used to show information about the library itself, like a header and version, which can also be queried directly through methods of class Settings. To run applications which just use the Calimero library, only calimero-x.jar is required.

Show information about the library in the terminal:

$ java -cp "calimero-x.jar" tuwien.auto.calimero.Settings

Setup

For running Java programs, you need a Java Runtime Environment (JRE), together with any other third party libraries you might want to use. For details how to set up Java, refer to dedicated SDK installation sites, for example the Java installation guide.

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 and build it.

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 : is used.

Try it out

The following steps assume that you have the Calimero Core and Tools JAR files (e.g., calimero-2.0.4.jar and examples/calimero-tools-2.0.2.jar) available, either because you built them yourself or because you got them from the distribution package.

 

Discover your KNX network

The first tool to check is tuwien.auto.calimero.tools.Discover. Its purpose is to find the route to the gateway to the KNX network from the local PC it is running on. The result Discover returns is required for invoking any other tools.

Discover has the followig options:

java tuwien.auto.calimero.tools.Discover -help

usage: Discover [options]
options:
 -help -h                show this help message
 -version                show tool/library version and exit
 -localport <number>     local UDP port (default system assigned)
 -nat -n                 enable Network Address Translation
 -timeout -t             discovery/description response timeout
 -search -s              start a discovery search
 -interface -i <IF name | host name | IP address>
      local multicast network interface for discovery or
      local host for self description (default system assigned)
 -description -d <host>  query description from host
 -serverport -p <number> server UDP port for description (default 3671)

The option -search starts a discovery run:

java tuwien.auto.calimero.tools.Discover -search

This command searches all interfaces of your local computer for connnection to a KNX/IP gateway. If the search is successful, it returns something like the following (depending on your actual hardware):

local address /192.168.178.73
control endpoint IPv4 UDP host 192.168.178.23 port 3671
device 1.1.0 "KNX IP Router 750"
KNX medium TP1
installation 0 project 0 (project installation ID 0)
routing multicast address /224.0.23.12
MAC address 00-24-6d-00-39-04
S/N 0x00c5010012d1

This roughly means, that a "KNX IP Router 750" was found with KNX hardware address "1.1.0" that can be contacted through IP address "192.168.178.23" on port "3671". The information about the local address (which identifies the interface that was used for communication) is currently not printed (see Ticket #21). However, if your local machine has multiple network interfaces, it is essential to pass this information to the tools expained in the following steps.

 

Low-level listening to the KNX network

The tool java tuwien.auto.calimero.tools.NetworkMonitor allows to listen on the KNX bus in a low-level fashion. It has the following options:

java tuwien.auto.calimero.tools.NetworkMonitor -help

2013-10-12 22:04:15,453 always, tools: usage: NetworkMonitor [options] <host|port>
options:
  -help -h                show this help message
  -version                show tool/library version and exit
  -verbose -v             enable verbose status output
  -localhost <id>         local IP/host name
  -localport <number>     local UDP port (default system assigned)
  -port -p <number>       UDP port on host (default 3671)
  -nat -n                 enable Network Address Translation
  -serial -s              use FT1.2 serial communication
  -medium -m <id>         KNX medium [tp0|tp1|p110|p132|rf] (default tp1)

Note: If you have a KNX/IP router instead of a simple KNX/IP interface (as in the example above), the NetworkMonitor cannot be used, since a router is not able to provide low-level listening access to the network, see Ticket #22.

Using the information from the discovery run above, you can start the NetworkMonitor using the following command line (with addresses and ports adjusted to the results from the discovery run above). If your local machine has multiple IP interfaces (such as LAN and WLAN, etc.) make sure to pass in the option -localhost to identify the network interface to use for communication. Using the wrong interface, the connection would simply time out, otherwise.

java tuwien.auto.calimero.tools.NetworkMonitor -localhost 192.168.178.73 -p 3671 192.168.178.23

 

Take control over your components

It's time to switch your lights on, tuwien.auto.calimero.tools.ProcComm demonstrates how to do. The following command line options are supported:

java tuwien.auto.calimero.tools.ProcComm -help

usage: ProcComm [options] <host|port>
options:
  -help -h                show this help message
  -version                show tool/library version and exit
  -verbose -v             enable verbose status output
  -localhost <id>         local IP/host name
  -localport <number>     local UDP port (default system assigned)
  -port -p <number>       UDP port on <host> (default 3671)
  -nat -n                 enable Network Address Translation
  -routing                use KNX net/IP routing (always on port 3671)
  -serial -s              use FT1.2 serial communication
  -medium -m <id>         KNX medium [tp0|tp1|p110|p132|rf] (default tp1)
Available commands for process communication:
  read <DPT> <KNX address>           read from group address
  write <DPT> <value> <KNX address>  write to group address
Additionally recognized name aliases for DPT numbers:
  switch (1.001), bool (1.002), string (16.001)
  float (9.002), ucount (5.010), angle (5.003)
completed, null

Assuming that an actuator is listening for group address 1/1/5 for switching a light, you can switch it on using the following command (assuming the same communication parameters as above):

java tuwien.auto.calimero.tools.ProcComm -localhost 192.168.178.73 \
   192.168.178.23 write bool true 1/1/5

If the device supports reading out the current actuator state, using the same group address, you can determine the current state of the light by issuing a read command:

java tuwien.auto.calimero.tools.ProcComm -localhost 192.168.178.73 \
   192.168.178.23 write read bool 1/1/5

In the same way, you can move shutters or position heating valves by sending integer values to the bus. The following example sends the value 128 to the group address 1/3/7. If a shutter actuator uses the address for the position, the shutter would go down to 50%:

java tuwien.auto.calimero.tools.ProcComm -localhost 192.168.178.73 \
   192.168.178.23  write ucount 128 1/3/7