Device files¶
A device file, devices/<address>.toml, holds one device: its name and location, its parameter values and its links to group addresses. import and adopt write it; after that it is yours in full. Parameters and objects sit in the table of the channel they belong to, keyed by the handles bussard.lock assigns.
Example¶
devices/1.1.47.toml, based on a real import of a Jung 2300.21 SU switch and blind module, trimmed:
address = "1.1.47"
name = "Switch actuator, 2-gang / blinds actuator, 1-gang"
description = "Fenster"
product = "230021SU" # order number, printed on the device
[location]
floor = "DG"
room = "Gast 2 Süd"
[parameters] # device-level parameters (no channel)
regenalarm = "1"
[links] # device-level objects (no channel)
regenalarm.listen = ["4/1/8"]
[channel.relaisausgaenge-1] # handle from the lock
name = "Fenster Süd" # your name for the channel
bei-regenalarm = "schließen" # parameter: scalar value
betriebsart = "Lüftungsklappe / Dachfenster"
langzeitbetrieb.listen = ["3/1/20"] # command object: listens
kurzzeitbetrieb.listen = ["3/1/21"]
rueckmeldung-lueftungsklappen-dachfensterposition.send = "3/1/23" # status object: sends
This device carries no [security] table, because the device is not secured. application and replaced are optional fields it happens not to set. bussard device <address> <channel> lists the keys a channel accepts, with their texts and ranges.
Top level¶
| Key | Type | Meaning |
|---|---|---|
address |
string | The device identity, its address. Must match the file name (E002). |
name |
string | Display name. Required. |
description |
string, optional | Free text. |
product |
string, optional | The order number. The join key into the lock and the product data; needed for anything beyond links. |
application |
string, optional | Override of the application program the lock pins. |
replaced |
string, optional | RFC 3339 timestamp, written by bussard replace. |
[location] |
floor, room |
Physical location. Optional. |
[security] |
activated, secure_commissioning |
Intent only; activated = true means secured. What the device and the ETS project generated (secure_capable, has_fdsk_certificate, sequence_number) lives in the lock; key material never appears in either. |
[knxnet] |
table | The KNXnet/IP settings of an IP interface, or of a device with one built in, intent only. See [knxnet]. |
[parameters] |
table | Device-level parameters. |
[links] |
table | Device-level objects. |
[channel.<handle>] |
table | One per channel: name, parameters, objects and parameter pages. |
[parameters] and [links] follow the same rules as a channel table, for the parameters and objects that belong to no channel.
Inside a channel table¶
| Entry | Shape | Meaning |
|---|---|---|
name |
string | Your name for the channel. |
<key> = <value> |
string, integer or bool | A parameter. |
<key>.send |
string, one group address | The address the object transmits on. The object needs the T flag (E025). |
<key>.listen |
array of group addresses | The addresses the object accepts writes from. The object needs the W flag (E025). |
<key>.name |
string | Your override of the object's display name. |
[channel.<handle>.<page>] |
table | A parameter page holding parameters one level down. Exists only where the lock defines one for that channel. |
Every entry other than name is classified by the shape of its value, then checked against the lock:
- a string, integer or bool is a parameter;
- a table whose keys are a subset of
send,listenandnameis an object (a communication object, the device's input or output for one function); - any other table is a parameter page.
Command objects listen; status objects send.
Object keys. An object key is either the key the lock assigns (langzeitbetrieb) or the bare object number (144). Both resolve to the same object; bussard writes the key from the lock when there is one.
Parameter keys. A parameter key is the key the lock assigns. When the same text would repeat within a scope, the lock assigns a longer key: page-qualified (<page>.<key>) or the escape hatch <key>@<ref>. bussard writes whatever the lock says, and reads through the lock. How keys are derived is in Key derivation.
A parameter key the lock does not list, a value you set for the first time, resolves through the product model:
- the key must equal the slug of exactly one parameter's text in the channel's scope (the module definition's parameters for a module channel, the application's own otherwise);
- that parameter must have exactly one ref in the product model;
- the next save adds the key to the lock.
A key that resolves neither way is E023. A <slug>@<ref> escape key always resolves, lock or not; once the lock names that parameter, the next save writes the lock's key instead. A key the lock lists for one channel does not resolve in another channel's table. A device without a lock entry cannot resolve its parameters or object keys; validation reports E021 with the command that creates the entry (adopt, import, or import-product plus import).
What the file shows. The file holds only what ETS shows. ETS also stores values for parameter refs the configuration does not show (an inactive branch, the alternative of a shown ref) or never lets you edit (Access="None"). Those are the lock's hidden[], not the file's.
Without product data¶
The readable keys come from the vendor's product data (.knxprod), not from the ETS project. A device whose product data was never imported still gets a device file, but its channel handles are the vendor's channel ids and its objects are keyed by number. Its parameters can be neither checked nor flashed.
address = "1.1.1"
name = "Push Button Hallway"
description = "4-fold push button with status LEDs"
product = "PB-4F"
[location]
floor = "Ground Floor"
room = "Hallway"
[links]
40.send = "3/1/0"
40.name = "Spare Output"
[channel.CH-1]
name = "Rocker 1 - Hallway Light"
0.send = "0/0/0"
0.name = "Hallway Light - Switch"
1.listen = ["0/0/1"]
1.name = "Hallway Light - Status LED"
Once the product data is available, import or adopt rewrites the lock with keys, and the next save writes the readable form. The object numbers stay valid as keys either way.
Parameter values¶
The file stores the value you mean. bussard accepts:
- a string: an enum label (
"Jalousie"), an enum code ("2"), a number with unit ("21 °C","15 min"), free text for a text parameter, which must fit the field in the program's text code page, or a colour for a colour parameter ("#FF8000","#FF800010"with a white channel); - an integer or a bool, converted to its string form.
A float is refused with a fix-it hint, because 1.10 and 1.1 cannot be told apart after parsing.
When the product model is available in .bussard/model-cache/, the value is normalized to the vendor code: an enum label becomes its code, and a number with unit is checked against the range. Without the product model the string is kept as written, and validation reports that the value could not be checked (E026).
flash, plan, apply, reconstruct and replace resolve an enum label against the vendor program itself, read in the lock's language (see Text language). A label matches, in this order:
- the member's text in the lock's language;
- else its untranslated text (the program's
DefaultLanguage); - else its text in any other language the program carries, so a file edited from an English catalogue still loads under a German lock.
The first step with a match decides. A label two members share at that step is refused as ambiguous. A label no member carries is refused with the list of labels in the lock's language. import-product writes .bussard/model-cache/ in the same language, so the MCP knx_set_parameter check accepts the labels the device files carry.
The [knxnet] table¶
A KNX IP interface or router carries the settings of its KNXnet/IP parameter object (interface object type 11) in a [knxnet] table:
[knxnet]
assignment = "dhcp" # or "static"
address = "192.0.2.10" # static only
netmask = "255.255.255.0" # static only
gateway = "192.0.2.1" # static only
friendly_name = "Demohouse Alpha"
tunnels = ["1.1.22", "1.1.23", "1.1.24", "1.1.25", "1.1.26", "1.1.27", "1.1.28", "1.1.29"]
| Key | Type | Meaning |
|---|---|---|
assignment |
"dhcp" or "static" |
How the interface gets its IP address. Default "dhcp". |
address |
IPv4 string | With static only, and required there (E043). |
netmask |
IPv4 string | With static only, and required there (E043). |
gateway |
IPv4 string | With static only. |
friendly_name |
string | At most 30 ISO 8859-1 characters (E043). Absent: bussard leaves the device's name alone. |
tunnels |
array of addresses | The tunnelling slots, in order (PID_ADDITIONAL_INDIVIDUAL_ADDRESSES). |
The table is what you mean. What the device reports (the address, netmask and gateway in use, the assignment method in effect, the MAC address, the capabilities and the state) are device facts in .bussard/facts/<address>.toml (see Project folder), never in this file or in the lock.
Where the values come from:
importreads the device instance's<IPConfig>and<AdditionalAddresses>.Assign="Fixed"isstatic, with the ETS project'sIPAddress,SubnetMaskandDefaultGateway. Anything else, including noAssignat all, isdhcp, the ETS default, and the ETS project'sIPAddress(the last address ETS saw) is not kept. Each<Address Address="22"/>is a tunnel address on the interface's own line, in document order. The ETS project carries no friendly name. The import summary prints one line per interface. Nothing is read from the device's<Security>element: the device authentication code, the management password and the tool key belong to the key store, never to the project files.adoptof an IP interface reads the object and writes the table: the configured method (dhcp, with a note, when the device reports one the device file cannot spell, such as BootP), the static settings whenstatic, the friendly name and the tunnels.- A re-import keeps the file's table. An ETS project whose tunnel addresses or static address differ is reported as a conflict (
knxnet.tunnels,knxnet.address);--theirstakes the ETS project's.
validate checks the table with E043 to E046 and, with the key checks, W047 (see Diagnostics). diff and status describe a change as Interface KNX IP Interface (1.1.200): tunnel address 1.1.30 added.
Warning
plan and apply of an interface with this table and no links write it to the device, and read each value back after the write. A field the table leaves out, and an empty tunnels, stays as the device holds it. Changing the assignment, the static address or the tunnel addresses of the interface the command tunnels through needs apply --allow-self-reconfigure.
Over MCP, knx_set_interface edits the table and knx_plan_device and knx_apply_device write it.
A device with a KNX IP interface built in¶
A bus device whose application declares tunnelling addresses (AdditionalAddressesCount, for example the Zennio ALLinBOX family) has a KNXnet/IP parameter object too. A full flash of such a device writes it after the application and before the closing restart, as ETS does, and reads each value back:
- the routing multicast address 224.0.23.12, the routing TTL 32 and installation id 0, the values ETS writes for a project with its default backbone settings;
friendly_name, required;- the assignment method, which must be
dhcp: no ETS capture shows what a download writes for a static address, sostaticis refused; tunnels, exactly as many as the application declares.
A flash whose device file lacks the table, or one of these values, is refused before anything is written. import fills tunnels and assignment from the ETS project; add friendly_name by hand (ETS uses the device's name).
Details
The writes are property writes on the KNXnet/IP parameter object: the friendly name (PID 76), the tunnel addresses (PID 53), the static address set (PIDs 60 to 62) and the assignment method (PID 55).
Related¶
- bussard.lock: the handles, keys and vendor facts this file is keyed by.
- Device commands:
device,adoptandimport-product. - Programming commands:
plan,applyandflash, which write these values. - Diagnostics: E002, E021 to E026 and the
[knxnet]codes.