Skip to content

bussard.lock

bussard.lock is the join between your words and the vendor's ids: which product archive each device runs, and the channel handles, object keys and parameter keys its device file uses. import, import-product and adopt write it; never edit it by hand. Commit it with the project, as you would Cargo.lock.

Example

The lock entry for the device on Device files, trimmed the same way:

# This file is @generated by `bussard import` and `bussard adopt`. Do not edit it by hand.
version = 3
written_by = "bussard 0.1.0"
source = "home_test.knxproj"
language = "de-DE"

[[product]]
sha256 = "5e0c…"
file = "products/Jung_KNX_Aktoren.knxprod"
filename = "Jung_KNX_Aktoren.knxprod"
size = 1184233
origin = { kind = "index", order_number = "230021SU", url = "https://…" }
applications = ["M-0004_A-20DE-22-C7D8-O000A"]
order_numbers = ["230021SU", "230041SU"]

[[device]]
address = "1.1.47"
product = "230021SU"
application = "M-0004_A-20DE-22-C7D8-O000A"
product_sha256 = "5e0c…"
application_id = "000420DE22"
manufacturer = "Albrecht Jung"
manufacturer_ref = "M-0004"
mask = "07B0"
secure_capable = true
application_version = 34
channels = [
  { key = "relaisausgaenge-1", id = "MD-3_M-18_MI-1_CH-25", number = 25, text = "Relaisausgänge", label_ref = "MD-3_M-18_MI-1_P-13_R-13", base = 2915 },
]
objects = [
  { number = 138, key = "regenalarm",      text = "Jalousie - Sicherheit - Eingang", function = "Regenalarm",     dpt = "1.005", flags = "CWU",  ref = "O-138_R-13" },
  { number = 144, key = "langzeitbetrieb", channel = "relaisausgaenge-1", function = "Langzeitbetrieb", dpt = "1.008", flags = "CWU",  ref = "MD-3_M-18_MI-1_O-2-0_R-38" },
  { number = 162, key = "rueckmeldung-lueftungsklappen-dachfensterposition", channel = "relaisausgaenge-1", dpt = "5.001", flags = "CRTU", ref = "MD-3_M-18_MI-1_O-2-18_R-11" },
]
parameters = [
  { key = "regenalarm",  ref = "P-19_R-38",                                     param = "P-19" },
  { key = "betriebsart", channel = "relaisausgaenge-1", ref = "MD-3_M-18_MI-1_P-14_R-14", param = "MD-3_P-14" },
]
hidden = [
  { ref = "MD-3_M-18_MI-1_P-103_R-160", value = "1" },
]

hardware_ref, has_fdsk_certificate, sequence_number and module_bases are absent here rather than false or zero: this application resolves no distinct hardware ref, and the device is not secured. MD-3_M-18_MI-1_P-103_R-160 is a parameter whose effective Access is "None": ETS stores a value for it but never lets you edit it, so it gets no device-file key.

Keys

Top level

Key Type Meaning
version integer The lock format version: 4 when a device entry carries a serial_number, 3 otherwise. See Lock version.
written_by string The build that wrote the lock (bussard 0.1.0, plus the short git commit when the build has one). Informational only.
source string The file the project was imported from.
language string The language the lock's texts and keys were derived in. See Text language.
[[product]] array of tables One entry per product-data archive the project depends on.
[[device]] array of tables One entry per device, sorted by address.

[[product]]

