bussard.toml¶
bussard.toml holds the connection to the bus, the optional lint rules, the import language, the Home Assistant connection and the certificate enrolment relay. bussard init writes it; after that it is yours to edit. bussard never rewrites it, except to append a [lint] table when one is missing (bussard groups reserve does this the first time it runs).
Example¶
[connection]
transport = "tunnel" # "tunnel" | "routing"
gateway = "192.0.2.10:3671" # host:port for tunnelling
# multicast = "224.0.23.12:3671" # addr:port for routing; this is the default
# keyring = "house.knxkeys" # deprecated: use the key store bussard.keys
# admit_tunnel_senders = true # Data Secure: admit the key store's tunnelling
# addresses as secure senders
[lint.topology]
max_devices_per_line = 64
[lint.topology.supply_ma]
"1.1" = 640
[lint.groups]
scheme = "floor-trade-block" # or "function-floor"
feedback_pairing = true
name_pattern = "* * *"
[lint.groups.blocks]
light = 5
blind = 10
heating = 10
[import]
# language = "de-DE" # text language of import
[home_assistant] # optional: the MCP server's Home Assistant tier
url = "http://homeassistant.local:8123"
token_env = "BUSSARD_HA_TOKEN" # default; the token itself never goes here
config_path = "../ha/knx.yaml" # the KNX YAML Home Assistant reads
[enroll] # optional: bussard keys enroll, knx_enroll_certificates
# relay = "https://bussard-relay.tmbo.dev" # the enrolment relay; the default
# page = "https://bussard-relay.tmbo.dev/enroll/" # the page the link opens; the default
Keys¶
| Key | Type | Meaning |
|---|---|---|
connection.transport |
"tunnel" or "routing" |
The transport used to reach the bus. |
connection.gateway |
string, optional | Gateway host:port for tunnelling. --gateway and BUSSARD_GATEWAY override it. |
connection.multicast |
string, optional | Multicast addr:port for routing. Default 224.0.23.12:3671. |
connection.keyring |
path, optional | Deprecated: use the key store bussard.keys, which wins over it. The ETS .knxkeys keyring every bus command uses when --keyring is not given: for the KNXnet/IP Secure tunnel, the tool keys of the devices it lists, and the group keys. A relative path is resolved against the project folder. The password comes from BUSSARD_KEYRING_PASSWORD. Keep the keyring file itself out of git. |
connection.admit_tunnel_senders |
bool, default false |
On a KNX Data Secure device, plan, apply, flash and knx_apply_device add every tunnelling address of the key store to the device's security individual address table (PID 54), so a secured write or read from bussard is accepted. |
lint.topology.max_devices_per_line |
integer, optional | The most devices one line may carry (the KNX TP limit is 64). Drives L001. |
lint.topology.supply_ma |
table line to mA, optional | Each line's power-supply budget. Drives L002. Declaring a line here also declares that it exists, which drives L003. |
lint.groups.scheme |
"floor-trade-block" or "function-floor", optional |
Which address level carries the floor and which the trade. The convention lints and groups reserve follow it. |
lint.groups.blocks |
table trade to size, optional | How many consecutive sub addresses each trade reserves per room. A trade that is absent is not part of the plan. |
lint.groups.feedback_pairing |
bool, default false |
Require the feedback address the block layout reserves for each command address. |
lint.groups.name_pattern |
string, optional | A glob every group address name must match: * is any run of characters (including none), ? exactly one, everything else literal. |
import.language |
string, optional | Overrides the language import derives texts and keys in. See Text language. |
home_assistant.url |
string | The Home Assistant instance. |
home_assistant.token_env |
string, default BUSSARD_HA_TOKEN |
The environment variable that holds a long-lived access token. A .env supplies it only for a BUSSARD_* name. |
home_assistant.config_path |
path | The KNX YAML file Home Assistant reads, relative to the project folder unless absolute. |
enroll.relay |
string, optional | The relay base URL keys enroll and the MCP tool knx_enroll_certificates use when --relay is not given. Default https://bussard-relay.tmbo.dev. The hosted page connects only to that relay, so a self-hosted relay needs a self-hosted copy of the page (web/enroll/, its CSP connect-src naming the relay) set as enroll.page. --local (local: true over MCP) uses neither. The relay only sees ciphertext. |
enroll.page |
string, optional | The enrolment page the keys enroll and knx_enroll_certificates link opens when --page is not given. Default https://bussard-relay.tmbo.dev/enroll/. |
Notes¶
[lint]is opt-in. Without it nothing extra is reported, so adding the feature cannot change an existing project. With it,validateruns the topology and convention rulesL001toL008(see Diagnostics).- Bus current for
L002comes from the product models in.bussard/model-cache/, written byimport-productfrom theBusCurrentin the.knxprodHardware.xml. Devices with no product model contribute nothing and are counted in the warning. [home_assistant]is optional. With it,bussard mcp --allow-home-assistantregisters the Home Assistant tools; without it the flag does nothing.admit_tunnel_sendersis off by default. The reason it exists is in Safety.
Related¶
- Global options: the flags that override
[connection]. - Environment variables:
BUSSARD_GATEWAY,BUSSARD_KEYRINGandBUSSARD_HA_TOKEN. - Diagnostics: the
Lcodes the[lint]table turns on. - MCP tools: the Home Assistant tier
[home_assistant]configures.