The assistant over MCP¶
An LLM assistant can read your installation and edit your project freely, but it reaches the bus only through tiers you switch on, and each physical step waits for your explicit yes. This page explains the tiers and the rails on each.
Every workflow the how-to guides describe can run from chat, with two
exceptions on purpose: a write to a group address marked protected = true
(only bussard write --force at the terminal reaches it), and securing
a factory-fresh device with KNX Secure, which stays with ETS.
Each tier adds to the one before¶
bussard mcp runs at one of four bus tiers, plus an optional Home Assistant
tier:
| Tier | Flag | What the assistant can do |
|---|---|---|
| Passive | --passive |
Read and edit the project files, watch the bus. Nothing is transmitted. |
| Read | none | Also read group values and introspect devices, rate-limited. |
| Write | --allow-writes |
Also send group values (knx_write_group, knx_run_tests). Protected addresses are refused. |
| Programming | --allow-programming |
Also write one device's link tables and parameters after you approve the plan, replay a parameter backup (knx_restore_parameters), clear a Secure device's security failures log (knx_clear_security_log), switch KNXnet/IP Secure of an IP interface (knx_interface_secure), add a new device (knx_add_device), replace a dead one (knx_replace_device) and commission a line (knx_commission_line), each after your yes. Not with --passive. |
| Home Assistant | --allow-home-assistant |
Read Home Assistant and rewrite its KNX configuration, each change after your yes. Never touches the bus. |
Edits to the project touch files only, at every tier; --no-model-edits withholds
them. A parameter value set with knx_set_parameter reaches a device through
the same plan and apply as a link. The server's instructions, each edit's
next_step and knx_project_summary state the active tier, so the assistant
tells you which push actually applies.
flowchart TB
passive["Passive<br><code>--passive</code><br>reads and edits the project,<br>watches the bus"] -->|adds reads<br>on the bus| read["Read<br>(default)"]
read -->|adds group values| write["Write<br><code>--allow-writes</code>"]
write -->|adds programming one device<br>after your yes| prog["Programming<br><code>--allow-programming</code>"]
A write-enabled server pointed at a real gateway refuses to start without
--allow-remote-gateway or an exported BUSSARD_ALLOW_REAL_GATEWAY=1, as on
Safety. knx_bus_reconnect at the read tier only reopens the
connection to the interface and sends nothing onto the bus.
Protected addresses have no override over MCP¶
At the CLI you can force a write to a protected = true group address with
--force. Over MCP no override exists, at any tier: the assistant cannot
write a protected address, rename or retype it, add or remove a link to it,
or set or clear the flag. knx_run_tests refuses a protected test whatever
tests.toml says, and a plan whose changes touch a protected address is
refused.
The asymmetry is deliberate. A human who types --force means to. An
assistant never gets that choice, so keep every dangerous address marked
protected = true and the MCP path can never touch it.
Any change near one is rendered with "This group address is protected." and
sorted to the top of bussard status.
The programming tier writes one approved plan¶
bussard mcp --allow-programming gives the assistant the single-device
write of bussard apply: the link tables and the parameter octets that
differ, written by the same code the CLI runs. Every CLI gate applies, plus a
plan digest:
- Write gate. Checked at startup and again on every call.
- Source-address check. Both tools probe before they connect, as Device support describes.
- Plan digest.
knx_plan_devicereads the device and returns the plan plus aplan_digest.knx_apply_devicewrites only when the digest came from the same session within--plan-ttl-minutes(default 10) and a fresh read reproduces it. A digest is single use. - Your approval. The assistant shows you the plan and calls
knx_apply_deviceonly after an explicit yes. The digest makes this checkable: an apply can only write what a plan showed. - Protected addresses in the plan refuse it.
- Identity. A device whose application or mask differs from the lock
gets the pinned application loaded, after your yes to loading it (see
below); without a pinned archive it is refused with the
bussard flashit needs.
If ETS or another tool changed the device, or the project was edited, the
apply is refused and the digest retired. With plan_hash, the apply also
refuses when the device no longer produces the plan's state_hash, the
hash bussard plan --json prints.
An apply then runs the CLI rails: the backups to captures/backups/ (no
backup, no write), a history snapshot naming the gateway, the table write,
the parameter download, and a read-back of each. The result carries the
verify outcome, what was written and the backup paths. With line, the same
job writes every device your project has on a line.
The safety net around an apply is in chat too. knx_backup_device and
knx_reconstruct_device back a device up and read its tables back against
your project; they only read, so they are in the default tier.
knx_restore_tables writes a backup's link tables back through the same
plan, approval and read-back as an apply, and knx_restart_device restarts
a device in the form ETS uses, after your yes.
Details
The digest is a SHA-256 over the device address, the project's links and
parameter values for it, the desired tables, the parameter image the
write would stream, and the live tables and parameter memory it read.
The history snapshot is named mcp knx_apply_device <address> <digest>.
Adding a device is one flow¶
knx_add_device is bussard adopt in chat, on the same functions. The
assistant asks you to press the programming button on the new device; the
server waits for its answer as long as the CLI does (30 seconds). It then
reads what the device is (serial number, mask, order number), picks the
address (the one you named, else the next free one), looks up its product
data, and shows you the plan with a digest. Nothing is written yet.
After your yes it checks the device again, writes the address, reads the
device back at the new address, and writes the device file and its lock
entry. Downloading the vendor's product data is a separate question:
your yes to the address does not answer it. A device the key store lists keeps
its address and is read over KNX Data Secure, as adopt does; securing a
factory-fresh device stays with ETS.
Commissioning a line is one job¶
knx_commission_line is bussard commission --line in chat, on the same
functions. The assistant shows you the devices your project has on the line
and asks once. Your yes covers the whole line, as the CLI's one
confirmation does. Devices that already answer at their address are
skipped. For each other device the assistant names the one to press, by
name, room and order number. The server reads the pressed device's order
number before it writes anything; when it is the product your project
expects, it writes the address, reads the device back at it and gives you
the label text, without asking again.
When the pressed device is another product, reports no order number, or
nothing or two devices answer, the job waits for your word: retry, skip
that device, or stop. A device your project has no order number for waits
too, and you can say assign. You can stop the run at any time. Only
addresses are written; links, parameters and the application follow per
device with knx_plan_device and knx_apply_device.
Replacing a dead device is one flow¶
knx_replace_device is bussard replace in chat, on the same step machine.
It first keeps a backup: a history snapshot of the project, the dead device's
file and its lock record included. The server checks that nothing answers at
the address any more, and the assistant asks you to press the programming
button on the replacement. The server reads what it is (serial number, mask,
order number, the application it runs) and refuses another product than the
device file and the lock name. It then shows you the plan with one digest
for the address, the application and the links. Nothing is written yet.
After your one yes it checks the device again, writes the address and reads
it back, then plans and writes the device as knx_plan_device and
knx_apply_device do: the application the lock pins is loaded when the
replacement does not run it, your project's parameters and links are written,
and the result says verified only when the read-back matches your project. Only
then are the replacement and the new serial number recorded in the device
file and the lock. A device your project records as secured is refused:
securing its replacement stays with ETS.
A com-object change becomes a flash¶
A parameter that shows or hides a com-object changes the group-object table,
which a parameter download does not rewrite. The same plan and apply pair
then flashes the device: the plan says method: flash, lists the
com-objects that appear or disappear, the table sizes, the parameter backup
and the pinned archive, and asks to flash. The device restarts and is offline
for the stated time, 30 to 50 seconds. It is the flash bussard flash <ia>
--yes writes, refused without an archive pinned in the lock, for a device
carrying another application, or whose load state cannot be read.
Loading an application from chat¶
When a device does not run the application program the lock pins (another
one, or none loaded), the plan says so first: its sentences start with
"must have its application program loaded" and say what it replaces. One yes
to the plan's question loads the application and writes your project's
parameters and links with it, as one job. It runs the same functions as
bussard flash: the download, the read-back against your project and the lock
update, so the result says verified only when the device matches your project.
When the application's download writes no link table and your links
differ, the plan says so and the same yes also writes the links afterwards,
as bussard apply does, with its own read-back. A device whose state cannot
be read, or whose application bussard cannot identify, is refused; bussard flash --force at the terminal stays the way
to overwrite it.
Parameters are approved by name¶
The plan lists every parameter that differs by key, vendor text, device value
and project value, one sentence each. The write streams only the differing
octets, after the tables, and reads them back. Device-managed parameters
(values the application owns at runtime) never make a plan non-empty on
their own; the plan lists them with the role device_managed.
When the pinned product data is missing or changed, the plan leaves the
parameters out with the recovery line (bussard import-product ...) and says
it writes the links only. Once the archive is back, a new plan covers them.
Secured devices follow the CLI¶
A device the server's key store lists is planned and written over Data Secure,
as bussard apply --keyring does. The plan shows what the security object
receives (senders, keyed addresses, secured objects, never a key). A
secure = true address without a key refuses the plan, and a key store or flag
change between plan and apply retires it. A device your project marks secured
but the key store does not list is refused.
The apply runs as a job¶
A client may cut a tool call at 60 seconds, which a secured apply with a
restart exceeds. knx_apply_device runs every gate, the snapshot and the
backups inside the call, and the write as a job in the server:
- A refusal in the pre-flight is the reply; nothing was written.
- The call waits up to 20 seconds. If the write ends, the reply is the full
result; if not, it is
started: truewith a job id, andknx_job_status {job}reports the step, the progress and the result (knx_apply_statusstill answers too). - One apply per server at a time. Another apply or plan while a job runs is refused with the job's id.
- The job record is written to
apply-result.jsonin its history snapshot.knx_last_apply {address}returns the latest job for a device, even after a server restart. A record a stopped server left running reads asinterrupted: plan again before trusting the device. - The status tools never touch the bus.
The Home Assistant tier changes one file¶
--allow-home-assistant needs the [home_assistant] table in
bussard.toml as well; with only one of the two, the tools are not
registered.
- Every change needs your explicit yes. Reads are free (
knx_ha_status,knx_ha_plan). A write goes through a plan, its sentences, your yes, and the same single-use, time-limited digest as device programming. - The token comes only from the variable
home_assistant.token_envnames (defaultBUSSARD_HA_TOKEN) and appears in no result, error or log. Keep it in an untracked.env, and revoke it on your Home Assistant profile page when the laptop leaves. - One file. Only
config_pathis written, and only when it is YAML-managed (aknx:package file, or the inside of aknx: !include). The old bytes go tocaptures/backups/ha/first and the replacement is atomic. Entities created in Home Assistant's UI are never touched. - Reload after success only. The apply checks the token first, calls
knx.reloadonly after the write, and reads the status again. A failed reload is reported with the backup path; restore by copying it back. - Automations. bussard writes only ids starting with
bussard_whose description carriesmanaged by bussard (model <dir>), and refuses a hand-made one. The previous JSON is kept undercaptures/backups/ha/before an update or removal. Every address must be ingroups.tomlwith a matching DPT (data type), and none may beprotected. - No other change. The tier calls
knx.reloadandautomation.reloadand no other service.
Undo takes back files, never the bus¶
bussard copies the project files to <dir>/.bussard/history before every
command that writes them or the bus, and before every edit over MCP. bussard status says what changed since the last snapshot, bussard
history lists them, and bussard undo puts the files back.
undo sends nothing on the bus: after it, the installation behaves exactly
as before. The restored project reaches a device only when it is planned and
written again: by you with bussard plan <ia> and bussard apply <ia>, or by
the assistant with knx_plan_device and knx_apply_device after your yes. An undo is snapshotted first, so
it can be undone.
Snapshots carry the project files (bussard.toml, groups.toml,
bussard.lock, devices/*.toml, and tests.toml and ha.toml when
present). A Data Secure switch of a group address also keeps a copy of the
encrypted key store, so undo restores the key. A snapshot never holds a
password, a plain key or vendor data. A bundle from bussard export holds the same files, the
snapshots and a manifest, copied from an allow-list: never products/,
captures, keyrings, .knxproj or .knxprod files, or .env. It carries your gateway address
in bussard.toml, and an import into an existing project keeps the
recipient's own. Importing a bundle writes files only.
Next steps¶
- Connect an assistant: set up the server and have a first conversation.
- MCP tools: every tool, its tier and its arguments.
- History commands:
history,showandundo. - Home Assistant: generate and tune the configuration.