Key Type Meaning
sha256 string The archive's content hash, its identity. Every use verifies the file against it first.
file path The archive's path under products/. Absent only for an export whose program could not be extracted.
filename string The archive's file name.
size integer The archive's size in bytes.
origin inline table How to get the archive back: { kind = "index", order_number, url } (downloaded through the pointer index), { kind = "file", path } (a .knxprod given to import-product or adopt), or { kind = "knxproj", path, project_hash } (a program extracted once from an ETS export; project_hash is the export's hash).
applications array of strings The application programs the archive carries.
order_numbers array of strings The hardware its catalogue maps to one of them.

[[device]]

Key Type Meaning
address string The device's address.
product string The order number. Must equal the device file's product (E022).
application string The application program ref the device runs.
product_sha256 string The [[product]] entry that carries the application (E032 when there is none).
application_id string The PID_PROGRAM_VERSION the device must report, as ten hex digits: manufacturer, application number, version.
application_version integer The program's ApplicationVersion.
manufacturer string The manufacturer's name.
manufacturer_ref string The manufacturer id, for example M-0004.
hardware_ref string, optional The hardware ref, when the application resolves a distinct one.
mask string The mask version (the device's system type), for example 07B0.
serial_number string, optional The serial number the device reported (PID 11 of the device object), twelve upper-case hex digits, for example 00FA01020304. adopt, assign, scan and describe record it; a device certificate's serial selects its device by it (bussard keys add-certificate). A serial is held by one device only: recording it on one removes it from any other.
secure_capable bool, optional The device can run KNX Data Secure.
has_fdsk_certificate bool, optional The device carries a factory key certificate.
sequence_number integer, optional The device's Data Secure sequence number as the project recorded it.
secure_senders array of tables, optional The security individual address table (PID 54) adopt read back: one { address = "1.1.5", sequence = 275149400526 } row per sender the device accepts secured group telegrams from. Not key material.
module_bases array, optional The base offsets of module instances that own no channel.
channels[] array of tables The device's channels: key, id, number, text, label_ref, base.
objects[] array of tables Every communication object the device has, linked or not: number, key, channel, text, function, dpt, size, flags, ref, secure.
parameters[] array of tables The parameter index: key, channel, ref, param, default.
hidden[] array of tables Values ETS stores for refs the configuration does not show: ref, value.

channels[], objects[], parameters[] and hidden[]

Key Meaning
channels[].key The handle used in [channel.<key>]. Without a key, the handle is id.
channels[].id The application's channel id, or the module-instance channel id.
channels[].number, channels[].text The vendor's channel number and text.
channels[].label_ref The parameter ref that carries the channel label (TextParameterRefId), when the vendor defines one. It gets no key: its value is the channel name.
channels[].base The module-instance base offset, when the channel is a module instance.
objects[].key Present when a key could be derived.
objects[].channel The channel handle the object belongs to.
objects[].text, function, dpt, size, flags, ref The vendor's object definition.
objects[].secure The object runs Data Secure.
parameters[].key The device-file key.
parameters[].channel The channel handle.
parameters[].ref The visible parameter ref.
parameters[].param The parameter id (the memory cell).
parameters[].default Present when the ref's Value overrides the parameter's own default; that override is the default ETS shows.
hidden[].ref, hidden[].value A ref and the value ETS stores for it.

Notes

Products and devices

  • A save keeps every [[product]] entry a device links and every entry that names an archive.
  • A device served both by an archive in the project and by an ETS export links the archive. A save links an unlinked device to an archive entry that lists its order number and application, and drops a link whose entry no longer lists the device's application.
  • application_id and application_version follow from the application ref (M-0004_A-20DE-22-… is manufacturer 0004, application 20DE, version 0x22). The lock writes them so a reader does not need the product data.

Identity checks

describe, plan, reconstruct and apply compare application_id and mask with what the device reports:

  • describe and reconstruct print an identity verdict: match, drift or unmodelled;
  • plan warns on drift;
  • apply refuses a drifted device before any write, naming the bussard flash it needs;
  • audit lists the devices whose stored facts drifted, the devices with no pinned product data, and pinned archives that are missing or changed.

flash, apply, commission --flash and replace refuse a pinned archive that is missing or whose hash is not the one the lock pins, before any bus access. --product <FILE> stays the explicit override.

The parameter index

  • parameters[] lists every parameter the evaluated configuration shows, whether the device file holds a value for it or it is at its vendor default, plus any other ref the file holds a value for.
  • Only one ref per parameter id appears. A parameter only an <Assign> reaches is listed only when the file holds a value for it.
  • The rest of the program's parameters, with their texts, types and defaults, are in the product model under .bussard/model-cache/.
  • An MCP knx_set_parameter re-derives the channels, objects and this index under the new value when the archive is pinned, keeping every existing handle and key.
  • channels[] leaves out a channel with nothing to configure: one whose only parameters have the effective Access "None" and that holds no object (ETS bookkeeping such as Jung's "Applikationsinstanzen").

hidden[]

hidden[] holds the values ETS stores for parameter refs the evaluated configuration does not show: refs in an inactive branch, the alternatives of a shown ref, and refs whose effective Access is "None". You never see them in ETS, so they are generated data: a flash writes them as ETS would, the device file does not show them, and every import replaces them.

One spelling per ref: a ref has one value, in the device file under its parameters[] key or in hidden[], never both.

  • A hidden[] row whose ref parameters[] also indexes, and that the configuration reaches under the current values, is read as the value of that visible key. Whoever saves next (an import, an MCP edit) writes it into the device file and drops the row.
  • The index alone is not reachability: it was built under the configuration the lock was last refreshed with. A row of an indexed ref the configuration does not reach stays hidden; the flash writes it.
  • When the device file stores the ref as well, the file's value wins.
  • diff and the checklist compare parameters by ref, so a key spelled differently on the two sides is no change.

KNX Secure state

The product facts (program, manufacturer, hardware, mask) and the device's KNX Secure state (secure_capable, has_fdsk_certificate, sequence_number, secure_senders) live here; the device file keeps only the intent.

  • A secured flash or apply writes the secure_senders rows back next to the senders the project's links imply; a sender the links imply takes the derived sequence. A device keeps accepting senders the project does not describe. An import never writes secure_senders.
  • An object's secure is set by the import (from the ETS project's group keys) and by adopt (from the device's PID 61). bussard groups secure and knx_set_group with secure change it with its group address. A verified secured apply or flash rewrites it for the linked objects to the flags the security object received.

Text language

Channel and object texts, parameter keys and enum labels come from the vendor's program, which carries its texts in a DefaultLanguage plus translation layers. import picks one language for all devices:

  1. [import] language in bussard.toml, when set;
  2. else the language the existing lock records, so a re-import keeps the keys it wrote;
  3. else the language the ETS project states (Language or DefaultLanguage on ProjectInformation; ETS 6 exports usually state none);
  4. else the one language every program in the project offers, as default or translation. ETS exports the translations of the languages the project uses, so a German project's programs all carry de-DE even when their default is en-US. A language that is only every program's default gives way to a common translation; several candidates prefer en-US;
  5. else the most common DefaultLanguage, else en-US.

A program without the chosen language keeps its untranslated texts. The choice is recorded as the lock's language. Changing the override and importing again rewrites the keys in the new language.

Key derivation

import and adopt derive the keys and record them in the lock.

Channel handle. A stem, then -<n>.

  • The stem is the slug of the channel Name when that is a plain label: only letters (umlauts included), digits and spaces, at most 24 characters as a slug, and contained in the slug of the channel's text, when there is one, as a whole --separated word. regler is not contained in raumtemperaturregler, a longer word it happens to end with, but is in heizung-regler.
  • Vendors that use Name for an internal id (SMOD0_MotionDetector1_MP_CT_1, LICHTAUSGANG_1, W1 - TSM - Wippe 1), for an untranslated word (Manual operation next to Manuelle Bedienung), or for a word the text merely ends with, fail that test. The stem is then the slug of the channel's Text in the import language, with module arguments filled in and the label placeholder stripped. A placeholder's default text, as in {{0: Eingang g+h}}, stays.
  • n is the channel Number, or for a module-instantiated channel the instance ordinal (1-based, in M-<m> order). It is not appended when the stem already ends with -<n>.
  • A module channel whose text ends with a number after its arguments are filled in (Ventilausgang 3) takes that text as its handle, since the number is the instance's own.
  • Without a stem the handle is ch-<ordinal>.
  • Handles are unique per device; a collision appends the ordinal.

Object key. The shortest of these that is unique within the channel, or within the device-level scope: the slug of FunctionText; the slug of Text + FunctionText; either of those with -<number>. No key when the vendor gives no text at all; the file then uses the number.

Parameter key. The slug of the parameter Text (falling back to Name) when unique within its scope; else <page slug>.<slug>, using the ParameterBlock text the ref sits in; else <slug>@<ref> as the escape hatch.

  • Only a parameter the configuration shows and lets you edit gets a key.
  • The escape hatch is for such a parameter whose text still collides after page qualification, never for a hidden ref or one whose effective Access is "None". Keeping those out of the competition usually spares a same-named sibling the escape hatch.
  • The channel's label parameter (label_ref) gets no key: its value is the channel name.

Slugs. Lowercase; ä ö ü ß become ae oe ue ss; everything not [a-z0-9] collapses to -; trimmed; empty becomes x.

Staleness

  • Validation compares each device file's product with the lock entry and reports E022 when they differ or when the entry is missing, naming the command to run.
  • A lock entry for a device that has no file is dropped on the next save.
  • E032 (a warning) reports a product_sha256 with no [[product]] entry.
  • E033 (a warning) reports a [[product]] entry whose file the project folder does not hold, with the command that gets it back.

Lock version

bussard reads lock versions 3 and 4. It writes version 4 when a device entry carries a serial_number and version 3 otherwise, so a lock without serial numbers stays readable by a build that reads only version 3. A lock of another version, or a version 3 lock that carries a serial_number, is refused with the fix: bussard import <export> --dir <dir> regenerates it.

  • Any change to the lock's schema (a field added, renamed or removed) bumps the version. A build reads an older version only when the newer one just adds optional keys, as version 4 does.
  • bussard reads version before anything else, so a build that meets a newer lock refuses it with the version message instead of a field error. Since it never reads that lock, it can never rewrite it with fields dropped.
  • written_by is never checked and never used for compatibility, and a lock without it loads. A version refusal quotes it: lock format version 2, written by bussard 0.1.0 8d6e18f, is not supported.
  • The device files carry no format version; they are user-owned and validated field by field.

Version history: 2 added the [[product]] entries and the per-device product hash and application id; 3 indexes the parameters at their vendor default in parameters[], and adds their default and written_by; 4 adds the per-device serial_number.