Skip to content

Find what you have

Find out what your project holds, which devices answer on the bus, and what bussard can do with each of them. Every command here reads; none of them changes a device.

Audit the installation

An illustrative exchange:

You:        What do I have, and what needs attention?
Assistant:  (calls knx_audit)
            38 devices on line 1.1, 214 group addresses, 402 links.
            bussard can plan and apply 36 devices; 2 older ones can
            only be described. 12 group addresses have no type.

knx_audit returns the same report as the terminal command. With the server's key store it also says which Secure devices it covers.

$ bussard audit
Your project
  project: my-house   imported from: my-house.knxproj
  38 devices, 214 group addresses, 402 links
    line 1.1: 38 devices
...
Devices per mask
  07B0 System B (29 devices): bussard can: plan/apply, flash, reconstruct, describe
  0705 System 7 (7 devices): bussard can: plan/apply, flash, reconstruct, describe
  0012 System 1 (2 devices): bussard can: describe only

Add --keyring <file.knxkeys> (password in BUSSARD_KEYRING_PASSWORD) to see which Secure devices your keyring covers. --json prints the same report as one object.

The first section is the project summary: name, import source, and the count of devices, group addresses and links per line. Below it audit lists what needs attention:

  • devices without a name or a location
  • group addresses without a type (DPT) or a name
  • links to com objects the device file does not declare
  • one-sided links: a group address with senders but no listener, or the reverse
  • protected group addresses and KNX Secure devices

"Devices per mask" groups devices by their mask, the device's system generation, and says what bussard can do with each. A device marked describe only cannot be programmed by bussard.

Unlinked com objects and unused group addresses are counted, not flagged. Actuators ship far more objects than a house uses, and an unused group address is a reserve.

Check the live bus

You:        Check the live bus too.
Assistant:  (calls knx_audit with live: true)

The live audit adds the interface's tunnel slots and a traffic sample from the telegrams the server has seen.

$ bussard audit --live

--live adds three things: the gateway's tunnel budget, a traffic sample over --window seconds (default 30), and a probe of every device in your project, one at a time.

It sends only management reads to single devices, never a group telegram, so no light switches.

See which devices are on a line

You:        Which devices answer on line 1.1?
Assistant:  (calls knx_find_devices, then knx_job_status until done)
            3 devices answered. 2 are in your project; the blind actuator
            MDT JAL-0810.03 at 1.1.47 is not. Every device of your
            project on this line answered.

knx_find_devices runs the scan as a job, so the assistant checks back with knx_job_status while it runs. A server started with --passive does not offer it.

$ bussard scan 1.1
Address  Product                   Serial number  Secure  In project
1.1.1    MDT BE-06001.02           0083000A1B2C           yes
1.1.4    Albrecht Jung 23024 1S R  00020011AB34   🔒      yes
1.1.47   MDT JAL-0810.03           0083001F00E1           no

3 devices found · 256 addresses in 52 s · 253 did not answer within 3 s · 1 not in your project

Next steps
  → bussard describe 1.1.47
    shows what a device that is not in your project is

Narrow the scan with --from and --to (device numbers 0 to 255). The line defaults to 1.1.

The summary is the point: which devices are in your project, which are not, and which devices of your project did not answer. A serial number the scan saved to your project is marked (saved). Piped into a file or with NO_COLOR set, the output has no colour and the lock reads secure. The scan probes one address at a time, because most gateways handle one device session at a time, so a full line can take a while.

Look inside one device

You:        What does the Jung actuator 1.1.4 actually carry?
Assistant:  (calls knx_reconstruct_device)
            Its tables match your project, except one group address the
            device has and your project does not.
You:        And what does it report about itself?
Assistant:  (calls knx_describe_device)

knx_reconstruct_device reads the link tables back and compares them with your project. knx_describe_device lists the interface objects and properties. With the server's key store a Secure device is read with its tool key.

$ bussard describe 1.1.4

describe lists the device's interface objects and every property it reports, with type, size and access level. A Secure device needs its tool key: pass --keyring.

$ bussard reconstruct 1.1.4

reconstruct reads the device's link tables back and compares them with your project, group addresses per com object. Give it --product <file.knxprod>, or let it use the product data the lock pins, and it also decodes the parameters that differ from the vendor default and from your project.

Use the description on an unknown device during commissioning. Neither form writes. A Secure device that answers only under its factory key from the key store was reset or never commissioned; bussard says so, and you commission it with ETS and import the new ETS keyring.

The read-back cannot tell send from listen, because many devices do not expose that. It refuses a device whose mask it cannot read; the audit shows which devices allow it. To build a new project from what a whole line carries, see Add a device.

Check one device's identity

You:        Is the IP interface still the device my project expects?
Assistant:  (calls knx_show_device with live: true)

The live form of knx_show_device reads the device over the bus and adds its mask, its identity against the lock and, for an IP interface, its IP settings and tunnelling addresses.

$ bussard status 1.1.250

With an address, status reads the device's mask and identity and compares them with the lock. For a KNX IP interface it also prints its IP settings, tunnelling addresses and state, and each difference from the device file. Without an address, status shows the changes to your project not yet written to any device (see Change what a button does).

Get past "no free tunnelling connection"

error: 192.0.2.10:3671 has no free tunnelling connection (E_NO_MORE_CONNECTIONS).

Your IP interface has a fixed number of tunnelling slots, often one to five. A tunnelling slot is one client connection; each connected program holds one for as long as it runs:

  • Home Assistant's KNX integration, permanently
  • ETS, while a project is online
  • bussard viz, bussard mcp, or any other bussard command still running

When all are taken, bussard says so and exits with code 4 instead of timing out. Retrying does not help until a slot is free. Stop one of the other clients, or wait about two minutes for a crashed client's slot to time out. A long-running observer can use routing (--routing) instead, if your interface supports multicast. bussard init --gateway <ip> and bussard audit --live print N tunnels, M in use when the interface reports it.

A bussard write never retries into a full interface, so the refusal comes before anything reaches a device.

Next steps