Skip to content

Project folder

The project folder is your installation as files: what each file and folder holds, which ones bussard regenerates, and how a bundle packs them. knx/ by default.

Some identifiers keep the older word "model" for the project: this page's file name, --no-model-edits, and JSON fields such as model_sha256 and model_status. .bussard/model-cache/ holds product models, which describe a vendor's application program, not your project.

knx/
  bussard.toml            connection and lint settings, hand-editable
  groups.toml             the group-address plan, hand-editable
  devices/1.1.47.toml     one file per device, hand-editable in full
  bussard.lock            @generated by import, import-product and adopt, never edited
  bussard.keys            KNX Secure key store, encrypted, written by `bussard keys`
  bussard.keys.bak        the previous key store, kept by every write
  bussard.keys.meta.toml  when the key store last changed and each keyring export, no keys
  tests.toml              optional acceptance tests for `bussard test`
  ha.toml                 optional Home Assistant overrides for `bussard ha-config`
  .env                    optional, untracked: passwords and the gateway
  products/               the product archives the lock pins; retained, never regenerated
  products/manufacturers.toml  manufacturer names from the imported ETS data
  captures/               local captures, apply backups, apply-line-<line>.json resume state
  .bussard/history/       snapshots of the project files
  .bussard/facts/         @generated device facts, one file per device
  .bussard/products/      the parsed-product cache
  .bussard/model-cache/   @generated product models, rebuilt from products/ when missing
  .bussard/last_export.json
  .bussard/tunnel-users/  which KNXnet/IP Secure tunnelling user each running bussard holds
  .bussard/instances/     the running `bussard mcp` processes for this project

Each file has its own page under files/; see Related.

Discovery

Without --dir and BUSSARD_DIR, a command that reads an existing project looks for it the way git and cargo find their roots. It works from the repository root, from inside the project folder and from any subdirectory of either:

  1. the working directory, when it holds bussard.toml;
  2. ./knx, when it exists;
  3. each parent directory, nearest first: the parent when it holds bussard.toml, else its knx/ when that holds bussard.toml;
  4. otherwise the current directory.

bussard -v logs the directory it chose. A directory without a project file (bussard.toml, groups.toml, bussard.lock or devices/) is no project, and a command that needs one says so:

no project in the current directory <path>: ...; run `bussard init` or `bussard import <export>` 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.

Project files

