Project commands¶
The commands that create, import, export, compare, check and document the project folder: init, import, export, diff, validate, groups reserve, export-groups and doc. None of them writes to a device.
The options every command shares are on Global options and are not repeated here.
bussard init [PROJECT]¶
Create a fresh project: discover the gateway and write the skeleton, then import an ETS project when there is one.
$ bussard init [PROJECT] [--scan <LINE>] [--yes]
With a resolved tunnelling gateway, init prints what the interface says about itself:
$ bussard init
Gateway: Jung IP Interface (192.0.2.10:3671, IA 1.1.0)
Tunnelling: 4 tunnels, 1 in use.
| Flag / arg | Default | Meaning |
|---|---|---|
[PROJECT] |
the one .knxproj next to --dir |
The ETS project (a .knxproj) to import right after writing the skeleton. |
--password <PASSWORD> |
Project password, as for import. |
|
--scan <LINE> |
Without an ETS project: scan this line after writing the skeleton, without asking. | |
--yes |
off | Skip the confirmation prompt for a non-empty directory. |
--gateway (or BUSSARD_GATEWAY) skips gateway discovery and writes that gateway into bussard.toml; --routing configures routing instead.
Behaviour:
- The project folder is
--dir,BUSSARD_DIRor the current directory.initnever searches upward. - With an ETS project,
initrunsimportright after writingbussard.toml, product data from the export and validation included. - Without an ETS project, on a terminal, it offers to scan line 1.1 and list the devices that answer (see
scan).--scan <LINE>does that without asking. Off a terminal and without flags it writes the skeleton and stops. - A directory that already holds
bussard.tomlis refused. - A directory with anything else in it (other than
.git,.env,.gitignoreand.bussard/), or with a project one level down inknx/, gets a question first:the current directory /home/me/house is not empty (12 entries, a project exists in knx/); initialise a project in the current directory? [y/N].--yesanswers it; without a terminal and without--yes,initrefuses. - In a non-empty directory
initkeeps existing files and adds its.bussard/,*.knxkeysand.envlines to an existing.gitignore, each only when missing. - With an ETS project,
initlooks for an ETS keyring export (.knxkeys) in the ETS project's directory. WithBUSSARD_KEYRING_PASSWORDset, the import merges exactly one into the key storebussard.keys(seekeys). Without the password,initrecords it as the deprecatedconnection.keyring(relative to the project folder when it sits next to it, else absolute) and prints thebussard keys importcommand that moves it into the store. Several are listed and none is picked. The password is never written anywhere. - Gateway discovery is multicast and does not cross subnets. When it finds nothing,
initstill writes a valid skeleton with a placeholder gateway. - When every tunnel slot is taken,
initprints the no-free-tunnel message (exit code 4 on Global options) and still writes the skeleton. initreports KNXnet/IP Secure astunnelling is secure-only (needs tunnelling credentials),supported, plain tunnelling allowedornot advertised. A secure-only interface skips the plain reachability check, andinitnames the credentials a command needs. Discovery lists such interfaces asKNXnet/IP Secure only.
Details
The interface description is a unicast DESCRIPTION_REQUEST, which uses no tunnel slot. The tunnel count comes from the tunnelling-info DIB (KNXnet/IP Core v2). An interface that sends only its additional individual addresses prints N tunnels (usage not reported); an older interface that reports neither says so. The Secure line comes from an extended search (SEARCH_REQUEST_EXTENDED).
bussard import [PROJECT]¶
Import an ETS .knxproj or a .bussard bundle (see export) into the project with the product data it carries, then validate.
$ bussard import <PROJECT> [--password <PASSWORD>] [--mine | --theirs | --interactive]
$ bussard import house.knxproj --dir knx
imported 2 group addresses, 1 devices, 2 link entries → knx
extracted 1 application program(s) from house.knxproj into knx/products
pinned the product data of 1 device(s) in bussard.lock: 1.1.1
validation: 0 error(s), 0 warning(s)
| Flag / arg | Default | Meaning |
|---|---|---|
<PROJECT> |
The .knxproj or .bussard file to import. |
|
--password <PASSWORD> |
BUSSARD_PROJECT_PASSWORD, then a prompt |
Project password. |
--mine |
off | On a re-import, keep this project's value for every hand-edited conflict and exit 0. |
--theirs |
off | On a re-import, take the incoming value for every hand-edited conflict. |
--interactive |
off | On a re-import, ask per conflict (m keeps mine, t takes theirs). Needs a terminal. |
--yes |
off | Skip the confirmation prompt for a non-empty directory that holds no project yet. |
Behaviour:
- The project folder is
--dir,BUSSARD_DIRor the current directory;importnever searches upward. To import intoknx/, pass--dir knxorcd knxfirst. - A directory that already holds a project is a re-import and asks nothing.
- Any other non-empty directory gets the same question as
init:the current directory /home/me/house is not empty (3 entries); import into the current directory? [y/N]. Without a terminal and without--yesthe import is refused and nothing is written. - An import into a directory without a project writes or merges the same
.gitignoreasinit. - Every import into an existing project snapshots it first, so
bussard undoreverts it. - After the write,
importprints what changed in the project as the sentencesbussard statususes, validates the written project and printsvalidation: N error(s), M warning(s)with each error. An error does not undo the import. - A group address a device uses but the ETS project does not define is added to
groups.toml(seegroups reserve).
Product data. A .knxproj carries the application program of every device it holds, so import downloads nothing.
- An application program no stored archive carries is extracted once from the
.knxprojinto<dir>/products/<application-id>.knxprod, pinned in the lock and turned into product models under<dir>/.bussard/model-cache/. See Product data. - An export that lacks a device's application program is refused before anything is written:
application program <id> referenced by device <address> was not found in the archive. - A device the project does not hold gets its product data from
adoptorimport-product, which can download it.
Re-import and conflicts. Re-import is idempotent.
- The generated sections (com-object tables, link wiring, parameters) always come from the incoming side.
- Hand-authored fields (names, rooms, descriptions, DPTs,
protected, channel names) that differ are conflicts, printed as sentences:Group address Light Kitchen (1/0/1): the name is "Light Kitchen" here and "Kitchen ceiling" in the bundle. Kept this model's value. - Without a flag the local value is kept and
importexits3.--mine,--theirsand--interactivesettle the conflicts and exit 0. - A device, channel or com object the ETS project no longer has is dropped with its links, and its keys leave the device file. Device files whose address left the ETS project are pruned.
- A send or listen address the local project has and the incoming side lacks is a conflict, because the project records no history for links.
--theirsremoves it,--minekeeps it,--interactiveasks; without a flag it is kept andimportexits3. A stored parameter value that differs is a conflict in the same way. - With
--theirs, the device files,groups.tomlandbussard.lockmatch a fresh import of the same file byte for byte.bussard.tomlis yours and stays as it is.
Bundles. A bundle imported into a directory without a project (no groups.toml, no device file) is extracted byte for byte, history included. An existing bussard.toml, for example from init, is kept. A bundle imported into an existing project runs the merge above; the local history stays and the bundle's snapshots are not merged.
bussard export [FILE]¶
Write the project and its history as one .bussard file: the handover file for an integrator and the owner's backup.
$ bussard export [FILE] [--no-history]
| Flag / arg | Default | Meaning |
|---|---|---|
[FILE] |
<parent>/<dir name>-<YYYY-MM-DD>.bussard |
The bundle to write, next to the project folder by default. |
--no-history |
off | Leave the .bussard/history snapshots out. |
--json |
off | Print {"path", "manifest"}. |
Behaviour:
- The project must load;
exportrefuses a broken project. - It records the bundle's path, time and project digest in
<dir>/.bussard/last_export.json. - After a verified
apply, bussard prints a one-line hint on stderr when that record is older than the newestapplysnapshot and the project files changed since, or when the project was never exported. An apply of an unchanged project stays quiet.
The bundle format is on Project folder.
bussard diff <A> <B>¶
Explain what changes from A to B as the plain sentences bussard status prints. Each side is a .knxproj, a .bussard bundle or a project folder. Both are loaded in memory; nothing is written.
$ bussard diff <A> <B> [--raw | --checklist] [--password <PASSWORD>] [--password-b <PASSWORD>]
| Flag / arg | Default | Meaning |
|---|---|---|
<A>, <B> |
The two sides. | |
--json |
off | Emit (schema 2) {"ok", "from", "to", "source", "count", "summary", "touches_protected", "sentences", "changes": [...]}, the same change objects as status --json; source is the second side's bundle manifest (kind: "bundle") or kind: "knxproj", absent for a project folder. knx_diff_project returns the same object with from: "the working model". |
--raw |
off | Print a file-level TOML diff instead of the sentences. |
--checklist |
off | Print a per-device Markdown checklist of the changes to redo by hand in ETS. With --json, emit the same structure as JSON. |
--password <PASSWORD> |
BUSSARD_PROJECT_PASSWORD |
Password for both .knxproj sides. |
--password-b <PASSWORD> |
Password for the second side, when it differs. |
Behaviour:
- Exits 0 whether or not there are differences.
- Group addresses are matched by address and devices by address, so a GA renamed in a newer export is one rename, not a removal and an addition. Two exports of the same ETS project give an empty diff.
- A parameter change is named by its text from the product data when a project-folder side has one, else by its key.
- A sentence names a device or group address by its name; the address follows only when another device or group address has the same name, or the group address is protected:
Meteodata 140 S now switches Aussen dunkel.An unnamed one reads as its address, and a channel without a name or vendor text is left out.
--checklist. ETS signs its project files, so bussard cannot write changes back into a .knxproj. bussard diff <export> knx --checklist prints the work to redo in ETS, in ETS order:
- Group addresses: new, renamed, DPT, description, security, removed, with the range names:
- [ ] 4/1/20 "Aussen dunkel", DPT 1.001, new (main group 4 "Zentral", middle group 4/1 "Wetterdaten"). - One
## <address> <name> (<room>)section per device, with Device (name, location, product, channel names), Parameters, Objects and links and Security. A parameter line gives the ETS page, the ETS label, the new value and the old one:- [ ] Universalkanal C4: Funktion › Helligkeitsschwelle: unter 20 lx (was über 10000 lx). The old value is the vendor default when the old side stores none. A parameter that enables another one's page comes first. An object line shows only the roles that changed:- [ ] Objekt 105 "C18.1 Logikmodul" (Schalten): sends 1/0/4 (was nothing). - Not in ETS by hand: what ETS does not take (gateway, transport, admission, the
protectedflag), a value stored at its vendor default, and a parameter ETS does not show under the new values. - The item count and
Afterwards: export the project and run bussard diff <export> <B>; it should report no changes.
The pages and old values come from the product models of a project-folder side. A cached product model of an older format carries no pages; the checklist says so, and bussard device <address> regenerates it.
--checklist --json emits {"schema", "from", "to", "changes", "items", "groups": [...], "devices": [{"address", "name", "room", "device", "parameters", "objects", "security"}], "notes": [...]}. Each item has kind, text and, where they apply, device, group, object, page, label, value, old_value.
bussard validate¶
Validate the project and its keys, and report diagnostics. Offline; never prompts.
$ bussard validate
| Flag | Default | Meaning |
|---|---|---|
--json |
off | Print (schema 2, the object knx_validate returns with severity: "info") {"schema", "ok", "diagnostics": [...], "counts", "shown", "note", "checked"}; each diagnostic has code, severity, message and location, and device and parameter when it names them. checked lists the rule families that ran. |
Behaviour:
- Exits non-zero on errors; warnings and infos alone exit 0. The codes are on Diagnostics.
- The key checks (E027 to I031) use the file
BUSSARD_KEYRINGnames, else the key storebussard.keys, else the deprecatedconnection.keyring. - It decrypts the key store (or keyring) once with
BUSSARD_KEYRING_PASSWORD. Without the password it prints one info line (I031) and skips the key checks.
bussard groups reserve "<FLOOR> <ROOM>" <FUNCTION>...¶
Reserve the conventional group addresses for one room, append them to groups.toml and print them.
$ bussard groups reserve "EG Küche" light blind
reserved 9 group address(es) for EG Küche in knx/groups.toml (floor-trade-block scheme):
1/1/0 1.001 EG Küche Light Switch
1/1/3 1.001 EG Küche Light Switch status
1/2/0 1.008 EG Küche Blind Move
...
The room is one argument, floor first: the first word is the floor, the rest the room. Each function gets the block of its trade, five addresses for a light and ten for a blind or a heating zone. Every address is named <Floor> <Room> <Function> <Role> with its DPT; unused slots in the block stay free for growth.
Functions: light (switch and feedback), light-dim (switch, dim, value, both feedbacks), blind, heating, socket.
| Flag | Default | Meaning |
|---|---|---|
--scheme <SCHEME> |
[lint.groups] scheme, else floor-trade-block |
floor-trade-block or function-floor, for a project that has no scheme yet. Refused when it contradicts bussard.toml. |
--json |
off | Emit room, scheme, file, added, lint_config_written, validation instead of the list. |
| Scheme | main | middle | sub |
|---|---|---|---|
floor-trade-block |
floor | trade | block start + role offset |
function-floor |
trade | floor | block start + role offset |
Behaviour:
- Running it again for a room and function that already have their block adds nothing. Existing addresses are never renumbered or renamed.
- The scheme is
[lint.groups] schemeinbussard.toml. The first reservation in a project without one writes a[lint]table with the scheme, so later reservations andbussard validatefollow the same convention. - There is no plan file. For several rooms, run the command once per room, or have an assistant call
knx_scaffold_groupswith the room list. - A group address that a device file uses but
groups.tomldoes not define is declared byimport,applyand the MCP edit tools, named<channel name or device name> <object function or key>with the object's DPT, and reported:added 0/1/3 "Fenster Süd Langzeitbetrieb" (DPT 1.008) to groups.toml, first used by 1.1.47 object 144.bussard validatealone only warns (E001).
bussard export-groups¶
Write the group-address plan in a format ETS's Group Addresses -> Import accepts.
$ bussard export-groups --format ets-csv --out groups.csv
| Flag | Default | Meaning |
|---|---|---|
--format <FORMAT> |
required | ets-csv or ets-xml. |
--out <FILE> |
required | The file to write. |
Behaviour:
- Names, descriptions and DPTs cross over.
- ETS has no field for the
protectedflag, so it is carried into the description as a leading[protected]marker.
Details: the two formats
ets-csv is the three-level CSV ETS itself exports: UTF-8 with a BOM, semicolon separated, CRLF line endings, every field quoted, with the columns Main, Middle, Sub, Address, Central, Unfiltered, Description, DatapointType, Security. Main groups, middle groups and addresses each get their own row, and the DPT is in ETS notation (DPST-1-1, or DPT-1 when the DPT has no sub number).
ets-xml is the GroupAddress-Export document in the namespace http://knx.org/xml/ga-export/01: nested GroupRange elements carrying Name, RangeStart and RangeEnd, with GroupAddress leaves carrying Name, Address, Description, DPTs and Security.
bussard doc¶
Render the handover documentation folder the KNX guidelines prescribe, as Markdown, from the project and the product models in .bussard/model-cache/. Offline; never touches the bus.
$ bussard doc [--out <DIR>]
| Flag | Default | Meaning |
|---|---|---|
--out <DIR> |
docs/installation |
Where to write the files. Files with the same names are overwritten; others are left alone. |
--json |
off | Print the structured document model to stdout instead of writing files. |
| File | Contents |
|---|---|
index.md |
Links to everything below, one entry per room sheet. |
devices.md |
Address, name, location, manufacturer, order number, application, mask, Secure status. |
groups.md |
Address, name, DPT, description, protected flag, senders and listeners (device and com-object names). |
rooms/<floor>-<room>.md |
Every device in the room with its channels, and one plain line per com object: Rocker 1 switches Kitchen ceiling light (1/0/10); status from 1/0/12. Unnamed items fall back to their addresses. A device without a location: gets no room sheet. |
connection.md |
Transport and gateway or multicast endpoint from bussard.toml. Never credentials. |
changelog.md |
The last 50 commits touching the project folder, from git log. Empty when the directory is not a git repository or git is missing. |
Behaviour:
- The output is deterministic: two runs on the same project write identical bytes, with no timestamps, so you can commit the folder and review its diff after every change.
- With
--json, each device'sparametersare the parameter rowsbussard device --jsonshows (key,reference,text,value,default,at_default,choices,range,computed,computed_by), pluslabel, one row per parameter the device file stores or a calculation computes.valueis the stored value;computedis what a download writes for a calculation output.
Related¶
- Global options: options, consent flags and exit codes shared by every command.
- Project folder: the files these commands write, and the bundle format.
- Diagnostics: every code
validatereports. - Exchange with ETS: names into ETS and what a new export changes.