Global options¶
The conventions, options, consent flags and exit codes that every bussard command shares. bussard <command> --help is authoritative for the build you run.
Conventions¶
| Item | Form | Example |
|---|---|---|
| Group address (GA), the shared address a button and an actuator talk on | three levels | 3/2/0 |
| Address (individual address, IA), the address of one device | area.line.device |
1.1.4 |
| DPT, the datapoint type that says how a value is encoded | quoted string | "1.001" |
Filter (monitor --filter, capture --filter) |
comma-separated GAs, GA prefixes or IAs | 3/2/0,3/,1.1.30 |
Confirmation. A command that writes to a device or the bus asks y/N on a terminal and names the resolved gateway (host:port). Without a terminal it refuses unless you pass --yes. See confirmation, download consent and JSON.
The real-gateway gate. A write command whose resolved gateway is not loopback (127.0.0.0/8 or ::1) refuses to run unless you pass --allow-remote-gateway or set BUSSARD_ALLOW_REAL_GATEWAY=1.
- Loopback gateways, such as the local simulator, are always allowed.
- Reads (
monitor,read,scan,plan,reconstruct) are never gated. - The two servers pass the gate once, at startup, when a flag lets them transmit:
mcp --allow-writes,mcp --allow-programming,viz --allow-writesandviz --watch-prog. The MCP programming tools check it again on every call. - Without those flags neither server can write, so neither is gated.
Read Safety before your first write.
Options¶
One option group serves every subcommand. Each option prints under "Global options" in every --help and goes before or after the subcommand: bussard --dir site/knx status and bussard status --dir site/knx are the same.
A command with no use for an option accepts and ignores it. The exception is --json, which a command without machine output refuses.
Precedence, for an option with more than one source: the flag, then the environment variable (exported, else from the .env file, see Environment), then bussard.toml, then discovery or the built-in default.
| Option | Environment | bussard.toml |
Default | Meaning |
|---|---|---|---|---|
--dir <DIR> |
BUSSARD_DIR |
discovered, see project folder discovery | The project folder. | |
--gateway <HOST[:PORT]> |
BUSSARD_GATEWAY |
connection.gateway |
none: a tunnel without a gateway is an error | The KNXnet/IP gateway; the port defaults to 3671. Implies tunnelling. For init: use this gateway instead of discovering one (flag or environment only). |
--routing |
connection.transport = "routing" |
tunnelling | Use KNXnet/IP routing (multicast). No environment variable selects it, so a scripted multicast write shows on the command line. For init: configure routing. |
|
--device-management |
tunnelling | Manage the KNX IP interface at --gateway itself over a KNXnet/IP device management connection instead of a tunnel: plan and apply of an interface, describe, interface secure. Refused by every other command. See Device support. |
||
--keyring <FILE> |
BUSSARD_KEYRING |
connection.keyring (deprecated) |
the key store bussard.keys |
The KNX Secure keys a bus command uses. See keys. |
--json |
text | Machine-readable output: one JSON document with a top-level "schema", or JSON Lines for monitor. Refused by a command without JSON output. apply --json needs --line. |
||
--allow-remote-gateway |
BUSSARD_ALLOW_REAL_GATEWAY=1 (exactly 1) |
deliberately none | off | Permit a transmitting command (a write, programming, an armed viz or mcp) against a non-loopback gateway. Read-only commands ignore it. No other variable can enable a transmit. |
--skip-address-check |
off | Skip the pre-flight probe that no bus device answers at bussard's own source address, on the commands that open a device connection. See Device support. | ||
--refresh-facts |
off | Ignore the stored device facts and read them from the device again. Every management command that reads the facts honours it. | ||
-v, --verbose |
RUST_LOG overrides |
warn |
Raise log verbosity; repeatable. -v is info, -vv debug, -vvv trace. An explicit RUST_LOG replaces this entirely, so RUST_LOG=bussard_transport=trace still works. -v also logs the project folder it chose. |
|
--timing |
off | Print the wall-clock time to stderr on exit (took 1.23s), preceded by the start-up phases that ran and how often the project was parsed and a key store or keyring decrypted. |
||
--no-progress |
off | Never draw the live progress display; print the plain progress lines, as a piped run does. | ||
--secure-user <ID> |
Open a KNXnet/IP Secure tunnel as tunnelling user ID. Needs --secure-password-env. |
|||
--secure-password-env <VAR> |
The environment variable that holds the tunnelling user's password. Never on the command line. Needs --secure-user. |
|||
--secure-transport auto\|tcp |
auto |
How a refused TCP connect of the KNXnet/IP Secure session is reported. Both open TCP; auto names the likely causes. Needs tunnelling credentials. |
--yes, --yes-download, --force, --dry-run and --plan are not global. They stay on the command whose action they consent to, and never come from the environment or bussard.toml.
Details: the --timing phases
The phases are tunnel creds (the secure tunnel credentials), model load, product parse (programs parsed and whether the parsed-product cache was on), tool keys, keyring (the PBKDF2 keyring decrypt, part of the phase that needed it), to tunnel open (start to the tunnel request) and tunnel.
Keys¶
--keyring names the keys three jobs use: the tunnelling users open the KNXnet/IP Secure tunnel, the device entries carry the KNX Data Secure tool keys for management, and the group keys secure and decrypt group telegrams.
- An explicit
.knxkeysfile from--keyring, thenBUSSARD_KEYRING. - Else the key store
bussard.keysin the project folder (seebussard.keys). - Else
connection.keyringinbussard.toml. It is deprecated, kept for projects without a store, and ignored with a warning when a store exists.
A relative connection.keyring is relative to the project folder; a relative flag or variable is relative to the working directory. The password comes from BUSSARD_KEYRING_PASSWORD, never a flag.
- Only commands that talk to the bus read the keys.
adoptandtestuse them for the tunnel only. - A key source other than
--keyringserves the tunnel only when--tool-keyis given. --keyringconflicts with--tool-key.
Project folder discovery¶
Without --dir and BUSSARD_DIR, a command that reads an existing project looks for it the way git finds its root. It works from the repository root, from inside the project folder and from any subdirectory:
- the working directory, when it holds
bussard.toml; ./knx, when it exists;- each parent directory, nearest first: the parent when it holds
bussard.toml, else itsknx/when that holdsbussard.toml; - otherwise the current directory.
A directory without a project file (bussard.toml, groups.toml, bussard.lock or devices/) is no project. A command that needs one says no project in the current directory <path>: ...; runbussard initorbussard import there, or pass --dir <project folder>.
init and import create or update the project in --dir, BUSSARD_DIR or the current directory, and never search upward.
Confirmation, download consent and JSON¶
--yes¶
--yes means one thing on every command: skip the confirmation prompt.
assign,adopt,flash,apply,commission,restore,replace,restart,write,testandlearnask on a terminal.- Without a terminal and without
--yesthey refuse withrefusing to <action> without a terminal to confirm on; pass --yes to confirm non-interactively. assign,adopt,replace,commissionandlearnrefuse before they load the project.flash,apply,restore,writeandtestfirst read and show what they would change, then refuse at the prompt.restartrefuses at its prompt, before it sends anything.- An explicit address or value is never consent on its own.
--yesnever lifts the real-gateway gate, which is checked before the prompt.
--yes-download¶
Downloading vendor product data is a separate question with its own flag, --yes-download, on import-product and adopt. --yes never answers it. init and import download nothing: a .knxproj carries its product data.
Without a terminal and without --yes-download, adopt downloads nothing and lists the missing order number; import-product --order-number refuses. --no-download on adopt skips the question.
--force and --full¶
These keep a per-command meaning.
--forceoverrides one named refusal: the not-factory-fresh refusal (flash), the replacement-identity refusals (replace), or the protected-group-address refusal (write,test).testalso needsallow_protected = truein the test file.--fullmeans "skip nothing":flashre-streams every object,describewalks every property description again.
JSON documents¶
Every --json document is one object whose first field is "schema": <n>, the version of that command's shape. Each monitor --json line carries it too. A list is wrapped under a key: validate --json prints {"schema", "diagnostics": [...]}.
The number goes up when a field is removed or renamed, or changes its type or meaning. Adding a field does not bump it, so ignore fields you do not know. Every shape starts at 1. The shapes are in JSON output.
KNXnet/IP Secure tunnelling¶
An interface with KNXnet/IP Secure on and no plain tunnel refuses an ordinary connection. bussard then needs a tunnelling user's credentials and opens an authenticated, encrypted session.
| Source | What happens |
|---|---|
| The key store or a keyring (automatic) | A command with keys (the key store, or --keyring) uses their tunnelling users. When an interface listed there names the gateway's address and the gateway advertises KNXnet/IP Secure, the tunnel goes secure as the user whose tunnel address is free. The interface's device authentication code from the same keys lets bussard check the interface's identity first. A plain gateway stays on the plain tunnel. |
--secure-user <ID> --secure-password-env <VAR> |
Always opens a secure session as that user. Without a key store or keyring the interface's identity is not verified; a warning says so. |
| Neither | Against a secure-only interface the command fails at once, with no retries: interface <gateway> requires KNXnet/IP Secure (secure tunnelling only) and no tunnelling credentials were given .... |
bussard init --gateway <ip> prints KNXnet/IP Secure: tunnelling is secure-only for such an interface.
One key source, two jobs. The key store (or the keyring) opens the tunnel, and its device entries carry the tool keys.
- A device the key store lists is managed over KNX Data Secure with its tool key.
- A device it does not list is managed in the clear through the secure tunnel, so plain devices behind a secure-only interface stay reachable.
- A device whose device file says
security.activated: true(secured) but that the key store does not list is refused withthe keyring ... has no tool key for <IA>. This holds fordescribe,reconstruct,plan,flash,apply,commission,replace,backup,restore, the--linewalks and the MCP device tools. scan,assignandaudit --livenever refuse. A secured device without a tool key is shown assecured, bussard has no tool key for it(scan) orsecured (mask hidden), bussard has no tool key for it(assign).
TCP only. A KNXnet/IP Secure tunnelling session runs over TCP, as ETS uses it. The KNX standard allows no other carrier: a unicast secure session must use TCP, and an interface discards a session request that arrives over UDP (KNX IP Secure 3/8/9 §2.2.3.3, §2.2.3.6.4). When the TCP connect is refused by an interface that advertises KNXnet/IP Secure, bussard fails with a message that names the likely causes: secure tunnelling disabled or misconfigured, the interface's TCP connections all taken (often there is just one), or a different device at that address.
Tunnel addresses and sessions. The interface assigns each authenticated user its own tunnel address, and management traffic uses it as its source.
- Two bussard processes on one host take different users. A user the interface refuses hands over to the next one.
- A refused password (
refused tunnelling user N) and an interface that fails its own authentication are fatal. - A lost link re-establishes a new session within the
BUSSARD_TUNNEL_RECONNECT_SECSbudget; a pulled cable is noticed after about 7 s. - The session sends a keepalive every 30 s (
BUSSARD_SECURE_KEEPALIVE_SECS). A value of 60 s or more prints a warning at connect.bussard test --secure-idle <SECS>measures how long an interface keeps an idle session. - Secure routing (multicast) is not implemented.
The variables are on Environment.
Details
The handshake is X25519 key agreement; the interface proves its device authentication code, bussard proves the user password, and every later frame travels in a SECURE_WRAPPER. bussard reads the gateway's extended description to match it with an interface in the key store. The tunnel marks the user it holds under <dir>/.bussard/tunnel-users/. A re-established session first closes the stale one, so an interface that allows one session per user does not refuse the new one as a second login.
TCP carries no ACK, so after 5 s without a frame the tunnel sends a CONNECTIONSTATE_REQUEST and treats 2 s of further silence as a lost link (BUSSARD_TCP_READ_DEADLINE_MS). A UDP session detects a loss through its ACK timeout. Over UDP one socket carries the session and the tunnel, TUNNELING_ACKs travel inside the wrappers, every HPAI carries the real local endpoint and every frame goes to the control endpoint. The 30 s keepalive default is half the 60 s session timeout of the KNX specification.
Progress display¶
flash (including --parameters-only), apply, reconstruct --line and scan show a live progress view on stderr when stdout and stderr are both terminals. It shows the step k/n and its label, a byte bar for the segment being streamed, the elapsed time, an ETA and the last bus event (a reboot wait, a reconnect, a connect retry).
A successful run clears the view and ends with the usual final lines. A failed run leaves it on screen, so the step it stopped at stays visible.
The view is off, and the output is the plain line-oriented text, when any of these holds:
- stdout or stderr is not a terminal;
TERM=dumb;BUSSARD_WIRE_TRACE=1;- the command runs with
--json; --no-progressis given.
Progress never goes to stdout. The plain lines contain no cursor-control codes beyond the \r of the byte and address counters.
Details
The flash ETA starts from the plan's TP1 frame estimate and switches to the measured rate once 5% of the bytes are written.
Exit codes¶
| Code | Meaning |
|---|---|
0 |
Success. |
1 |
Any other error or refusal. A network timeout exits 1. |
2 |
A usage error: an unknown flag, a missing argument or a value that does not parse. Nothing ran. |
3 |
import re-imported the project but left hand-authored conflicts un-applied. The files were written with your edits intact; reconcile the reported fields. |
4 |
The gateway has no free tunnelling connection (E_NO_MORE_CONNECTIONS, status 0x24). Every tunnel slot is taken, usually by Home Assistant, an open ETS project or another bussard process. See Device support for the tunnel budget. |
Cases worth knowing:
validateexits non-zero on errors; warnings and infos alone exit 0.readexits non-zero when nothing answers within the timeout, so a script can detect a dead group object.planandapplyexit 0 when there is nothing to do.importexits3when a re-import kept hand-edited values that differ from the incoming side and no--mine,--theirsor--interactivesettled them. The write still happened.- Refusals (a protected GA without
--force, no terminal without--yes, an unsupported device mask, an unsupported load procedure) exit non-zero before anything is written. auditexits 0 on a completed audit, whatever it found.
Related¶
- Environment: the variables and the
.envfile. - Safety: the rules to read before the first write.
- Write commands: what each write command does and its rails.
- Project folder: what lives in the folder
--dirnames.