bussard.toml, groups.toml, devices/*.toml, bussard.lock, tests.toml and ha.toml are the project files. A snapshot, a bundle and the project's change hash cover exactly these.

  • A file is either fully user-owned or fully generated. Of the project files, bussard.lock is the only generated one. The generated files under .bussard/ are regenerable caches outside them.
  • The device files and groups.toml are the source of truth. The lock is what import and adopt derived from the product data; commit it, as you would Cargo.lock.
  • bussard.keys is written by bussard keys (and by init and import when they find a keyring export), is encrypted, and is committed with the project. Commit bussard.keys.meta.toml with it.
  • captures/ and .bussard/ are local only. init git-ignores .bussard/, *.knxkeys and the .env with the passwords.
  • products/ holds copyrighted vendor data bussard cannot regenerate, so committing it is your decision (see Product data).

All files except bussard.keys are TOML 1.0 as bussard writes them. The parser accepts TOML 1.1 input; the writer never relies on it. Every string is a basic string. Keys are bare wherever TOML allows it and quoted otherwise; no key bussard writes needs quotes except the parameter escape hatch (see Device files).

All TOML is parsed strictly: unknown fields and duplicate keys are errors, with a help: line where the raw parser message misleads (see Errors).

Saves edit the files in place. Comments and the formatting of untouched lines survive; only the entries bussard adds or changes are re-formatted, and everything else stays byte-identical.

  • An object key the project no longer links is removed when the lock written by this save, or the lock it replaces, resolves it. A key neither resolves was typed by hand and stays, so validation reports it (E023).
  • A re-import puts sections and entries in the order a fresh import writes them; comments move with their entries.

bussard device <address> [<channel>] shows the keys a device file accepts.

products/ and a missing .bussard/

products/ is retained: nothing in it regenerates (see Product data). Everything under .bussard/ does, so deleting it loses the history and nothing else. What each command does without .bussard/:

Command .bussard/ absent
init, import, import-product, adopt Create it and write .bussard/model-cache/ and the first history snapshot. products/ is written next to it, never inside.
status, history, show, undo, export The history is empty: status says there is no snapshot yet, history lists nothing, show and undo find no snapshot, export writes the bundle without snapshots.
validate, groups, export-groups, doc, ha-config, device Regenerate .bussard/model-cache/ from the archives the lock pins, in the lock's language, then run as usual. device also writes a single missing product model on demand.
diff, keyring Read no project folder.
scan, monitor, capture, read, write, learn, test Unaffected (the product models regenerate first, as above).
describe, plan, reconstruct, audit --live, backup Read the device facts from the device and write .bussard/facts/<ia>.toml. plan and reconstruct decode parameters when the archive is in products/.
flash, apply (parameters), commission --flash, replace Unaffected by .bussard/. They refuse before any bus write only when the archive the lock pins is missing from products/ or changed.
restore Unaffected: the tables come from the backup directory.
mcp, viz Regenerate the missing product models as above at start and again on every project reload (an edit under knx/, or POST /api/reload in viz), so a server that runs for hours heals without a restart.

Regeneration also runs when .bussard/ exists but lacks the product model of an application a device in the lock pins: the directory is empty, partly deleted, or a device's archive arrived later. Every command checks one file per pinned application and writes only the missing ones.

Only the pinned applications get a product model. An archive with 407 programs, of which one device runs one, is parsed for that one program. import and import-product still write a product model for every program of the archives they pin.

.bussard/history

bussard keeps its own history so undo works without git:

knx/.bussard/history/20260922T101112Z-001/
  manifest.json     # {"reason": {"command", "args"}, "gateway", "result", "bussard_version", "created_at", "summary"}
  bussard.toml
  groups.toml
  bussard.lock
  devices/*.toml
  tests.toml        # when present
  ha.toml           # when present
  • One directory per snapshot, named by a UTC timestamp plus a sequence number, so a listing is already a timeline.
  • A snapshot is a full copy of the project files, since a house's project is well under a megabyte.
  • Nothing else is ever copied: products/, .bussard/model-cache/, captures/, keyrings, .knxproj and .knxprod files stay out.

import, apply, flash, adopt, reconstruct and every MCP edit to the project snapshot before they write. plan and those commands first record an external edit snapshot when the working files differ from the last one, so an edit made in an editor or by an assistant writing TOML is never lost.

bussard status, history, show and undo read this directory. bussard init git-ignores it.

.bussard/facts

What bussard reads off a device that does not change while the device keeps its application: the mask, PID_MAX_APDU_LENGTH, the interface-object table, the property descriptions (once describe has walked them) and how the device answered A_Authorize. One generated file per device:

# This file is @generated by bussard from reads of the device. Do not edit it by hand.
[device_facts]
address = "1.1.12"
read_at = "2026-09-25T10:11:12Z"
mask = "07B0"
application_object = 3
application_id = "0004D14221"
max_apdu = 233
authorize = "granted"
object_table_source = "io_list"

[[device_facts.objects]]
index = 0
object_type = 0

[[device_facts.objects.properties]]
index = 1
pid = 1
pdt = 4
writable = false
max_elements = 1
read_level = 3
write_level = 0

[[device_facts.objects]]
index = 1
object_type = 1

Who writes it:

  • describe, reconstruct, plan, apply, restore, backup and the flash pre-flight read or refresh it on their connection.
  • commission and replace drop the file of the address they re-assign, since a new box answers there; their flash and apply read the new one.
  • scan, assign and audit --live read only the mask, compare it with the file, and drop a file stored under another mask.

Every bus command that uses the facts first reads the device descriptor and the application id (PID_PROGRAM_VERSION of application_object). When both equal the stored mask and application_id, the command skips the per-object PID_OBJECT_TYPE walk and the PID_MAX_APDU_LENGTH read. Otherwise it reads the facts again and replaces the file.

  • --refresh-facts forces the re-read; deleting the file has the same effect.
  • A file that does not parse is ignored with a warning and rewritten.
  • Without a project folder no facts are stored, and every command reads the device each time.

authorize = "unsupported" lets describe, plan, reconstruct, the read phase of apply and the flash pre-flight skip A_Authorize_Request, which such a device leaves unanswered for the full 3 s response timeout per session. When the facts turn out stale on that connection, the key is presented after all. The write phase of apply and flash relies on the verdict its own read phase established. A device recorded as granted or denied is always asked, and flash --bcu-key always presents the key. The frames apply and flash write do not change.

Details

The object table is read from PID_IO_LIST (device object, PID 71) in one or a few multi-element reads, when a System B device offers it and the list agrees with PID_OBJECT_TYPE at the last object, the first application object and the index after the last. Any refusal, short answer, timeout or disagreement falls back to the walk (object_table_source = "walk").

The [device_facts.knxnet] table

For a KNX IP interface, status <ADDRESS>, describe and adopt add what its KNXnet/IP parameter object reported. For any other device they write no_knxnet = true once they have probed for the object. The table is re-read on every such command, because the address in use can change under DHCP:

[device_facts.knxnet]
read_at = "2026-10-26T10:00:00Z"
object_index = 4
individual_address = "1.1.200"
tunnels = ["1.1.22", "1.1.23"]
current_assignment = ["dhcp"]
assignment = ["dhcp"]
assignment_mode = "dhcp"
current_address = "192.0.2.10"
current_netmask = "255.255.255.0"
current_gateway = "192.0.2.1"
mac = "00:00:5E:00:53:7D"
routing_multicast = "224.0.23.12"
capabilities = ["device management", "tunnelling"]
state = "ok"
friendly_name = "Demohouse Alpha"

Why the facts live here

  • An ETS re-import rewrites the device files and the lock, and never touches .bussard/.
  • The device files hold intent to review; the facts are observations.
  • The lock is written by import and adopt only and is covered by snapshots and the project's change hash, which a read-only bus command must not change.

The facts are not part of a bundle.

.bussard/products

The parsed-product cache. A .knxproj carries the application program of every device in the project, and a .knxprod often a whole product family, while flash, plan, reconstruct and adopt need one program. bussard reads the archive's table of contents first, then parses only the program the command selects (see Product data). What was parsed is stored here as JSON, one directory per archive:

.bussard/products/<key>/catalog.json
.bussard/products/<key>/<application-id>.json
  • The key is a SHA-256 over the archive's SHA-256, the selected inner archive, the cache format and the running bussard build (its version and executable). An edited or replaced archive, or a rebuilt bussard, gets a new directory, so nothing is read from a stale entry.
  • Regenerating .bussard/model-cache/ parses only the pinned programs (with the programs their Hardware2Program lists next to them), so afterwards the cache holds those, not the whole archive.
  • The 32 most recently written entries are kept.
  • An unreadable or foreign file is a cache miss, never an error. A program read back is the same value the parser returns, so the images flash writes are unchanged.
  • BUSSARD_PRODUCT_CACHE=off turns the cache off. Deleting the directory is always safe.

Note

Two other start-up costs are paid once per process. The project is parsed once per command: a later load of unchanged files returns the same result, and any edit is parsed again. The key store or a keyring is decrypted once per process or MCP server for the same file bytes and password; an edited file or another password is decrypted again.

.bussard/model-cache

One generated JSON file per application program, the product model, written from the archives in products/ (through the parsed-product cache) by import-product, and by any command or server that finds one missing or of an older format. Never edit them; Product data describes what they hold and when they regenerate. Deleting the directory is always safe.

The bundle format

A .bussard file, written by bussard export, is a zip archive:

manifest.json                      # always the first entry
bussard.toml
groups.toml
bussard.lock
devices/*.toml
tests.toml                         # when present
ha.toml                            # when present
.bussard/history/<id>/...          # unless exported with --no-history

Entries are sorted, with a fixed timestamp and permissions, so two exports of the same files differ only in the manifest's exported_at. The manifest:

Field Meaning
format, format_version "bussard-bundle", 1.
model_version The project schema version. A reader refuses a newer one.
bussard_version The bussard that wrote the bundle.
exported_at RFC 3339 in UTC.
project The project name from groups.toml, when set.
devices, group_addresses, links, history_snapshots Counts.
files The SHA-256 of each project file, by path.
model_sha256 SHA-256 over the lines <file sha256> <path>\n, sorted by path (the sha256sum output format).
excluded What a bundle never contains (below).

A bundle never contains products/, .bussard/model-cache/, captures/, keyrings, .knxproj or .knxprod files, or .env: the export copies an allow-list of project files and nothing else. A reader rejects:

  • any entry outside the layout above;
  • any project file whose hash does not match;
  • any entry larger than 64 MiB.