Command line tools on Tinkerbus

knxproj

Mon, 01 Jan 0001 00:00:00 +0000

knxproj reads a .knxproj file and prints information about it. It never touches the bus and never changes the file.

knxproj [-pwfile FILE] [-list] [-extract NAME -out FILE] project.knxproj
knxproj [-pwfile FILE] -device 1.1.21 [-params] project.knxproj
knxproj [-pwfile FILE] -ga 3/0/10 project.knxproj

Flags

Flag	Meaning
`-pwfile FILE`	File holding the project password. Without it the environment variable `KNXPROJ_PASSWORD` is used.
`-list`	List the entries of the outer and inner archive, with their sizes.
`-device ADDR`	Print this device (for example `1.1.21`): product, manufacturer, place, comment, description, and its group objects with flags, data type and linked group addresses.
`-params`	With `-device`: also print the parameter pages with their values.
`-ga ADDR`	Print this group address (for example `3/0/10`) with its name, data type, range, and the devices and objects linked to it.
`-extract NAME`	Write this inner entry to the file given by `-out`.
`-out FILE`	Output file for `-extract`. Written with mode 0600.

With none of -list, -extract, -device or -ga, it prints the project name and whether it is password protected.

knxprobe

Mon, 01 Jan 0001 00:00:00 +0000

knxprobe finds KNXnet/IP gateways and opens a tunnel. By default it only listens. A few options send requests to the bus; they are marked below. It never writes to a device.

knxprobe -discover
knxprobe -addr HOST:PORT -describe
knxprobe -addr HOST:PORT [-tcp] [-for 30s] [-trace]
knxprobe -addr HOST:PORT [-read GA | -info DEV | -prop DEV:OBJ:PID[:START[:COUNT]] | -mem DEV:ADDR:LEN | -scan LINE | -progmode]
knxprobe -usb-list

Flags

Flag	Default	Meaning
`-addr HOST:PORT`	none	The KNXnet/IP gateway. Required, except for `-discover` (multicast) and `-usb-list`.
`-tcp`	off	Tunnel over TCP instead of UDP.
`-for DURATION`	`10s`	How long to listen (for example `30s`, `5m`). Interrupt with Ctrl+C to stop earlier.
`-trace`	off	Print every KNXnet/IP frame sent and received.
`-discover`	off	Multicast search for gateways, print them, and exit.
`-unicast`	off	With `-discover`: send the search request to `-addr` instead of multicasting.
`-describe`	off	Describe the gateway at `-addr` and exit.
`-usb-list`	off	List plugged-in KNX USB interfaces and exit. Linux only.
`-mgmt`	off	Open a device management connection, hold it briefly, close it. Reads and writes nothing.

Options that send telegrams (read-only requests), used after the tunnel is open:

knxdownload

Mon, 01 Jan 0001 00:00:00 +0000

knxdownload builds the memory image (and for some devices the load plan) that a project device should hold, and can compare it with the real device. It only reads: nothing is ever written to a device by this tool.

knxdownload -pwfile FILE -device 1.1.21 [-dump] [-plan] project.knxproj
knxdownload -pwfile FILE -device 1.1.21 -verify GATEWAY [-tcp] [-all] project.knxproj
knxdownload -pwfile FILE -device 1.1.21 -from-dump DIR [-all] project.knxproj
knxdownload -pwfile FILE -device 1.1.21 -xml out.xml project.knxproj

Flags

Flag	Meaning
`-pwfile FILE`	File holding the project password.
`-device ADDR`	Individual address of the project device. Required.
`-dump`	Print the image: each segment as hex.
`-plan`	Print the load plan, every operation a download would perform, and exit. Nothing is sent.
`-verify GATEWAY`	Connect through this gateway, read the device’s memory (read-only) and compare it with the image. For System B devices (mask `0x07B0`) it compares the load images by size and checksum instead.
`-tcp`	Tunnel over TCP instead of UDP.
`-from-dump DIR`	Compare against saved reads in a directory (files named `0xADDR.txt`, as printed by `knxprobe -mem`) instead of the bus.
`-all`	Print every difference, not only the first 40.
`-xml FILE`	Write the application program of the device to this file and exit.

The output starts with the application program name, number and version, the mask, each segment with its address and size, and any notes and WARNING lines from building the image. With -verify or -from-dump it then prints the number of differing octets per segment and the differences (image value, device value, mask).

knxprogram

Mon, 01 Jan 0001 00:00:00 +0000

knxprogram loads the configuration of a project device into a real device. It can assign an individual address to a device in programming mode first, runs the load procedure of the application program, and verifies the result.

Without -write it only reads: it checks the device, saves a backup of its memory (when -backup is given) and prints the plan. With -write it changes the device, and it refuses to start unless it was told which device it is (-expect-serial) and where the backup goes (-backup). Read safety and the workflow before using -write.

knxcap

Mon, 01 Jan 0001 00:00:00 +0000

knxcap prints the KNX telegrams of a tunnelling capture, decoded. It is a development tool, used to compare what another tool sends with what Tinkerbus would send, and to create the capture fixtures the tests use. It does not touch the bus.

It reads the tab separated output of

tshark -r FILE.pcap -Y 'tcp.port==3671 && tcp.len>0' -T fields \
 -e frame.number -e frame.time_relative -e ip.src -e tcp.payload

from standard input, or from the file named on the command line.