Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/calimero-project/calimero-tools

A collection of KNX network tools for device discovery, process communication, and monitoring
https://github.com/calimero-project/calimero-tools

cli command-line java knx

Last synced: about 5 hours ago
JSON representation

A collection of KNX network tools for device discovery, process communication, and monitoring

Host: GitHub
URL: https://github.com/calimero-project/calimero-tools
Owner: calimero-project
License: other
Created: 2012-12-05T15:23:50.000Z (almost 12 years ago)
Default Branch: master
Last Pushed: 2024-08-18T15:39:01.000Z (about 2 months ago)
Last Synced: 2024-08-19T15:06:57.217Z (about 2 months ago)
Topics: cli, command-line, java, knx
Language: Java
Homepage:
Size: 2.21 MB
Stars: 32
Watchers: 13
Forks: 19
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE.txt

Awesome Lists containing this project

README

# Calimero Tools [![Java CI with Gradle](https://github.com/calimero-project/calimero-tools/actions/workflows/gradle.yml/badge.svg)](https://github.com/calimero-project/calimero-tools/actions/workflows/gradle.yml)

~~~ sh
git clone https://github.com/calimero-project/calimero-tools.git
~~~

A collection of KNX network tools based on Calimero for (secure) process communication, monitoring, and management.

With Maven, execute

$ mvn install

With Gradle, execute

./gradlew build

### Docker image

