knxprogram

Load a project device into a real KNX device. Reads only unless -write is given.

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.

knxprogram -pwfile FILE -gateway HOST:PORT -from 1.1.20 -target 1.1.32 -expect-serial 00E1:03925BC3 [options] project.knxproj

-from, -target, -expect-serial and the project file are required.

Flags

Flag	Meaning
`-pwfile FILE`	File holding the project password.
`-gateway HOST:PORT`	KNXnet/IP gateway. Required: there is no default.
`-tcp`	Tunnel over TCP.
`-from ADDR`	The project device whose settings are loaded, for example `1.1.20`.
`-target ADDR`	The individual address the device has afterwards, for example `1.1.32`.
`-assign-from ADDR`	The device has no address yet and answers at this address in programming mode (`15.15.255`): assign `-target` to it first.
`-expect-serial S`	The serial number the device must have, as `00E1:03925BC3`, or `none` for devices of mask `0x0012`, which have none.
`-backup DIR`	Directory for the backup of the device memory. Required with `-write`.
`-full-backup`	Read the whole content of the loaded segments for the backup even where that is slow (a System B device with extended services answers about every 10 seconds). Otherwise only their sizes and checksums are saved.
`-write`	Change the device: perform the plan. Without it nothing is written.
`-no-links`	Load the settings without any group address link, so the device takes part in no group communication.
`-defaults`	Load the defaults of the application program instead of the values stored for `-from`. Implies `-no-links`.
`-partial par\|grp\|both`	Load only part of the settings: `par` (parameters), `grp` (group communication) or `both`. The device must already hold the application program (this is not checked), and the plan follows the downloads ETS makes.
`-allow-warnings`	Load although the image has warnings.

What it prints

The settings of the project device, the program, application number and version, the mask, and the address the device will have.
WARNING: lines, if any.
The steps of the plan.
The image against the device as it is now: how many octets (or load images) differ, and a line per segment. For a router, also the group filter table against the image.
Without -write: “nothing was written (no -write)”. With -write: “CHANGING THE DEVICE in 5 seconds (interrupt to abort)”, then the load, and “the device holds the image” when the load finished without an error.

Examples

Check only (nothing is written, nothing needs -backup):

knxprogram -pwfile pw.txt -gateway 10.0.0.5:3671 \
  -from 1.1.20 -target 1.1.32 -expect-serial 00E1:03925BC3 house.knxproj

Assign an address to a new device and load it:

knxprogram -pwfile pw.txt -gateway 10.0.0.5:3671 \
  -from 1.1.20 -target 1.1.32 -assign-from 15.15.255 -expect-serial 00E1:03925BC3 \
  -backup ./backups -write house.knxproj

Write only the group address links of an IP router (the filter table is part of it):

knxprogram -pwfile pw.txt -gateway 10.0.0.5:3671 \
  -from 1.1.0 -target 1.1.0 -expect-serial 00C5:0123ABCD -partial grp \
  -backup ./backups -write house.knxproj

The serial numbers in the examples are placeholders. Take the real one from knxprobe -info or the application’s Diagnostics.

Limits

Only the mask versions in the verified list are supported. Others are refused.
The overall run has a time limit of 15 minutes.
There is no restore command; the backup is for your own use.