Exchange with ETS¶
Keep bussard and ETS, the KNX Association's commissioning tool, in step in both directions: your names into an ETS project, and an integrator's new ETS export into your project. For owners who work with an ETS integrator, and for integrators who keep ETS as the tool of record.
None of these steps touch the bus.
flowchart LR
ets["ETS project"] -->|export .knxproj| imp["bussard import"] --> project["your project"]
project -->|export-groups| names["group-address names<br>as an ETS import file"] -->|import in ETS| ets
ets -->|new export| diff["bussard diff"] -->|what would change,<br>in sentences| project
Send your group-address names to ETS¶
You: Export my group addresses for ETS.
Assistant: (calls knx_export with what: groups)
Wrote 62 group addresses as an ETS CSV. Import it in ETS
under Group Addresses, Import.
format: ets-xml writes ETS's group-address XML instead.
$ bussard export-groups --format ets-csv --out groups.csv
Wrote 62 group address(es) to groups.csv (ETS CSV).
Import it in ETS: Group Addresses -> Import, then pick this file.
--format ets-xml writes ETS's group-address XML instead.
In ETS, open the project, select Group Addresses in the project tree, and use Import on the toolbar. The CSV is the three-level form ETS itself exports. The XML keeps the main and middle group names as a tree.
Names, descriptions and DPTs (the data type of each address) cross over as they are. ETS has no field for bussard's protected flag, so a protected address carries a leading [protected] marker in its description.
Redo the other changes in ETS by hand¶
bussard cannot write into a .knxproj: ETS signs its project files, so bussard cannot write changes back into one. ETS stays in step only when someone redoes the changes there, so let bussard write the list. The checklist is a terminal command; in chat the assistant reads the same changes to you as sentences (knx_diff_project).
$ bussard diff project.knxproj knx --checklist
The output is a Markdown checklist in the order you work in ETS. The lines below are illustrative:
- [ ] 4/1/20 "Aussen dunkel", DPT 1.001, new (main group 4 "Zentral", middle group 4/1 "Wetterdaten")
...
- [ ] Universalkanal C4: Funktion › Helligkeitsschwelle: unter 20 lx (was über 10000 lx)
- [ ] Objekt 105 "C18.1 Logikmodul" (Schalten): sends 1/0/4 (was nothing)
...
Afterwards: export the project and run bussard diff <export> <B>; it should report no changes.
- Group addresses first: new, renamed, DPT, description, security, removed.
- Then one section per device: name and location, parameters (with the ETS page, the ETS label, the new and the old value), objects and links, security.
- Last, a Not in ETS by hand list for what ETS does not take, such as the gateway and the
protectedflag.
Work through it, export the project from ETS, and run the diff again. When it reports no changes, the two agree. If the checklist says it has no pages for a device, run bussard device <address> once and diff again.
See what a new export would change¶
Before you import an integrator's new file, ask what it changes.
You: What would integrator-2026-10-01.bussard change?
Assistant: (calls knx_diff_project)
2 changes. Group address 1/0/1 is now called "Kitchen
ceiling" (was "Light Kitchen"). Night setback on Living
room thermostat: 2 to 3. No protected address is touched.
knx_diff_project compares a .knxproj or .bussard file with your project. A password-protected ETS project needs BUSSARD_PROJECT_PASSWORD in the .env.
$ bussard diff knx integrator-2026-10-01.bussard
2 change(s) from knx to integrator-2026-10-01.bussard:
Group address 1/0/1 is now called "Kitchen ceiling" (was "Light Kitchen").
Night setback on Living room thermostat: 2 to 3.
Each side can be a project folder, a .bussard bundle or a .knxproj. diff exits 0 whether or not there are differences.
- A password-protected ETS project takes
--password,--password-bfor a second ETS project with another password, orBUSSARD_PROJECT_PASSWORDfrom your.env. --jsongives the structured changes,--rawa file-level TOML diff.
A renamed group address is one rename, not a removal and an addition. The comparison writes nothing.
Import the new export¶
You: Import it.
Assistant: (calls knx_import_file)
Imported. The new night setback is in your project; no
device has it yet.
knx_import_file takes theirs: true to take the file's values.
$ bussard import integrator-2026-10-01.bussard --dir knx
The import takes the generated data from the file: com-object tables, links and parameters. Names, rooms, descriptions, DPTs and protected flags you edited stay yours. Each disagreement is reported as a sentence. At the terminal the command exits 3 so you notice:
| Flag | On a disagreement |
|---|---|
| none | Keep your value, exit 3. |
--mine |
Keep your value, exit 0. |
--theirs |
Take the file's value. |
--interactive |
Ask for each one (m keeps mine, t takes theirs). |
A link you have and the file lacks is a disagreement too, because bussard cannot tell a link you added from one the ETS project dropped. The import snapshots your project first, so an undo reverts it. Afterwards, plan and write the devices that changed; the import itself writes no device.
Next steps¶
- Work with an integrator: the full file exchange, with bundles.
- Change a link: push the imported change to the device.
- Project commands: every flag of
diff,importandexport-groups.