Skip to content

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:

  1. Write gate. Checked at startup and again on every call.
  2. Source-address check. Both tools probe before they connect, as Device support describes.
  3. Plan digest. knx_plan_device reads the device and returns the plan plus a plan_digest. knx_apply_device writes 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.
  4. Your approval. The assistant shows you the plan and calls knx_apply_device only after an explicit yes. The digest makes this checkable: an apply can only write what a plan showed.
  5. Protected addresses in the plan refuse it.
  6. 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 flash it 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: true with a job id, and knx_job_status {job} reports the step, the progress and the result (knx_apply_status still 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.json in 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 as interrupted: 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_env names (default BUSSARD_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_path is written, and only when it is YAML-managed (a knx: package file, or the inside of a knx: !include). The old bytes go to captures/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.reload only 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 carries managed by bussard (model <dir>), and refuses a hand-made one. The previous JSON is kept under captures/backups/ha/ before an update or removal. Every address must be in groups.toml with a matching DPT (data type), and none may be protected.
  • No other change. The tier calls knx.reload and automation.reload and 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