Reference on Tinkerbus

File formats

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

Read

Format	Use	Notes
`.knxproj`	ETS 6 project	An outer zip that holds the project as an inner zip, which is password-protected for protected projects, plus an information file. ETS 6 layout only; other layouts are refused.
`.knxprod`	Manufacturer product data	Also zip files that contain a knxprod (some manufacturers deliver them that way). The signature of product data is not verified.
`knx_master.xml`	Datapoint type layouts and manufacturer names	Used from the project when it carries one, or downloaded once on request from `update.knx.org`, and stored in the catalog folder.
Group address CSV	Import	ETS CSV export. Group addresses can be three-level (`1/2/3`), two-level (`1/200`) or a plain number.
Group address XML	Import	The group address export XML.
tshark text output	`knxcap`	Tab separated fields of a KNXnet/IP capture. See knxcap.
`.pcapng`, `.pcap`	Reports	A packet capture of an ETS download, read in the application to make an anonymized transcript. Not kept. See Reports to the project.

Written

Format	Written by	Notes
`.knxproj`	Save, Save as, Start from scratch	Save replaces the project file after backing up the previous version; Save as writes a new file; Start from scratch writes an empty project. Changed content invalidates the ETS signature. See Saving.
Group address CSV (ETS 5.7 and later)	Group addresses > Import/Export
Group address XML	Group addresses > Import/Export
Device list CSV	Devices & places > Export	Devices with their place.
HTML report	Reports	One self-contained HTML file, to print or save as PDF from a browser.
Telegram CSV	Monitor > Export, Monitor > Record	Columns: Time, Source, Source name, Destination, Destination name, Service, Data type, Value, Raw value, Confirmation. A recording never replaces an existing file.
Backup of device memory	`knxprogram`, Programming > Check	A text file named `backup-<serial>-<date>-<time>.txt`. It records the memory of the device before the load.
`settings.json`, `downloads.json`	The application	See Settings.
Report file (`.zip`)	A report > Save report file	`report.md` and, if you read a capture, `transcript.txt`. See Reports to the project.
`-xml` output	`knxdownload -xml`	The application program of a device as XML.
Raw archive entry	`knxproj -extract`	One entry of the inner project archive.

Files that Tinkerbus writes are created with restrictive permissions where they may hold secrets (the settings file is mode 0600).

Settings

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

Location

The application keeps its state in your user configuration folder, in a folder named tinkerbus. The folder comes from the operating system: ~/.config/tinkerbus on Linux (or $XDG_CONFIG_HOME/tinkerbus), %AppData%\tinkerbus on Windows, ~/Library/Application Support/tinkerbus on macOS. If the system has no configuration folder, nothing is saved.

Path	Content
`tinkerbus/settings.json`	Settings, below. Written atomically with mode 0600; the folder is mode 0700.
`tinkerbus/catalog/`	Imported `.knxprod` files and `knx_master.xml`.
`tinkerbus/downloads.json`	What is known about the last download of each project device, by project id and device id: a fingerprint of the image that was loaded, or “never” for devices added from the catalog. See the download reminder. Names and comments are not part of it.
`tinkerbus/backups/projects/`	The previous version of a project file, copied before Save replaces it (`<name>-<date>-<time>.knxproj`). The last five per project name are kept.
`tinkerbus/backups/`	The memory backups of devices written by the Programming check and `knxprogram`.

A damaged settings.json is treated as empty and replaced the next time something is saved.

Protocols and data types

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

The bus protocol code lives under internal/falcon, the datapoint code under internal/dpt.

KNXnet/IP

Part	Status
Search (multicast) and description of a gateway	Implemented, used by the application and `knxprobe -discover`, `-describe`
Tunnelling over UDP	Implemented, with unit tests, and used against real gateways in development
Tunnelling over TCP (KNXnet/IP v2)	Implemented, with unit tests. A gateway closes a tunnel that stays silent for about two minutes, so the connection state request is sent every 60 seconds on TCP as on UDP, and the tunnel is closed when the gateway does not answer
Device management connection	Implemented (reading and writing the gateway’s own interface objects). The tools use it to open and close a connection only
Routing (multicast, default `224.0.23.12:3671`)	Implemented in the library (at most 50 frames per second, busy handling). Not used by the application or the tools. Not tested on hardware
IP Secure (secure sessions, secure routing)	Not implemented. It would need the specification or a secure gateway to test against, and nothing is guessed

cEMI and application layer

Frames are decoded and built as cEMI L_Data requests, confirmations and indications. The application layer covers group value read, response and write, and the management services the programming code uses: