Diagnostics¶
Every code bussard validate and the knx_validate MCP tool report, with its severity. Both run the same rules through one function; the report's checked lists the rule families that ran. For reading a validation report and deciding what to fix first.
bussard validate runs strict parsing first (see Errors), then the rule passes below. validate --json prints {"schema", "diagnostics": [...]}.
Project rules¶
| Code | Severity | Rule |
|---|---|---|
| E001 | warning | A link references a group address not defined in groups.toml. import, apply and the MCP edit tools declare it; validate alone warns. |
| E002 | error | A device file's name does not match its address. |
| E003 | error | A link references a communication object the device does not have. A warning when the device has no object table at all, because nothing can be checked without product data. |
| E004 | error | Conflicting object or DPT sizes on one group address. The main number fixes the format (KNX 03_07_02 §1.1); every fixed-width main type of the §2 overview is sized, and only the variable-length strings (24.x, 28.x) are skipped (#498). |
| W005 | warning | Same size but different DPT main types on one group address (5.001 against 6.010). Subtypes of one main type agree (1.001, 1.005, 1.019 on one 1-bit address is normal in ETS), as does a main type alone (1). |
| I006 | info | More than one sending object on a group address. Normal in KNX: two push buttons on one light, a central function next to a local one. Listed for review. |
| E007 | error | Impossible flags: no C flag, or send without T. |
| I009 | info | An orphaned object: T or W, never linked. |
| I010 | info | A group address defined but never linked. |
| W011 | warning | A group address without a DPT; monitor cannot decode it. |
| E012 | error | The reserved address 0/0/0 defined in groups.toml. |
| E013 | error | A link for a device that has no device file. |
| E014 | error | The same object linked more than once on one device. |
| I015 | info | A group address marked protected = true, listed so a reviewer sees the guarded set. |
| E016 | error | A parameter key is malformed (no @) or not in the product model. |
| E017 | error | A parameter value is invalid: unparseable, out of range, or not an enum member. |
| I017 | info | A parameter value equals the vendor default (redundant). |
| E020 | error | A duplicate group address in groups.toml (both lines), or a duplicate object in a device file. |
| E021 | error | A device has channels, parameters or keyed objects but no lock entry. |
| E022 | error | A device's product differs from its lock entry. |
| E023 | error | An unknown parameter or object key in a channel; the message lists the channel's keys. |
| E024 | error | An object linked to a group address whose main DPT number differs from the object's. |
| E025 | error | send on an object without the T flag, or listen on one without the W flag. Command objects listen, status objects send. |
| E026 | warning | Parameter values could not be checked because the product model is missing. The message names bussard import-product only when no stored archive carries the application; otherwise the product model regenerates automatically. |
| E032 | warning | A device's lock entry names a product (product_sha256) the lock has no [[product]] entry for. |
| E033 | warning | A [[product]] entry names an archive (file) the project folder does not hold. The message names the recovery command for its origin. |
| I048 | info | A group address with a sending object but no listening one: its telegrams go nowhere. bussard audit and the viz problems panel list it as a finding. |
| I049 | info | A group address with a listening object but no sending one: nothing triggers it. Listed as a finding like I048. |
| W050 | warning | A parameter value the device file sets is replaced by a Dynamic <Assign> of the product under the device's current values. The message names the value, the value the <Assign> puts in its place, the parameter it copies and the condition under which it applies. The download writes the assigned value, as ETS does, so this is not an error: set the parameter to the assigned value, or change the condition. plan, flash and the device view name the same value. |
[knxnet] rules¶
| Code | Severity | Rule |
|---|---|---|
| E043 | error | An IP interface's [knxnet] table contradicts itself: assignment = "static" without address or netmask; address, netmask or gateway under dhcp; or a friendly_name longer than 30 characters or outside ISO 8859-1. |
| E044 | error | A [knxnet] tunnel address is listed twice, or is the interface's own address. |
| E045 | error | A [knxnet] tunnel address is not on the interface's line. |
| E046 | error | A [knxnet] tunnel address is the address of a device in the project. |
| W047 | warning | The [knxnet] tunnel addresses of an IP interface differ from the tunnelling addresses the key store (or keyring) lists for it, its Host entries, which are the addresses admit_tunnel_senders admits on the Secure devices. The message names both lists. Runs with the key checks, and only for an interface the store lists tunnelling addresses for. |
Key and KNX Secure rules¶
| Code | Severity | Rule |
|---|---|---|
| E027 | error | The configured keyring (BUSSARD_KEYRING or connection.keyring) points at a file that does not exist. |
| W028 | warning | A device file says security.activated = true, but there is no key store or keyring, the keyring is missing, or it has no tool key for the device. Re-export the keyring from ETS and bussard keys import it. |
| W029 | warning | A group's secure flag disagrees with the keyring: marked secure without a group key, or keyed in the keyring but not marked secure. |
| W030 | warning | The keyring does not read or decrypt; the key checks are skipped. |
| I031 | info | BUSSARD_KEYRING_PASSWORD is not set; the key checks are skipped. |
| W034 | warning | A secured group address (secure = true, keyed in the store) has no device sender, so only tunnel clients can write it, and a Secure device linked to it admits none of the store's tunnelling addresses: no secure_senders row lists one, and no keyring interface group entry covers the address. Set admit_tunnel_senders = true under [connection] and apply the device, or assign the address to a tunnelling connection in ETS. knx_plan_device adds the same sentence as a note for that device while the option is off. |
| E035 | error | A device without KNX Data Secure (no secure_capable in the lock) sends on a group address that a Secure receiver takes secured: its object is marked secure, or the address is. The receiver drops every plaintext telegram. The message names the sender, the address, the secured receivers and the two ways out: make the address plain, or send on a plain address into a logic input of the receiver. knx_add_link refuses such a link and knx_plan_device refuses to plan the sender. |
| E036 | error | The reverse of E035: a Secure device sends secured on a group address that a device without KNX Data Secure listens to, and that receiver cannot decrypt it. knx_add_link and knx_plan_device refuse it the same way. |
| W037 | warning | A device that supports Secure runs a secured group address but is not secured (ETS has not loaded its tool key), so it still sends and expects plain telegrams. The message says whether ETS has Secure commissioning set up for it. |
| E038 | error | Write time only: a secured write to a group address no device sends on (W034), whose Secure devices admit none of the tunnelling addresses, while admit_tunnel_senders is off. bussard write and knx_write_group refuse it before sending. |
| W039 | warning | A secured device sends on a secured group address, but bussard.lock records no sequence_number for it, so its receivers' sender tables (PID 54) can only be seeded from the keyring or with 0. |
| W040 | warning | A keyring export bussard keys export wrote is older than the key store's last change, or [home_assistant] is configured and no export is newer than that change (bussard.keys.meta.toml). |
| W041 | warning | A group address's secure flag and the secure flags of the objects that support Secure linked to it disagree. The message names bussard groups secure <ga> on\|off, which sets the flag, the key store entry and the object flags together. |
| W042 | warning | Import time only: bussard import secures again a group address the project ran plain, or bussard keys import puts back the group key of one. It names the devices the next apply secures. |
validate runs E027 to I031 and W034 with BUSSARD_KEYRING, else the key store bussard.keys, else connection.keyring; the codes are the same for a store and an export. knx_validate runs them with the server's key store or keyring. The rules see addresses only, never a key.
The Data Secure invariants split over these codes:
- every device on a secured address can run Data Secure (E035, E036), is secured (W037) and has its tool key in the key store (W028);
- the address's key is in the store (W029);
- a tunnel-only address admits the tunnel (W034, refused as E038 at write time);
- a Secure sender has a sequence source (W039);
- the group flag, the key store and the object flags agree (W029, W041);
- keyring consumers are not stale (W040);
- an import that secures a plain address again says so (W042).
W037, W039 and W041 read the project only; W040 reads bussard.keys.meta.toml.
Lint rules¶
These rules are opt-in and run only when bussard.toml carries a [lint] table (see bussard.toml):
| Code | Severity | Rule |
|---|---|---|
| L001 | warning | More devices on a line than topology.max_devices_per_line. |
| L002 | warning | A line's summed device bus current exceeds its topology.supply_ma budget. |
| L003 | warning | A device sits on a line topology.supply_ma does not declare. |
| L004 | warning | A KNX Secure device sits behind a line coupler that does not support Secure. |
| L005 | warning | A group address falls outside every block declared in groups.blocks. |
| L006 | warning | A command address has no feedback address on the offset its block reserves. |
| L007 | warning | A group address name does not match groups.name_pattern. |
| L008 | warning | A group address's DPT contradicts the role its block offset stands for. |
Related¶
- Errors: the parse errors that come before these rules.
- Project commands:
bussard validateand its flags. - bussard.toml: the
[lint]table andadmit_tunnel_senders. - KNX Secure: why the Secure rules exist.