Pre-built Docker images for running the tools are available on [Docker Hub](https://hub.docker.com/r/calimeroproject/knxtools).

Available Tools
---------------
Use `./gradlew run` or `mvn exec:java` to list available commands.

* Discover - KNXnet/IP discovery and self description
* DeviceInfo - shows device information of a device in a KNX network (using the device's interface objects)
* IPConfig - read/write the IP configuration of a KNXnet/IP server using KNX properties
* NetworkMonitor - busmonitor for KNX networks (monitor raw frames on the network, completely passive)
* ProcComm - process communication, read or write a KNX datapoint, or group monitor KNX datapoints
* ProgMode - shows the KNX devices currently in programming mode
* PropClient - a property client for KNX device property descriptions, get or set KNX device properties
* Property - get/set a single KNX device interface object property
* BaosClient - communicate with a KNX BAOS device
* ScanDevices - list KNX devices, or check whether a specific KNX individual address is currently assigned to a KNX device
* Restart - performs a basic restart or master reset of a KNX interface or KNX device
* DatapointImporter - import datapoint information from a KNX project (.knxproj) or group addresses file (.xml or .csv) for use with Calimero

Examples
-------------

Note, using KNX Secure requires a keyring (`--keyring`) and keyring password (`--keyring-pwd`); by default the keyring in the current working directory is used. Alternatively, for KNX IP Secure, the following command-line options are supported:

* Secure Multicast: `--group-key` _<16 bytes hex key>_
* Secure Unicast:
* `--user` _<user ID>_
* `--user-pwd` _<pwd>_, or `--user-key` _<16 bytes hex key>_
* (optional) `--device-pwd` _<auth>_, or `--device-key` _<16 bytes hex key>_

### Using Gradle

Show all supported tools

./gradlew run

Discover KNX IP devices

./gradlew run --args discover

Run group monitor (using KNXnet/IP Routing)

./gradlew run --args="groupmon 224.0.23.12"

Use `-h` or `--help` for help with a tool (here, _scan_ for scanning devices)

./gradlew run --args="scan -h"

KNX IP Secure multicast group monitor using a keyring

./gradlew run --args="groupmon 224.0.23.12 --keyring mykeys.knxkeys --keyring-pwd quack"

### Using Maven

Show all supported tools

mvn exec:java

Run a command with option `--help` to show the help message for usage

mvn exec:java -Dexec.args="groupmon --help"

The equivalent of the above command using explicit invocation would be

mvn exec:java -Dexec.mainClass=io.calimero.tools.ProcComm -Dexec.args="--help"

**Discover KNXnet/IP devices**

~~~ sh
# Variant which executes the `discover` command
$ mvn exec:java -Dexec.args=discover

# Variant which specifically refers to the tool class
$ mvn exec:java -Dexec.mainClass=io.calimero.tools.Discover -Dexec.args=--search
~~~

**Process Communication**

Start process communication for group monitoring (command `groupmon`), accessing a KNX power-line network (`--medium p110` or `-m p110`) using a USB interface with name `busch-jaeger` (or any other KNX vendor or product name, e.g., `siemens`).

mvn exec:java -Dexec.args="groupmon --usb busch-jaeger -m p110"

With USB, you can also specify the USB interface using the vendor and product ID as `VendorID:ProductID`. If you don't know any identification yet, run the tool using a bogus ID and debug settings to print the available USB interfaces.

Start process communication for group monitoring, accessing a RF network using a Weinzierl USB interface. Adjust the logging level for `debug` output:

mvn exec:java -Dexec.args="groupmon --usb weinzierl -m rf" -Dorg.slf4j.simpleLogger.defaultLogLevel=debug

**Local Device Management**

Access the KNX properties of your KNXnet/IP server with control endpoint `192.168.10.10` using _local_ device management

mvn exec:java -Dexec.args="properties 192.168.10.10"

**Remote Device Management**

Remote property services (this example only works if the KNX device implements _Interface Objects_): open a client to a remote (`-r`) KNX device with the device address `1.1.5`, via KNXnet/IP tunneling to a KNXnet/IP server with control endpoint `192.168.10.10`

mvn exec:java -Dexec.args="properties 192.168.10.10 -r 1.1.5"

Once you enter the CLI of the property client, execute, e.g., `scan all` to scan all KNX properties of that device.

### Using Java

Replace the version in the examples (3.0-SNAPSHOT) with the exact version you are running. Make sure all dependencies are available, either by relying on the Calimero Tools MANIFEST file or the [Java class path](https://docs.oracle.com/javase/8/docs/technotes/tools/windows/classpath.html) settings (using the `-classpath` option or the [CLASSPATH](https://docs.oracle.com/javase/tutorial/essential/environment/paths.html) environment variable). The simplest way is to have all required `.jar` files in the same directory.

For an overview of tools, run

java -jar calimero-tools-3.0-SNAPSHOT.jar

**Discover KNXnet/IP devices**

Discover KNXnet/IP servers, with Network Address Translation (NAT) enabled:

java -jar calimero-tools-3.0-SNAPSHOT.jar discover search --nat

**Process Communication**

Read a KNX datapoint value (switch button on/off) from a group address (`1/2/1`) using the FT1.2 protocol over the serial port `/dev/ttyS01`

java -jar calimero-tools-3.0-SNAPSHOT.jar read switch 1/2/1 --ft12 /dev/ttyS01

Start process communication group monitoring for a TP1 KNX network (the default) using KNXnet/IP Routing in the multicast group `224.0.23.12`, and a specific local host address (`--localhost`, useful in multihoming to specify the outgoing network interface)

java -jar calimero-tools-3.0-SNAPSHOT.jar groupmon --localhost 192.168.10.14 224.0.23.12

**Busmonitor**

Start a KNX busmonitor on a KNX TP1 (Twisted Pair) network, using a compact (`-c` or `--compact`) busmonitor indication output format

java -jar calimero-tools-3.0-SNAPSHOT.jar monitor -c --usb busch-jaeger

Calimero busmonitor output in compact mode looks like

~~~ sh
02:22:09.457 Seq 0 L-Data.req 7.1.13->2/1/0, low priority FCS 0x4e domain 0x6f, tpdu 00 81: T_Group, A_Group.write 01
02:22:09.475 Seq 1 ACK
02:22:09.810 Seq 2 L-Data.req 7.1.13->2/1/20, low priority FCS 0xa7 domain 0x6f, tpdu 00 80 ff: T_Group, A_Group.write ff
02:22:09.828 Seq 3 ACK
02:22:10.726 Seq 4 L-Data.req 7.1.13->2/1/11, low priority FCS 0x44 domain 0x6f, tpdu 00 80: T_Group, A_Group.write 00
02:22:10.744 Seq 5 ACK
~~~

**Device Information**

Read device information of KNX device `1.1.4` in a TP1 network (default medium) using the KNXnet/IP server `192.168.10.12`

java -cp "calimero-tools-3.0-SNAPSHOT.jar" devinfo 192.168.10.12 1.1.4

Run tools using Gradle without source code
-------

With Gradle installed, copy the following snippet into a file named *build.gradle*, and execute `gradle` in the same directory (see [Examples](#Examples), e.g., `gradle run --args="monitor 192.168.115.6"`).

```gradle
plugins { id 'application' }
repositories { mavenCentral() }
mainClassName = "io.calimero.tools.Main"
dependencies {
runtimeOnly group: 'io.calimero', name: 'calimero-tools', version: '3.0-SNAPSHOT'
}
```

Logging
-------

Calimero tools use the [System.Logger](https://docs.oracle.com/en/java/javase/19/docs/api/java.base/java/lang/System.Logger.html). Bind any desired logging frameworks of your choice.

Extending Tools
---------------

All tools implement the interface `Runnable` and can be extended.
Override the method that provides the result and customize its behavior. For example, with KNXnet/IP discovery

```
public class MyDiscovery extends Discover {
public MyDiscovery(String[] args) throws KNXException {
super(args);
}

@Override
protected void onEndpointReceived(Result result) {
// Use result ...
}
}
```