Skip to content

MCP tools

What the bussard mcp server offers an assistant: its tiers, every tool, the bus connection, and the gates in front of the programming and Home Assistant tiers.

The server speaks the Model Context Protocol over stdio. Its flags and how to register it with a client are on bussard mcp; why the tiers exist is in The assistant.

Tiers

Four bus tiers, a Home Assistant tier, and a switch for the edits to the project:

Tier Flag On the bus
Passive --passive Never transmits. The bus-touching read tools (knx_read_group, knx_describe_device, knx_backup_device, knx_reconstruct_device, knx_find_devices) and knx_bus_reconnect are not registered, and knx_audit and knx_show_device refuse live: true. knx_bus_status stays.
Read (default) none May send GroupValueReads and read devices (knx_describe_device, knx_backup_device, knx_reconstruct_device, knx_find_devices, knx_show_device with live: true), rate-limited. Never writes a device.
Write --allow-writes Adds knx_write_group and knx_run_tests.
Programming --allow-programming Adds knx_plan_device and knx_apply_device, plus knx_apply_status and knx_last_apply for the apply job, which write one device's link tables and the parameter values that differ after a plan the human approved (or, with line, the link tables of every device on a line), knx_restore_parameters and knx_restore_tables, which replay a parameter backup or a backup's link tables the same way, knx_restart_device, which restarts a device in the form ETS uses, knx_clear_security_log, which clears a Data Secure device's security failures log, knx_interface_secure, which switches KNXnet/IP Secure of an IP interface, knx_add_device, which adds a new device (press the button, identify, assign, product data, device file), knx_replace_device, which replaces a dead device (backup, press the button, identify, assign, flash, apply, record), and knx_commission_line, which gives each device the project has on a line its address (press the button, check the order number, assign, read back, label). Needs a loopback gateway or the real-gateway opt-in. Independent of --allow-writes; not available with --passive.
Home Assistant --allow-home-assistant Never touches the bus. Adds knx_ha_status, knx_ha_plan, knx_ha_apply, knx_ha_automation_plan, knx_ha_automation_apply and knx_ha_automation_remove when bussard.toml has a [home_assistant] table: read Home Assistant, write the KNX YAML it reads, and manage bussard's own automations, each write after a plan the human approved. Combines with every tier above.
No project edits --no-model-edits Withholds the twelve tools that write the project (knx_set_group, knx_remove_group, knx_add_link, knx_remove_link, knx_set_device, knx_set_parameter, knx_set_interface, knx_discard_edits, knx_undo, knx_scaffold_groups, knx_reserve_groups and knx_import_file) and the two that write device certificates into the key store (knx_enroll_certificates, knx_enroll_status). Orthogonal to the tiers above: they write the project's TOML files or the key store, never the bus, so they are registered in every tier by default.
  • On a missing or empty --dir the server starts in its onboarding state with two tools, knx_setup and knx_bus_status. After knx_setup has written the project it registers the full set of the tiers it was started with and sends notifications/tools/list_changed.
  • Tool counts: 32 in --passive, 38 by default, 40 with --allow-writes. --no-model-edits takes 14 away from each (18, 24 and 26). --allow-programming adds 12 to any non-passive tier. The Home Assistant tier adds 6 to any tier.
  • Bus operations share one rate limiter: at least 250 ms between operations, at most two in flight.
  • Two things stay out of chat on purpose. A group address marked protected = true is hard-refused by knx_write_group and knx_run_tests, with no MCP override: the assistant must ask a human, who can run bussard write ... --force at the terminal. Securing a factory-fresh device with KNX Secure (from its factory key, FDSK) stays with ETS; bussard does not implement it on either surface.
  • Every other workflow has its tools. init is knx_setup; import, import-product and keys import are knx_import_file; export, export-groups, keys export and doc are knx_export. adopt (and assign, its first step) is knx_add_device, replace is knx_replace_device, and commission --line (without --flash and --apply) is knx_commission_line. Loading an application program is knx_plan_device and knx_apply_device: when the device does not run the application bussard.lock pins, the plan loads it (see Loading the application). backup, reconstruct <ia>, restore <backup> <ia>, restart, scan and status <ia> have their tools (knx_backup_device, knx_reconstruct_device, knx_restore_tables, knx_restart_device, knx_find_devices, knx_show_device with live: true), and so do the line forms: plan --line and apply --line are knx_plan_device and knx_apply_device with line, reconstruct --line is knx_reconstruct_device with line.

Project tools

The project tools (knx_describe_change, knx_history, the nine that edit, knx_scaffold_groups, knx_reserve_groups and knx_import_file) touch files under the project folder and nothing else. knx_export, its older bundle form knx_export_bundle, and knx_diff_project only read the project (an export writes the one file it names) and are registered in every tier, --no-model-edits included. knx_import_file and knx_export run the functions bussard import, import-product, keys import, export, export-groups, keys export and doc run.

Every edit snapshots the project first, validates after, and returns the change as a summary and as sentences. An edit, knx_undo or knx_discard_edits result carries summary, changes (the sentences), detail (the same changes as JSON), validation and next_step:

  • summary is the change for a homeowner, in one or two sentences: rooms, device, channel and group names, which devices still need a push, and a line when it touches a protected group address. It names no group address, device address, com-object number, parameter key or ETS reference unless the item has no name. knx_describe_change carries one too. The assistant says it first, then quotes the sentences.

  • validation is {ok, errors, error_count, new_warnings, warning_count, for_the_human}; for_the_human says in one line whether anything stops a push or the edit added notes. errors are the project's errors after the edit; new_warnings only the warnings the edit introduced (a warning counts as old when its code, location and message were there before), so an edit that adds none returns []. Each list stops at 20 entries with a note giving the totals; knx_validate returns the full list.

  • Caps. changes and detail stop at 50 entries (knx_describe_change at 200), protected ones first, with a truncated note naming the totals.
  • Names, not ids. A sentence calls a group address or device by its name; the address follows in parentheses only when another group address or device has the same name, or when the group address is protected. An unnamed one reads as its address. A com object without a name of its own is called by the vendor's object text, a channel by its name or vendor text. detail keeps every address.
  • Parameter sentences compare enum values by member: a device file's label and the code the project holds for it are no change. An enum value reads as its label with the code after it (Funktion on Taster is set to Kurzer und langer Tastendruck (5).); detail keeps the values as the project holds them.

The project is not frozen at startup. The server re-reads the project folder when its files change, and immediately after one of its own edits, so a protected = true or a corrected dpt added to groups.toml mid-session is in force on the next tool call. A project that fails to parse is not swapped in; the server keeps the last good one and warns on stderr.

What the server tells the assistant

Clients load tools lazily, so a tool description or a result string is often all the assistant knows at the moment of a call. Every string that depends on what the server may do is built from its active tiers:

  • How to talk. The instructions say once who the reader is: a homeowner unless she says otherwise. The assistant names things the way the project names them (rooms, device, channel and group names), uses ids only in tool calls unless the human asks for them or a thing has no name, says the summary and what_you_will_notice before asking for a yes and quotes the sentences after them, and answers in the human's language; the server writes English.
  • Server instructions. What the server does end to end at its tier, which tools push, and what the active tier leaves to the terminal (without --allow-programming, a parameter that shows or hides com-objects and the load of an application need bussard flash <ia>) or ETS (securing a fresh device, and any setting the product model does not expose). Parameters are edited with knx_set_parameter using the keys knx_show_device lists. To find a device that can provide a function, the assistant uses knx_model_lookup with the function's words and reads knx_show_device for the candidates.
  • knx_get_device versus knx_show_device. The first is the configured state (the device file: links and stored parameters), the second what the device can do (every parameter the configuration shows, the inactive pages and channels with what enables them). Each description says so.
  • next_step after an edit to the project. Names the devices the change touches by name and room; the device address appears only inside the tool call (knx_plan_device {"address": "1.1.4"}) or the CLI command. With --allow-programming, push with knx_plan_device for the device and knx_apply_device after an explicit yes; without it, restart with the flag, or run bussard plan <ia> and bussard apply <ia> at the CLI. Names, rooms and group-address metadata are stored in no device: nothing to push. With the Home Assistant tier on, an edit that touches a group address Home Assistant's KNX config uses adds a line naming knx_ha_plan and knx_ha_apply.
  • Tool descriptions of the edits that reach a device (knx_set_group, knx_add_link, knx_remove_link, knx_set_parameter, knx_set_interface, knx_undo) name knx_plan_device and knx_apply_device as the push step and leave the tier-specific part to next_step.
  • knx_project_summary carries server (tiers, passive, writes, programming, model_edits, home_assistant) and capabilities, one paragraph saying what the assistant may do here.
  • knx_show_device carries how_to_change when unscoped: which tool edits the listed parameters and links, how they are pushed, and the parameter key grammar. Without a product model it says the parameters are not editable yet and what to run.

Tools

Tool Parameters Returns
knx_setup project_file (optional: a .knxproj; default the one .knxproj next to the project folder), gateway (optional: host[:port] or routing; default discovery), password (optional; default BUSSARD_PROJECT_PASSWORD) Onboarding state only. Runs what bussard init runs: finds the gateway, writes the project folder and imports the export with its product data and keyring. Several gateways or projects, none found, or a directory that is no longer empty come back as a question with nothing written. A protected export without a password: a client with URL-mode elicitation gets bussard's password form, a page on 127.0.0.1 where the human types the password. bussard asks again on the page when it is wrong, stores it as BUSSARD_PROJECT_PASSWORD in the .env the server reads and goes on; password in the result says so. Without URL-mode elicitation the result asks for the password in the .env. The password is never repeated. On success: done, summary, the setup's log, tools (the count now registered) and instructions for the full set.
knx_project_summary none Project name, device/GA/link counts, floors and rooms, GA main-range names, bus connection status (bus, the fields of the bus connection), validation counts, server (the active tiers) and capabilities (what the assistant may do here). Call first.
knx_bus_status none The bus connection in detail (see the bus connection): state, connected, transport, interface, tunnel_user, last_error, last_error_at, attempts, retry_in_seconds, connected_since, stopped (a fatal error the bus stopped on), other_instances (pids of other bussard mcp processes for this project folder on this host) and, while down, reason. Read-only; registered in every tier.
knx_bus_reconnect none Drops the connection and connects afresh now: a new socket, a new KNXnet/IP Secure session, the backoff reset. A connected bus disconnects its tunnel and closes its session first. Returns ok (connected after the attempt), bus (the knx_bus_status fields), and reason or note when it did not connect. Not a write: nothing goes onto the KNX bus. Omitted in --passive mode, where the bus reconnects on its own.
knx_model_lookup query (substring), limit (default 50, max 500), technical (optional) Without technical, empty and null fields are left out and a capability's enable steps drop the ETS reference their key already names. Case-insensitive matches across GA names/addresses, device names/IAs, room names, com objects and channels, grouped by kind (groups, devices, objects, channels), plus capabilities. An object matches on the name the device file gives a linked object and, for every object the device has, linked or not, on the vendor text, function and key; each hit carries device_ia, device_name, channel (the handle), object (the number), key, text, function and linked_gas. A channel matches on its vendor text, name or handle and lists its object numbers. capabilities searches what the installed devices could do: the parameter texts and enum choice texts of their product models, every word of the query in the page title, parameter text and choice text together (case and umlaut spelling do not matter: Dämmerung finds daemmerung). One entry per device page or channel: device_ia, block_or_channel, handle (for knx_show_device), the best match's parameter, key and choice, active, selected (the device has it now), status and up to five more matches. Entries that differ only in their channel are one entry whose channels lists the handles (a dimmer's four outputs), and devices of one application with an identical entry are one entry whose also_on lists the other devices. provides entries come first, then could provide ones on inactive pages and channels (spare capacity, with enable and needs as knx_show_device gives them; this includes the channels of module instances the configuration does not reach), then active pages set to another choice. Within each, a device whose com-objects send the measured value the query names (DPT 9.004 for Helligkeit or brightness, 9.001 for Temperatur, and so on) comes first, the one with the most such objects linked to a group address leading; its first entry lists them in sends. The parsed product models are cached as JSON under .bussard/model-cache/<application>.json, rebuilt when the product model file changes. limit bounds each kind.
knx_get_group ga, technical (optional) The GA's definition, every link sending to or listening on it, and the last telegram seen on it. By default each link also carries the device's room and what (the object in words, Eingang 1 of Logikkanal C18), and the telegram drops its wire detail (apci, payload, dest_type, the Data Secure sequence and raw ASDU); technical: true returns the raw shape.
knx_get_device address, technical (optional) One device's identity, product, location, channels, parameters, com-object table, and links: the configured state. parameters holds the values under the keys the device file uses; the ETS-internal ones the user cannot set (hidden@<ref>, label@<ref>) are left out and counted in hidden_parameters, and technical: true includes them. computed_parameters lists each parameter a <ParameterCalculation> computes under the configuration (key, value: what a download writes, computed_by: the calculation's id); it is absent while every input of every calculation holds its default, as then none runs. For what the device can do (inactive channels and pages, functions, choices) use knx_show_device.
knx_show_device address, channel (optional; a handle, a page handle, or device), toml (optional), inactive (optional), live (optional), technical (optional) What bussard device shows, as JSON: what the device can do. Without technical the ETS ids (a parameter's or enable step's reference where a key names it, a page's id and includes, application, computed_by) and each object's flags are left out; key, number, dpt and handle stay, since the next call needs them. The channels; for an application without channels of its own the ETS pages (blocks), for one with channels the inactive_channels, each inactive one with inactive (enable, would_show, needs; a channel of a module instance the configuration does not reach is listed too, and its objects, whose numbers the product model does not give, count in module_objects); an enable step never names an internal (Access="None") parameter: it names the parameter the user sets that changes it, or says enabled by ETS only with ets_only: true; a summary of what is inactive; and for channel its parameters (also the ones at their vendor default, at_default: true; a parameter a <ParameterCalculation> computes carries the computed value, which a download writes, in computed and the calculation's id in computed_by) and objects, or for an inactive page the ones it would show; with toml: true also the paste-ready snippet; how_to_change says which tool edits and pushes what. Unscoped, an inactive page whose enable chain repeats an earlier page's keeps only its own steps and names the earlier pages in also_needs (Theben's C10 behind C5 .. C9). With channel the response stays small: the pages and inactive channels come as block_summary and inactive_channel_summary, one line each (handle, text, state, parameter and object counts), the scope keeps its full inactive detail, inactive: true adds the other inactive pages in full as inactive_pages, and how_to_change is left out (the tool description carries it). For a KNX IP interface, knxnet holds the device file's [knxnet] table (model), what the device last reported (device, from the device facts status <ADDRESS> and describe keep), where they differ (drift) and how_to_change; knx_set_parameter does not edit it. Files only, unless live: true: then it also reads the device over the bus as bussard status <ADDRESS> does, with the same functions, and adds live: sentences (names first), mask, system_type, identity against bussard.lock, and for a KNX IP interface knxnet (address in use and how it was assigned, MAC, friendly name, tunnelling addresses, state), knxnet_lines, model_knxnet and knxnet_drift; security on a Data Secure device read with its tool key. A device that is not in the project answers with live and the reason in model_view. The live read is read-only and refused in --passive mode (live.ok: false).
knx_recent_telegrams limit (default 50, max 1000), ga (GA or prefix), source (IA), since (RFC3339), all optional Recent decoded telegrams, oldest first. With --capture-db, windows that predate the in-memory ring are topped up from the capture database.
knx_wait_for_telegram timeout_seconds (max 300), ga, source (optional) Blocks until a matching telegram arrives or the timeout elapses. A timeout is a normal result, not an error. Enables "press the button now" debugging. With the server's keys a secured group telegram arrives decrypted, with secured: true; without its group key it keeps the ciphertext and says secure_status: "no_key".
knx_validate severity (optional: error, warning (default) or info), address (optional: 1.1.4, or 1.1. for a line), group (optional: 3/2/0, or 3/ for a range) The diagnostics (code, severity, message, location, and the device and parameter a finding names) at or above severity, about the device or group when given (matched on the location, else the message). The rules are those of bussard validate, one function for both: parameter values against the product data (E016, E017, W050) and the key rules (E027 to I031) against the server's key store or keyring included. checked lists the rule families that ran (project, files, parameters, lint, keys), not_checked any that did not. counts always counts every error, warning and info in the project, shown how many are returned, and note what the filter left out.
knx_audit live (default false), window_seconds (default 30, max 3600) The bussard audit --json object. The server's --keyring (password in BUSSARD_KEYRING_PASSWORD of the server's environment) fills the static keyring check. With live: true it adds the gateway description with tunnel slots, a traffic sample taken from the server's telegram buffer, and live.secure: the project's Data Secure devices probed as bussard audit --live probes them, with the same fields. live.scan is null; knx_find_devices scans a line. live: true is refused in --passive mode; the static audit is always available.
knx_scaffold_groups plan (JSON {rooms: [{floor, room, functions}]}), scheme (optional) Writes groups.toml from a room and function list, returns the addresses added and the project's validation counts. Confirm the room list with the human first.
knx_reserve_groups room ("<Floor> <Room>"), functions The same for one room, as bussard groups reserve does it, under the project's scheme.
knx_read_group ga Transmits a GroupValueRead and returns the decoded response, the object bussard read --json prints: ok, ga, name, answered, value, typed, dpt, raw, source, secured, admission, or reason (with timeout_seconds, refused, hint, note where they apply). Omitted in --passive mode.
knx_describe_device address Introspects a device: enumerates its interface objects and each property's description (PID, type, element count, access levels), as the object bussard describe --json prints (ok, address, objects, secure, reason; the chat walk reads no descriptor, so mask is absent). Read-only on the bus. With --keyring, a KNX Data Secure device is addressed with its tool key, and the result adds security_diagnostics: the security failures log (PID 55: sequence, cryptographic and access error counts, the latest failure), the security report (PID 57) and its broadcast setting (PID 58). A device without a tool key that refuses the plain walk and answers a secured read under its factory key from the key store is reported as bussard describe reports it: ok: false, factory_key: true and the reason. The server keeps the connection for 3 s after a call, so a following call to the same device reuses it: no second T_Connect, S-A_Sync, authorize or max-APDU read. A call to another device, a programming-tier call, a lost gateway link or the idle window closes it first; a call that fails on the kept connection is repeated on a fresh one. Omitted in --passive mode.
knx_backup_device address, or all: true Backs one device or every device in the project up, as bussard backup does, by calling the same service function: the link tables and, on System B, the parameter memory the device bounds itself, one JSON file per device plus manifest.json under captures/backups/<timestamp>/. Returns ok (false only when a device answered and its read failed), out_dir, backup (the directory name knx_restore_tables takes), manifest, gateway, devices (per device address, status (backed_up, skipped, unreachable, failed), mask, system_type, application, order_number, read_time, file, parameters (captured, base, length, or the reason), detail, identity), totals and next_step. Read-only on the bus. Omitted in --passive mode.
knx_reconstruct_device address, or line with out, from and to (optional) Reads one device's tables back and compares them with its device file, as bussard reconstruct does, with the same report builder: mask, system_type, table_source, addresses, associations, objects (com-object to group addresses), notes, identity, parameters (the read-back, when bussard.lock pins the product data) or parameters_note, secured, diff (the raw table comparison: matches and note), and differences in the shape of knx_diff_project: from, to, count, summary, touches_protected, sentences, changes (each kind on_device_not_in_model or in_model_not_on_device, object, ga, ga_name, protected, sentence); the tables do not record send or listen, so pairs are compared per object. The result is bussard reconstruct <ADDRESS> --json plus summary and next_step. Read-only on the bus. With line (e.g. 1.1) instead of address, it sweeps the line from device from to to (default 0 to 255) and synthesizes a fresh project from the tables, as bussard reconstruct --line does with the same service functions: placeholder group names, no DPTs, every group address as listen, a banner atop every file. The project goes to out, a fresh (absent or empty) directory relative to the project folder, default captures/reconstructed/line-<line>-<unix time>; an absolute path, .. or a non-empty directory is refused, and the project the server serves is never changed. The sweep runs as a read job (about 3 s per address): past the 20 s read wait the call answers started: true with the job for knx_job_status. The result is the CLI's --json summary: line, out, devices_found, devices_read, devices_skipped, group_addresses, links and device_details. Omitted in --passive mode.
knx_find_devices line ("1.1"), from and to (optional, default 0 and 255) Scans one line as bussard scan does, with the same sweep and probe: each address one at a time, mask, manufacturer, order number and serial of every responder, over KNX Data Secure when the server's --keyring holds the device's tool key. Runs as a job: a scan that ends within the read wait returns its result, a longer one started: true and job, which knx_job_status reads; its progress counts probed, found and total. The result: summary (one sentence, names first), devices (name, address, known, mask, system_type, manufacturer, manufacturer_id, order_number, serial, secure and secure_note on a Data Secure device, identity), line, from, to, model_device_count, not_in_model, missing_from_bus (the project's devices in the scanned range that did not answer) and timing: bussard scan --json plus summary and next_step. One bus job at a time: refused while a plan or apply runs. Read-only on the bus. Omitted in --passive mode.
knx_infer_group ga, payload_hex (optional) What the traffic on a GA says it is: ranked DPT candidates (dpt, confidence of low/medium/high, reason), the sender (address, name, location), its channel and com object (index, name, declared DPT, flags), the GA's current entry in the project, a proposed name, and a next_step telling the assistant to confirm with the human before calling knx_set_group and knx_add_link. Uses every telegram seen on the GA, or payload_hex when given. A secured telegram counts only when the server's keys decrypted it (secured: true); undecrypted_secured counts the ones left out and secure_note says why. Reads only; also registered in --passive.
knx_write_group ga, value (human-typed), dpt (optional override) A GroupValueWrite. Registered only with --allow-writes; refuses protected GAs outright, and refuses a dpt that contradicts the GA's DPT in the project (the override is for GAs the project does not type). On a secured GA it checks sender admission as bussard write does: without evidence it reads the devices' security individual address table (PID 54) once per server lifetime, records it in bussard.lock, and refuses when the table does not list the tunnel address. The result is the object bussard write --json prints (ok, ga, name, value, dpt, payload, secured, sent, confirmed, result, admission, note, or refused and reason).
knx_run_tests only (list of test names, optional) Runs tests.toml and returns the same report as bussard test --json, plus refused_protected. Registered only with --allow-writes. A test that writes a protected GA is refused whatever the file says; manual tests are skipped.
knx_describe_change from, to (snapshot ids, optional) The change as plain sentences. With no arguments: the pending changes, i.e. the working files against the last snapshot. Files only.
knx_history limit (default 50, max 500) The history snapshots with id, time, command, gateway and a one-line summary each.
knx_set_group ga, name, dpt, description, secure (all but ga optional) Creates or updates a group address. Creating one needs name. Refuses to rename or retype a protected = true GA; there is no parameter that sets or clears protected. secure switches KNX Data Secure as bussard groups secure does: the key store, the group's flag and every linked com-object's flag in one change, refused for a protected GA and when the server reads a keyring other than the key store. The result adds key_store (group_key: removed, not_present, generated or kept), security (the linked devices and objects) and a note naming the Secure devices to plan and apply and the bussard keys export Home Assistant needs. knx_undo restores the key store with the project (key_store in its result).
knx_remove_group ga Removes a group address from groups.toml. Refused while any com object sends or listens to it: the reason lists each link (1.1.5 object 3 listens) and names knx_remove_link as the step before. Refuses a protected GA. Records a group_removed change ("Group address 1/0/22 (Kitchen door light) removed.") behind a snapshot, so knx_undo puts it back. Files only.
knx_add_link address, com_object, ga, role (send|listen) Binds a com object to a GA. address is the device's address; no other name is accepted (a client bridge strips a key named device). A com object has at most one sending GA, so an existing one is replaced. Refuses protected GAs.
knx_remove_link address, com_object, ga, role Unbinds a com object from a GA. address is the device's address, as for knx_add_link. Refuses protected GAs.
knx_set_device address, name, floor, room (all but address optional) Renames a device or changes where it lives.
knx_set_parameter address, parameter, value, channel (optional), force (optional) Sets one parameter in the device file. Parameter keys: the key knx_show_device lists (helligkeitsschwelle, page-qualified sollwerte.komfort, or key@reference), that key behind its page or channel handle (universalkanal-c4-funktion.helligkeitsschwelle), the bare reference (P-7305_R-7305), or the bare parameter id (P-7305) or vendor text, which name the ref the configuration shows; channel takes a channel handle, device or a page handle when the key repeats. An unknown key is refused with the three closest keys on the device (prefix match first, then edit distance over key and vendor text) and the page or channel each sits on. value is an enum label or code, a number or text, checked against the product model and stored as the device file stores it (a label becomes its code). Refuses a key neither the file nor the lock knows, and a device without a product model to check against. Refuses an output of a <ParameterCalculation>, also with force, naming the calculation and the input keys to set instead: ETS shows an output read-only and a download writes what the calculation computes, and a script cannot be run backwards to find the inputs for a wanted output. Setting an input lists each output whose computed value changes, marked "Computed by calculation PC-1.". A parameter at its vendor default is set the same way. A ref the configuration does not show under the device's current values (its page is inactive, or it belongs to another branch of a choice) is refused: the device image holds one slot per shown ref, so the value would be stored and never written. The refusal names the condition in words, the current values it tests, and the ref of the same parameter that is shown. force: true stores the value anyway, to prepare a branch before switching to it; knx_show_device then marks the row ignored with the reason, and knx_plan_device, bussard plan, bussard apply and bussard flash list it as "key = value ignored: not shown under the current values (needs ...)". A value a Dynamic <Assign> replaces under the current values is marked and listed the same way, as "key = value replaced by ...: an <Assign> copies ... while ..." (bussard validate warns W050). When bussard.lock pins the device's product archive, the device's channels, objects and parameter index are re-derived under the new value, so knx_show_device lists what it reveals right away; when the value shows, hides or resizes com-objects the result's note names them, since only a full download writes the new group-object table (knx_plan_device plans it as method: flash, or bussard flash <ia> at the CLI).
knx_set_interface address, assignment, ip_address, netmask, default_gateway, friendly_name, tunnels, add_tunnels, remove_tunnels (all but address optional) Edits the [knxnet] table of a KNX IP interface: assignment dhcp (drops the static settings) or static, the static settings, the friendly name ("" removes it from the table), the tunnel list (tunnels replaces it, add_tunnels and remove_tunnels change it). The device needs a [knxnet] table already. The table is checked before it is saved: E043 to E046 refuse the edit, W047 against the server's key store or keyring comes back as the note. Files only; knx_plan_device and knx_apply_device write it to the interface's KNXnet/IP parameter object as bussard plan / apply do (above), and refuse a change of the IP assignment, address or tunnel addresses of the interface the server tunnels through (bussard apply <ia> --allow-self-reconfigure at the CLI).
knx_undo snapshot_id (optional) Restores the project files to a snapshot (default: the newest one that differs from the working files, i.e. undo the last change). Files only.
knx_discard_edits address or group (exactly one) Drops this session's unapplied edits of one subject and leaves every other edit alone. With address, the device's file goes back to the snapshot before its first pending edit (the edits knx_plan_device lists in pending_model_changes); with group, the group address's groups.toml entry goes back to the snapshot before its first edit this session. Returns dropped (the sentences of the dropped edits), changes, snapshot, validation and next_step. A group address the session created that a dropped link used stays, and note says so; discarding such a group while a link still uses it is refused with the links. Snapshots first, so knx_undo brings the edits back as pending edits. Refused when the subject has no pending edits. A group address whose Data Secure state the discard flips gets its group key back in the key store, or loses it, as knx_undo does; the result carries key_store. Files only.
knx_import_file path or order_number; download, password, theirs (optional) Imports by file type, as the CLI does: a .knxproj or .bussard bundle into the project (bussard import: a re-import keeps hand-edited fields and lists each one that differs; theirs: true takes the incoming values), a .knxprod into the product store (bussard import-product), a .knxkeys into the key store bussard.keys (bussard keys import). order_number fetches vendor product data from the product index. Downloading vendor data needs download: true, the human's consent (never yes); without it nothing is downloaded and the result says what would be. password is the project password of a protected .knxproj or the keyring password of a .knxkeys (else BUSSARD_PROJECT_PASSWORD or BUSSARD_KEYRING_PASSWORD from the server's environment); it is never echoed, and no result carries key material. A protected .knxproj without a password gets the password form of knx_setup when the client supports URL-mode elicitation. Returns summary (one sentence), sentences (what the CLI prints) and per kind written, merged, conflicts, kept, models or the keyring report (addresses and counts). Snapshots first. Withheld by --no-model-edits.
knx_export what (bundle, groups, keyring or doc); out (optional for bundle), format, include_history, password, force Writes, as the CLI does: bundle the project and its history as one .bussard file (bussard export; default next to the project folder), groups the group-address plan for ETS (bussard export-groups; format ets-csv (default) or ets-xml), keyring the key store as a signed .knxkeys, read back and checked (bussard keys export; the keyring password or BUSSARD_KEYRING_PASSWORD; force: true overwrites), doc the handover documentation folder as Markdown (bussard doc). Returns path, summary (one sentence) and the details of the form; never key material. Available in every tier.
knx_export_bundle path, include_history (default true), both optional The bundle form of knx_export under its earlier name: writes the project and its history as one .bussard file (default: next to the project folder) and returns the path, summary and manifest. Available in every tier.
knx_diff_project path (a .knxproj or .bussard) What that file would change compared with the working project: {count, summary, touches_protected, sentences, changes, source}. The assistant quotes the sentences before the human imports. A password-protected .knxproj needs BUSSARD_PROJECT_PASSWORD in the server's environment. Read-only; available in every tier.
knx_job_status job One job of the server, of any tier: job, kind, state (running, done, or interrupted when the server stopped mid-job), done, step, question (what the human must do or answer before the job goes on, such as pressing a device's programming button; null when none), progress and, once done, result, exactly what the starting tool returns inline, plus next_step. Registered in every tier; reads the job table and the job records under .bussard/history/, never the bus.
knx_viz none Starts the page bussard viz serves inside the server and returns url, read_only and live_traffic. The page reads the server's own project and its one bus connection, so it opens no second tunnel; without a bus it shows the project only. It is read-only: a group write answers 403, and it answers only to loopback names and IP addresses in the Host header. It binds a free loopback port, or the address of bussard mcp --viz-listen. A second call returns the same url; the page stops with the server. Registered in every tier.
knx_enroll_certificates local (optional, default false) Starts a certificate enrolment session and opens the pairing page in the human's browser (through URL elicitation when the client declares it), then keeps the call open until the session ends and returns its summary: the fields of knx_enroll_status for an ended session plus pairing_page_opened and serials (each certificate's serial number and state in one line); warnings when the page or relay is not the default, note when the server reads another keyring than the key store. While it waits it sends a progress notification on every change and every minute (counts only) when the client sent a progress token. Without one it stops waiting after 4 minutes, and a cancelled call stops at once; the session keeps running either way, and the result then has session: running, data_path (how the certificates travel, in plain words) and read_more (the docs link). Never returns the link, the session code or the pairing page's address. When the human declines the elicitation, declined and the session is closed. Refuses when no browser can be shown (an SSH session, no display) or the browser does not open (pointing at bussard keys enroll), while a session runs, without BUSSARD_KEYRING_PASSWORD, when the key store does not load or cannot be written. Never touches the bus.
knx_enroll_status wait_seconds (optional, at most 120), until_end (optional), stop (optional), details (optional) The session's session (running, ended, none), end (phone_done, stopped, expired, error), error, local, phones, certificates, stored, ignored, expires_in_seconds, tally (stored, waiting, already_known, conflicts, invalid, errors), summary, next_steps (once ended: the CLI commands that apply, each with command and why), next_step, and results: one entry per certificate with serial, address, name, status (as keys enroll reports it) and message. wait_seconds waits for the next certificate or the end; until_end: true waits for the end, as long as the client allows (with progress notifications as above; wait_seconds caps it); stop: true ends the session first.
knx_plan_device address or line Reads the device's live tables and, with the product data bussard.lock pins for it, its parameter memory (read-only on the bus), and returns the plan bussard plan --json has: sentences (the text rendering in the device file's words, one line per changed link and per changed parameter), changes, unchanged_objects, unchanged_parameters, writes (with parameter_octets), parameter_plan (changed: each differing parameter as key, name (the vendor text), device and model; octets; octet_ranges: every run of written octets as {segment, offset, length, parameters, sentence}, parameters naming each parameter whose bits in the run differ as key, name and role, plus device and model: the values the device's octets and the project's image hold there, as the enumeration member's text where the value is one, else the number (see Octet attribution roles), empty where device memory differs from the project's image outside any parameter of the application; a run holding an internal ETS selector that differs carries an explanation (a plan that writes octets no changed parameter accounts for lists those runs in notes, so sentences say why); written; skipped: why the parameters are left out, with the recovery line), notes, identity (the verdict against the lock, an object with verdict), question, state_hash, parameters (the parameter read-back, as bussard plan --json has it), plus table_plan (the table-level detail: additions, removals, unchanged count, table sizes, load operations), pending_model_changes (what the project files changed on this device since this server session last saw it hold them, read from the history: the sentences that reach the device, links and parameters, as a list of strings; a successful knx_apply_device, a plan with nothing to write, a knx_undo or a knx_discard_edits that puts the device's files back clear them; [] on a fresh session), the same lists as JSON, backup_dir, plan_digest, planned_at and expires_at. A plan with nothing to do has no digest. Refuses a change that touches a protected GA. method says how the change is written: apply (the tables and the differing parameter octets) or flash, when a parameter shows or hides a com-object and only a full application download writes the new group-object table, or when the device does not run the application bussard.lock pins and it must be loaded (see Loading the application); a device whose application drifted is refused, naming bussard flash, only when no archive is pinned to load. A flash plan carries flash: why, objects (shown and hidden, each with number, text, dpt and because, the parameter changes behind it), tables (address, association and group_objects, each before and after), device_offline_seconds (min 30, max 50: the device restarts), parameter_backup (taken first, in captures/backups/parameters/), product (archive, product_sha256 from the lock, application), factory_reset and differential (whether the group-object table is kept when its MCB matches, as ETS keeps it); its question asks to flash the device. A flash plan is refused without an archive pinned in bussard.lock, and for a device carrying another application or one whose load state cannot be read. Without the product data the plan writes the links only and says why. With the server's keys, a Data Secure device they list is read over KNX Data Secure (secured: true), and security_object says what its security object receives with the write: summary (the line bussard apply --keyring prints), secure_senders, keyed_groups and secured_objects, never a key. A group the project marks secure without a key in the key store or keyring refuses the plan. When the device read does not end within the read wait (20 s from the start of the call; a Data Secure System B device reads its whole parameter memory), the call answers started: true, done: false, kind: plan, job, address and next_step instead; knx_apply_status with that job returns the plan as result once done, exactly as the inline answer, plan_digest included. A second call for the same device while its plan job runs returns the same job; a plan is refused while an apply runs, and an apply while a plan runs. With line (e.g. 1.1) instead of address, it plans every device the project has on the line as bussard plan --line does, through the same service function: the link tables only (no parameters), an unlinked device or an unsupported mask skipped, a device that cannot be read reported with the reason. The result carries line, gateway, devices (each address, name, mask, system_type, status (changes, unchanged, skipped or failed), changes, detail, verified, sentences, notes and backup), the counts total, changed, unchanged, skipped and failed (the object bussard plan --line --json prints), sentences, question, noop, and one plan_digest over the line with planned_at and expires_at. The digest binds the project's devices and links on the line, its protected group addresses and every device's tables as read. A protected group address in any device's change refuses the line plan. It runs as a plan job like the device form. Registered only with --allow-programming.
knx_ha_status none Home Assistant over its REST API, read-only: reachable, authorized, version, knx_loaded, knx_entries (the KNX config entries), entity_counts per KNX-capable domain, total_entities, errors; and the KNX YAML file: config_path, file (state yaml with its layout, or not_yaml with the reason), managed, generated_entities, file_entities, running (how many generated entities Home Assistant runs, by platform and name). Registered only with the Home Assistant tier.
knx_ha_plan none What writing the KNX YAML generated from the project (with ha.toml) to config_path would change: sentences (one per entity added, changed or removed), changes, counts, file, layout, noop, question, plan_digest, backup_dir, home_assistant (reachability and the generated entities it does not run yet), automations (the bussard_ automations Home Assistant runs: id, alias, state, managed and problems, e.g. a group address groups.toml no longer lists) and plan_ttl_minutes. No digest when nothing changes or the file is not YAML-managed. Writes nothing. Home Assistant tier.
knx_ha_apply plan_digest Backs the file up, replaces it atomically, calls the knx.reload service and reads the status again. Returns written, backup, reload (ok, or the error), status_after, sentences and a message. Refused unless the digest is fresh and a new plan reproduces it, the file is YAML-managed and Home Assistant is reachable with the token. Home Assistant tier.
knx_ha_automation_plan id (bussard_…), when ({ga, value?, dpt?}), then ([{send: {ga, value, dpt?}}]), alias, description (optional) The rule checked against groups.toml and rendered (see bussard-managed automations): sentence (when Zu Hause receives 1, send 0 to Gastmodus, by group-address name; an unnamed address reads as the address, a shared name gets it in parentheses; the automation's default alias), sentences, op (create, update or unchanged), automation (the JSON written) and yaml, previous (what Home Assistant stores under the id now), question, plan_digest, backup_dir. Writes nothing. Home Assistant tier.
knx_ha_automation_apply plan_digest Writes the planned automation through the config API and calls automation.reload. Returns op, written, backup (the previous JSON, for an update), reload and a message. Refused unless the digest is fresh and a new plan reproduces it. Home Assistant tier.
knx_ha_automation_remove id, plan_digest (optional) Without plan_digest: the removal plan (sentences, previous, question, plan_digest), nothing changes. With it: backs the JSON up, deletes the automation and reloads automations. Only a bussard-managed automation. Home Assistant tier.
knx_apply_device address or line, plan_digest, plan_hash (optional, address only), allow_unsupported (optional) Writes the planned change as a job: the pre-flight runs in the call (the gates, the digest check against a fresh read, the identity verdict, the history snapshot and the backups), then the write runs in the server. When it ends within the reply wait (20 s from the start of the call) the call returns the full result with started: false, done: true, job and record; otherwise it returns started: true, done: false, job, address, step, the backup paths and next_step, with no ok yet. One apply per server at a time: a second call while a job runs is refused naming the running job, and so is knx_plan_device. The write itself: the backups first (tables, and parameter memory when parameters change), then the bussard apply write (the tables when a link changes, then the differing parameter octets), each verified by reading back. The result carries ok, verified, the final load states, parameters (written, verified, octets, changed, or reason), backup, parameter_backup, gateway, the history snapshot and declared. Before the write, a group address the device files link but groups.toml does not define is added there, named after the object that uses it, as bussard apply does; declared holds one sentence per addition (absent for none) and the snapshot's result names them. A server started with --no-model-edits declares nothing. Refused unless the digest is fresh and a new read still reproduces it (see below), and when plan_hash is given and a fresh read no longer hashes to it. A device the server's key store (or keyring) lists is written over KNX Data Secure, and on System B its security object is reprogrammed with the tables (security individual address table, group key table, group-object flags), exactly as bussard apply --keyring does; the result carries secured and security_object. A plan with method: flash runs as the same job and takes the same arguments: the parameter memory is backed up, then the image bussard flash <ia> --yes writes is downloaded (built by the same code from the same inputs), the device restarts and the load is verified after the restart; the result carries method, load_state, application, warnings, parameters, readback and, for a secured device, secure_senders_recorded (the PID 54 table recorded in the lock, as flash does); a plan that loads the application adds load_application (why, application, loaded). The download, the read-back and the lock update are the functions bussard flash runs; ok is true only when the read-back matches the project. With line and the digest of a line plan, it writes the line as bussard apply --line does, through the same service function, as one job: the pre-flight refuses a digest that is not a fresh line plan of this session, a project whose devices, links or protected group addresses on the line changed since the plan, and a project with validation errors (after declaring the group addresses the device files use, as the device form and apply --line do; listed in declared), and records one history snapshot mcp knx_apply_device --line <line> <digest>. Then each device with changes is read again, backed up, written and verified by an independent read-back, in address order; a device whose fresh read no longer matches its plan is failed without a write, and a device that fails does not stop the run. The result lists per device status (applied, unchanged, skipped, failed), verified, changes, sentences, backup and detail, plus the counts (total, changed, unchanged, skipped, failed, as bussard apply --line --json), snapshot and declared; ok and verified are true only when no device failed. Parameters are not written in the line form. Registered only with --allow-programming.
knx_add_device address, order_number, product (all optional, first call); job, plan_digest, yes, download (the write call) Adds a new device as bussard adopt does, with the same service functions, in three steps. product is a path to the device's vendor .knxprod, as adopt --product: the first call imports it into the product store (the import knx_import_file runs, behind a history snapshot; the result lists it under product_import) and the device gets that product data whatever order number it reports, so no download is asked. The first call answers at once with step: press_button, job and question (press the programming button); the job waits up to 30 s for the programming-mode answer. knx_job_status then reports step: identified: current_address, address (the target: the argument, else the next free one on the project's busiest line; a device the key store lists keeps its address), serial, mask, manufacturer, order_number, product_data (in the store, what would be downloaded from the vendor index, or none), download_needed, sentences, plan_digest and question; nothing is written and the job holds no bus slot while it waits. The write call takes job, plan_digest and yes: true after the human's yes, and download: true when download_needed (the separate consent of --yes-download; yes never answers it). It re-reads the device and refuses when the digest no longer matches (another device in programming mode, another serial, a changed project or product), downloads, refuses an address another device answers at, writes the address, reads the device back at the new address and writes devices/<address>.toml with its bussard.lock entry (the serial included). The result carries step: done, name, address, from, assigned, verified (the read-back matches the identified serial and mask), readback (as bussard assign --json has it), device_file, product, objects (the com objects to wire, transmit-capable first), secure (for a device adopted over A_SecureData: links, parameters, secure objects and groups), notes, summary and next_step. Securing a factory-fresh device stays with ETS. Registered only with --allow-programming.
knx_replace_device address (first call); job, plan_digest, yes, download, allow_unsupported (the write call) Replaces a dead device with the same product as bussard replace does, on the same step machine, as one job. The first call needs a device file for address, refuses a device the project records as secured (securing the replacement stays with ETS) and one without product data to flash (unless the vendor index has the archive the lock pins), records a history snapshot (backup: the device file and its bussard.lock record, with what they hold) and answers at once with step: press_button, job and question. The job checks that nothing answers at address (a device that does is refused; bussard replace --force is the terminal's override), then waits up to 30 s for the replacement in programming mode. knx_job_status then reports step: identified: current_address, serial, mask, order_number, resident_application, identity against the lock, application, product_data, download_needed, sentences, plan_digest and question; another order number or mask than the device file names is refused, nothing is written and the job holds no bus slot while it waits. The write call takes job, plan_digest and yes: true after the human's one yes, and download: true when download_needed. It re-reads the device and refuses when the digest no longer matches, downloads, writes the address and reads it back (the identified serial and mask), then runs knx_plan_device's plan and knx_apply_device's pre-flight and write on the device as the same job: the pinned application loaded when the replacement does not run it, the backups, the parameters and links, the independent read-back. Only a verified write is recorded: replaced in the device file and the new serial in bussard.lock. The result carries step: done, ok, verified, name, address, from, assigned, flashed, readback (as bussard assign --json has it), write (the apply result), recorded (absent when the record failed), notes, summary and next_step; when the address took but the write did not verify, ok: false with reason and recovery. Registered only with --allow-programming.
knx_commission_line line (the plan); line, plan_digest, yes (the run); job, answer (the human's word) Commissions a line as bussard commission --line does without --flash and --apply, with the same service functions. line alone reads the project only and returns step: plan, devices (address, name, floor, room, order number), total, sentences, summary, question and plan_digest. With plan_digest and yes: true after the human's yes it starts a job (started: true, job): the job probes which of the project's addresses already answer (a device that reports the project's order number there is present, another one is refused), takes a history snapshot, then repeats per device press_button (question names the device by name, room and order number; the job waits up to 30 s), identified (serial, mask, manufacturer and order number read at the current address, order_check against the project) and assigned (the address written, read back at the new address with the programming-mode clear, the serial and mask compared with the identification). progress.device is the device it is on and progress.devices the reports so far, each with status (commissioned, present, failed), identified, readback and label. That one yes covers every device whose order number matches the project, as the CLI's one confirmation covers its run. A different product, an unreadable order number, no device, several devices, or a device the project has no order number for pauses the job with waiting (device, reason, identified, answers) and question; nothing is written and the job holds no bus slot while it waits. job with answer goes on: retry, skip (the device is reported failed), stop, or assign for a device the project has no order number for. stop also ends a running job, at once while it waits for a button, else after the device it is on. The result is the object bussard commission --json prints plus summary and next_step: ok, stopped, reason, devices (each with identified, from and readback once its address was written), labels (the label lines bussard commission prints), total, commissioned, present, failed and not_reached. Only addresses are written. Registered only with --allow-programming.
knx_apply_status job One job of the programming tier, an apply or a plan job of knx_plan_device: job, kind (apply or plan), address, state (running, done, or interrupted when read from a record a stopped server left running), done, started_at, finished_at, elapsed_s, step (what it is doing now), progress (tables, download_step, segment {position, total} (how far the current segment walk got), octets {written, writable} (what the last System 7 segment stream wrote, of the octets its write mask allows), download), the pre-flight's gateway, backup, parameter_backup and snapshot, result (the final result knx_apply_device returns inline, for a plan job the plan knx_plan_device returns inline, for a pre-flight that refused after the call answered refused: true with the reason; null while running), record and next_step. A job this session does not hold is read from its record (from_record: true). Never touches the bus. Registered only with --allow-programming.
knx_last_apply address The latest apply job for the device, in the shape of knx_apply_status plus found: this session's, else the newest record under .bussard/history/. Recovers a result whose reply was lost to a client timeout or a server restart. found: false when none is recorded. Never touches the bus. Registered only with --allow-programming.
knx_clear_security_log address, plan_digest (optional) Clears a Data Secure device's security failures log (PID 55) and resets its security report, as bussard secure diag --clear does after its confirmation, in two calls. Without plan_digest: reads the log with the device's tool key from the server's key store or keyring and returns diagnostics, lines, the CLI's question and a plan_digest. With the digest, after the human's explicit yes: reads again, refuses if the log moved, clears and reads back; cleared: true means every counter read zero and the report clear. Refused without a tool key for the device. Registered only with --allow-programming.
knx_interface_secure address, state (on or off), plan_digest (optional) Switches KNXnet/IP Secure of a KNX IP interface as bussard interface secure does, in two calls. Without plan_digest: steps, generated (the credentials the key store would gain, names only), question, plan_digest. With the digest, after the human's explicit yes: saves generated credentials to the key store, switches, waits out the restart and reads back; the result carries ok, verified, steps, security_mode, tunnel_users, gateway_secure_only, mismatches and key_store_updated, or error and recovery. Refused without a key store, for a device that is not an IP interface in the project, when the interface already runs secure-only tunnelling (on), and when the server's own session is a KNXnet/IP Secure session with that interface. Registered only with --allow-programming.
knx_restart_device address, plan_digest (optional) Restarts the device as bussard restart does, with the same service function, in two calls. Without plan_digest: sends nothing and returns form (confirmed, the master reset a System B application that supports Secure answers, or basic), form_reason, question and plan_digest. With the digest, after the human's explicit yes: restarts as a job in the shape of knx_apply_device (knx_apply_status reports it) and waits until the device answers again. The result is the object bussard restart --json prints plus the envelope: method (restart), address, gateway, secured, form, form_reason, ok, verified, confirmed (the device answered the restart with error code 0; never for the basic form), process_time_s, mask and answered_after_ms, or ok: false with the reason. A digest is single use and is refused when the restart form changed since the question. Registered only with --allow-programming.
knx_restore_tables address, backup (optional), plan_digest (optional), allow_unsupported (optional) Writes a backup's link tables back onto the device, as bussard restore <backup> <address> does, in two calls. backup is the backup name knx_backup_device returned or a file under captures/backups/; omitted, the newest pre-write backup an apply kept of the device. Without plan_digest: reads the device and returns the plan, nothing written: table_plan, additions, removals, unchanged (the links that stay), the table sizes, security_object, notes, question, plan_digest, identity, noop. With the digest, after the human's explicit yes: re-reads the device and refuses if the device or the backup moved, records a history snapshot mcp knx_restore_tables, backs up the current tables, then runs the table write and the independent read-back of knx_apply_device, as a job (knx_apply_status, knx_last_apply). verified is true only when the read-back matches the backup. Parameters are never written. Refused for a backup of another device or mask, a backup outside captures/backups/, and a change that touches a protected group address. Registered only with --allow-programming.
knx_restore_parameters address, backup, plan_digest (optional), allow_unsupported (optional) Replays a parameter backup from captures/backups/parameters/ (backup is its file name there) onto the device, the restore --parameters engine, in two calls. Without plan_digest: reads the device and returns the restore plan, nothing written: sentences, octets, octet_ranges (each run with its parameters, their roles, the device value and the backup's value in model, and written: false for an octet the restore leaves as the device holds it, because no parameter is placed there under the project's configuration or the application owns the value), notes, question, plan_digest, identity. With the plan's digest, after the human's explicit yes: re-reads the device and refuses if the device, the backup or the project moved, records a history snapshot, backs up the current parameter memory, writes and verifies, as a job in the shape of knx_apply_device (knx_apply_status reports it). Refused for a backup of another device, application or mask, a backup outside the backup directory, a device whose application drifted from bussard.lock, and a device that does not run the application. A digest is single use. Registered only with --allow-programming.

The bus connection

The server keeps one bus connection for its whole life and reconnects it on its own. A lost tunnel first re-establishes itself within BUSSARD_TUNNEL_RECONNECT_SECS (see Environment). Then the connection is opened afresh, with a backoff of 1, 2, 4, 8, 16 and then 30 s between failed attempts. Every attempt is a new socket and a new KNXnet/IP Secure session; nothing of a failed attempt is reused.

While the bus is down, a bus tool is refused with the last error, for example:

the bus to 192.0.2.10:3671 is not connected: socket error (192.0.2.10:3671): Broken pipe (os error 32), waiting for SESSION_RESPONSE at <time> after 240 attempts; retrying in 30 s

A socket error names the handshake step it happened at. bus in knx_project_summary and knx_bus_status carries:

Field Meaning
state, connected connecting (never connected yet), connected or reconnecting (also after a fatal stop).
interface The gateway, as 192.0.2.10:3671 or multicast 224.0.23.12:3671.
tunnel_user The KNXnet/IP Secure tunnelling user of the current or last connection; null on a plain tunnel.
last_error, last_error_at The exact error of the last failed attempt or lost connection, and when (RFC3339). Kept as history after a reconnect.
attempts Failed connect attempts since the bus was last connected; 0 while connected.
retry_in_seconds Seconds until the next attempt, while waiting for one.
connected_since When the current connection came up.
stopped Only when the bus stopped for good on a connect error retrying cannot fix (a refused password, a secure-only interface without credentials), before it ever connected. Restart the server after fixing the cause. Once the bus has connected, the same errors are retried.

Tunnelling user choice. With a key store that lists several tunnelling users for the interface, the tunnel takes, in order:

  1. a user no other bussard process on this host holds,
  2. a user whose tunnel slot the interface reports free,
  3. the key store's order.

The user a tunnel holds is marked by a lock file <dir>/.bussard/tunnel-users/<ip>-<port>-user<N>.lock holding the process id; a lock whose process is gone is ignored and replaced. A user the interface refuses (a failed authentication, no free tunnel for it, or the connection closed or reset during the handshake) hands over to the next user in the same attempt, before the bus backs off. A timeout does not, since the next user would fare no better. The user chosen is logged at info level, a refused one at warning level. With --secure-user the named user is used and marked, without rotation.

Two servers for one project. Claude Desktop starts two bussard mcp processes for one configured entry. Each marks itself in <dir>/.bussard/instances/ and logs a warning naming the other's process id at start; neither refuses to run. Each holds its own connection and, through the locks above, its own tunnelling user. knx_bus_status lists the other's process id in other_instances.

The programming tier

--allow-programming lets the assistant finish a change instead of ending with "now type bussard apply". It exposes the single-device write of bussard apply, the link tables and the parameter octets that differ, written by the same code the CLI runs. It is off by default and never available with --passive.

Warning

At this tier the assistant can write a device, after you say yes to its plan. Read the plan it shows you before you answer.

The gates, in front of every write:

  • Write gate. A non-loopback gateway needs BUSSARD_ALLOW_REAL_GATEWAY=1 or --allow-remote-gateway. The server refuses to start without it, and both tools check it again on every call.
  • Source-address probe. Both tools refuse when a device already answers at the tunnel's own address, as the CLI device commands do. The server probes once per tunnel: a passed probe holds until the bus reconnects (knx_bus_reconnect, or a tunnel that re-establishes itself), and an occupied address refuses every call.
  • Plan digest. knx_plan_device returns plan_digest, 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, what a secured write gives the security object (addresses, object numbers and sequence numbers, no key), and the live tables and parameter memory it read. knx_apply_device refuses unless the digest came from this server session within --plan-ttl-minutes (default 10) and a fresh read of the device, with the current project, reproduces it. A device changed by ETS or another tool, or an edited project, retires the digest. A digest is single use.
  • State hash. The plan also carries state_hash, the same hash bussard plan --json prints. knx_apply_device with plan_hash refuses when a fresh read no longer produces it. The digest stays required either way.
  • Human approval. The tool descriptions tell the assistant to show the plan to the human and to call knx_apply_device only after an explicit yes in the conversation. The digest makes this checkable: an apply can only write what a plan showed.
  • Protected group addresses. A plan whose additions or removals touch a protected = true group address is refused, with no override.
  • Identity. A device whose application or mask drifted from bussard.lock gets the pinned application loaded by the plan (see below). Without a pinned archive to load, it is refused, naming the bussard flash it needs, as bussard apply refuses it.

An apply then runs exactly the CLI rails:

  1. The pre-apply backups to captures/backups/: the tables, and the parameter memory when parameters change. No backup, no write.
  2. A history snapshot mcp knx_apply_device <address> <digest> that names the gateway: the audit line bussard history shows.
  3. The table write when a link changes, then the parameter-only download of the differing octets, each verified by reading back.

The result carries the verify outcome, what was written and the backup paths. One device per call.

Parameters. The plan reads the parameter memory on the same connection as the tables, with the product data bussard.lock pins, and lists every parameter that differs by key, vendor text, device value and project value, so the human approves them by name. The write uses the same write set as the CLI: only octets a parameter is placed in under the configuration, as ETS's download does. It refuses unless the device runs the application the product data describes. When the product data is missing (the lock pins an archive that is not in products/, or whose SHA-256 changed), parameters.skipped carries the recovery line, the plan says it writes the links only, and a links-only plan the human approved still applies.

Device-managed parameters. An Access="None" parameter the configuration reaches is owned by the application at runtime, for example a download flag. Its octets always differ from the project's image, so a plan whose only difference is such octets is noop and writes nothing. They are still written, at the project's value, alongside a table or parameter write, and listed in octet_ranges with the role device_managed (see octet attribution roles).

A parameter that shows or hides a com-object changes the group-object table, which a parameter download does not rewrite. The same knx_plan_device and knx_apply_device pair pushes it as a flash:

  • The plan says method: flash, lists the com-objects that appear or disappear, the table sizes, the parameter backup and the pinned archive (product_sha256), and states that the device restarts and is offline for 30 to 50 s.
  • Its question asks to flash the device, so the human's yes is a yes to the flash.
  • The flash is the one bussard flash <ia> --yes writes, built by the same code from the same inputs.
  • It is refused without an archive pinned in bussard.lock, for a device that carries another application or whose load state cannot be read, and on every gate above.
  • The parameter memory is backed up to captures/backups/parameters/ first, where knx_restore_parameters reads it.

Supported devices

bussard writes without a human's override only the application programs its device-support list rates proven or likely.

  • Visible before a write. knx_show_device, knx_find_devices (each responder the project has) and knx_plan_device carry support: status (supported or unsupported), category (proven, likely or unsupported), evidence or reason, note (not confirmed on a real device for likely), problem (a known problem with its issue) and cause (as the issue states it), application, application_id and name. A plan also says override_needed when the write would be refused on this gateway.
  • A likely device is written, and the human is told. Its plan's next_step says the device is not confirmed on a real device and that a backup comes first; no override is needed.
  • The plan still works. An unsupported device gets its plan and its plan_digest; next_step holds the sentence the assistant puts to the human: bussard has not checked this product against ETS (or the known problem with its cause), a backup comes first, and ETS is the safe way.
  • The write refuses by default. On a gateway that is not loopback, knx_apply_device, knx_restore_parameters, knx_restore_tables and the write call of knx_replace_device answer ok: false, refused: true, code: unsupported_device, support and override. Nothing is written and the digest stays valid.
  • The override is the human's. When the chat app can show the server's questions (form-mode elicitation), the server asks the human itself (<ia> runs ..., which is not on bussard's list of supported devices. ... Write anyway?, or for a listed known problem ..., which has a known problem (<problem>: <cause>). ...) and the assistant cannot answer for them; a likely device is never asked about: allow_unsupported does not count, a yes writes, and a no or a dismissed question refuses with nothing written and the digest kept. Otherwise, after the human's explicit yes, the assistant calls again with the same digest and allow_unsupported: true. Either way the override counts only with the digest of a plan that reported the device unsupported, the trust model of every other confirmed write. A line plan reports each unsupported device; without the override (or after the human's no to the server's question) the line write reports it with status refused, and the result is ok: false.
  • The result says so. A written result carries support: forced, supported, or unsupported on a loopback gateway, which never refuses.

knx_commission_line only assigns addresses and is not gated; the download that follows goes through knx_plan_device and knx_apply_device.

Loading the application

A device that does not run the application program bussard.lock pins (it runs another one, has none loaded, or holds the pinned one unloaded after an interrupted download) gets it from the same pair, as one job:

  • The plan says method: flash, its sentences start with ! <ia> must have its application program loaded: <why>, and flash.load_application carries why, application and replaces (what the device runs now).
  • Its question asks to load the application, so the human's yes is a yes to replacing what the device runs. The digest binds what the device reported; a device that changes between plan and apply retires it.
  • The apply backs up the tables, takes the history snapshot, runs the download bussard flash <ia> runs (a factory reset first where the product has one and the device runs another application), reads the device back on the download's last connection, compares it with the project and records the security tables in the lock. It is the same service function the CLI calls, so the offline oracle rows that cover bussard flash for a product cover this.
  • The parameter memory of another application cannot be read with the pinned product data, so it is not backed up (parameter_backup_note), as bussard flash takes none.
  • Refused when the device's state cannot be read, and when it runs an application bussard cannot identify (that stays bussard flash --force <ia> at the CLI).
  • A self-contained application's download writes no link table. When the links differ from the project (or a factory reset erases them), the plan's flash.links_after_download is true, its sentences and question say the links are written after the load, and the same job then writes them as bussard apply <ia> does, as bussard replace runs flash and then apply. Each step ends with its read-back; the result carries the table write in links, and ok is true only when that read-back matches the project. The same holds for a parameter change that needs a full download.

Secured devices. A device the server's key store (or keyring) lists is planned and written over KNX Data Secure, as bussard apply --keyring does. On System B the write also reprograms the security object. The gates above apply unchanged, and three more rules cover it:

  • The plan shows what the security object receives (security_object: the secured senders, the keyed group addresses, the secured objects), so the human approves it with the tables. It names addresses and object numbers, never a key.
  • A group the project marks secure = true without a group key in the key store or keyring refuses the plan: a download without that key would leave the group unusable.
  • The plan digest covers the security inputs. A key store or secure flag that changes between plan and apply retires the plan.

A device the project records as security.activated (secured) but the key store does not list is refused. System 7 devices get their tables written secured and their security object left as it is.

KNX IP interfaces. knx_plan_device and knx_apply_device write a [knxnet] table as bussard apply does (see KNX IP interfaces), and refuse outright a change of the IP assignment, address or tunnel addresses of the interface the server tunnels through.

What the human reads

Every result of knx_plan_device, knx_apply_device, knx_apply_status, knx_last_apply, knx_backup_device, knx_reconstruct_device, knx_restart_device, knx_restore_parameters, knx_restore_tables and the Home Assistant tools carries summary: what happened or would happen, by device name and room, with no id unless a thing has no name. The file paths, digests and ids stay in the payload.

A device plan also carries what_you_will_notice: device and room, takes (the duration of the device's last verified write, else a default; for a flash the 30 to 50 s restart), meanwhile (only this device does not react; the rest of the house keeps working), backup, changes (each changed link and parameter in plain words, by object, channel and group name) and to_test (what to try afterwards, from the changed links and parameters). The sentences, changes and plan_digest are as before.

The apply job

A client bridge may cut a tool call at 60 s, which a secured apply with a restart and a read-back exceeds. So knx_apply_device runs every gate, the snapshot and both backups inside the call, and the write as a job in the server:

  • A refusal in the pre-flight is the call's reply; nothing was written and no job remains.
  • After the pre-flight the call waits up to 20 s (from its start) for the write. If it ends, the reply is the full result (started: false, done: true). If not, the reply is started: true with the job id, and knx_job_status {job} (or knx_apply_status {job}, the same payload without question) reports the step, the download progress and the final result.
  • The pre-flight's device read is bounded too: past the 20 s read wait the call answers started while the pre-flight runs on, and a refusal after that ends the job with result.refused: true, nothing written. knx_plan_device runs its read the same way, as a plan job.
  • One job per server at a time. A second knx_apply_device, or a knx_plan_device, while an apply runs is refused with the running job's id. The job holds the bus lock and the management slot until it ends.
  • The job's record is apply-result.json in its history snapshot's directory (.bussard/history/<snapshot>/), written when the write starts and again when it ends. knx_last_apply {address} returns the latest job for a device, from the session or from that record, so a lost reply is recoverable after a server restart.
  • A record left running by a stopped server reads as interrupted: plan again before trusting the device.
  • The status tools never touch the bus.

The CLI apply is unchanged by this.

Certificate enrolment

A KNX Secure device's certificate (its 36-character code) enters the key store without passing through the chat. knx_enroll_certificates starts the session of bussard keys enroll in the server process and opens a pairing page in the human's browser: it shows the session code, a QR code of the phone link (and the link as text) and the certificates as they arrive. The human scans the QR code with a phone and the certificates on the page the link opens. Each certificate is entered as bussard keys add-certificate enters it: matched by its serial number, saved and read back. knx_enroll_status reports serial, address, name and status per certificate; no tool input or output carries a certificate's code or a key. The link carries the session's public key only.

The link and the session code never pass through the assistant. A link the assistant relays proves nothing: a prompt injection could hand the human another link with a matching code. So bussard opens the pairing page itself (open on macOS, xdg-open on Linux, start on Windows). The page is served by the MCP server on 127.0.0.1 at a free port, under a random path, answers only to that exact host and lives as long as the session. When the client declares URL-mode elicitation, the pairing page goes through it instead, and the chat app asks the human before opening it (a client that speaks protocol 2026-07-28 gets the request inside the tool's input_required answer). When nobody can see a browser on the server's computer (an SSH session, or Linux without DISPLAY and WAYLAND_DISPLAY) the tool refuses: run bussard keys enroll in a terminal instead.

The assistant flow:

  1. knx_enroll_certificates. bussard opens the pairing page; the human scans its QR code with the phone and checks that the phone shows the same session code. The assistant never sees either and never offers one of its own.
  2. The call stays open while the human scans and returns when the session ends, so the chat continues by itself: the assistant summarises the result in one or two lines and suggests the next step (for example bussard scan for certificates with no device yet). Claude Code moves a call that runs longer than 2 minutes to a background task and continues when it settles. When the result says session: running instead, the assistant waits with knx_enroll_status and until_end: true.
  3. The pairing page ends with "Done. You can close this tab and go back to your chat." and tries to close itself; a browser lets a page close only a tab a script opened, so the message stays otherwise.
  4. The session ends when the human finishes on the page, on knx_enroll_status with stop: true, when no phone joins within 10 minutes, 15 minutes after the phone's last sign of life, or after 4 hours.

One phone owns a session. When another phone opens the link, knx_enroll_status counts it in refused_phones and sets warning; tell the human, and stop the session if the phone was not theirs. When the page or relay is not the default, knx_enroll_certificates returns warnings.

By default the link opens the hosted page and relay, or the ones the [enroll] table of bussard.toml names. With local: true the server serves the page and the relay itself on 127.0.0.1 at a free port, on one origin, so the link names no relay; the pairing page offers a button that opens it in a browser on the computer running the server (a webcam, or codes typed in), not on a phone. One session runs at a time. The key store needs BUSSARD_KEYRING_PASSWORD in the server's environment.

The Home Assistant tier

--allow-home-assistant lets the assistant close the loop on the Home Assistant side. After a group address or a link changed, it shows what the KNX YAML Home Assistant reads would change and, after the human said yes, writes it and reloads the integration. It needs the flag and a [home_assistant] table in bussard.toml (see bussard.toml); with only one of the two the tools are not registered. The tier never touches the KNX bus.

[home_assistant]
url = "http://homeassistant.local:8123"
token_env = "BUSSARD_HA_TOKEN"     # the default
config_path = "../ha/knx.yaml"     # relative to the project folder

Warning

Every Home Assistant change needs an explicit yes. Reads (knx_ha_status, knx_ha_plan) are free.

  • The token is a Home Assistant long-lived access token (profile page, Security). It is read only from the variable token_env names, exported or from the project's .env (a .env supplies BUSSARD_* names only). It is sent as a bearer header and appears in no result, error or log line. Keep it in an untracked .env. A long-lived token is an admin credential for Home Assistant: revoke it on the profile page when the laptop leaves.
  • Status. knx_ha_status calls GET /api/, /api/config, /api/config/config_entries/entry and /api/states, and changes nothing. KNX entities created in Home Assistant's UI live in its .storage and are not visible through the REST API; bussard neither lists nor touches them.
  • One file, YAML-managed. The only file written is config_path, and only when bussard recognises it: a package file with the single top-level key knx: (what bussard ha-config prints), or the inside of the block when configuration.yaml says knx: !include knx.yaml (every top-level key a KNX platform). The written file keeps that layout. A missing or empty file, a file with other top-level keys and a file that is not YAML get no digest; file.reason says what to do. For a new file: create it with knx: or {}, and include it from configuration.yaml.
  • Plan digest. knx_ha_plan returns plan_digest, a SHA-256 over the file path, the layout, the text to write and the file's current bytes. knx_ha_apply refuses unless the digest came from this server session within --plan-ttl-minutes (default 10) and a new plan reproduces it, so an edit to the project, to ha.toml or to the file after the plan retires it. A digest is single use.
  • Human approval. The tool descriptions tell the assistant to show the sentences to the human and to call knx_ha_apply only after an explicit yes in the conversation.
  • Write, then reload. The apply checks that Home Assistant answers with the token, keeps the file's bytes under <model dir>/captures/backups/ha/<unix seconds>.yaml, writes the new text to a temporary file beside the target and renames it over the target, then calls POST /api/services/knx/reload, then reads the status again. A failed write reloads nothing. A failed reload is reported with the backup path, and the file stays written; restoring is copying the backup over the file and reloading.
  • No other change. The tier calls knx.reload and automation.reload and no other service, and writes no other configuration.
  • Audit lines. Each apply writes audit: knx_ha_apply wrote <path> ... on stderr.

bussard-managed automations

Some logic the bus cannot do alone, such as "when Zu Hause (4/3/2) receives 1, switch guest mode (4/3/10) off". The assistant proposes it as a rule, and bussard writes it as a Home Assistant automation through the config API (/api/config/automation/config/<id>). The rule shape is deliberately small:

{
  "id": "bussard_guest_mode_end",
  "alias": "Zu Hause beendet Gastmodus",
  "description": "Zu Hause ends guest mode",
  "when": { "ga": "4/3/2", "value": "1", "dpt": "1.001" },
  "then": [ { "send": { "ga": "4/3/10", "value": "0", "dpt": "1.001" } } ]
}
  • id starts with bussard_, then lowercase letters, digits and underscores (64 characters at most). alias defaults to the rule's sentence. description is optional.
  • when.ga triggers on an incoming GroupValueWrite. when.value (human form, as knx_write_group takes it) narrows it to one value; without it any value triggers.
  • then lists one or more sends, run in order.
  • Every address must be in groups.toml. dpt is optional when groups.toml types the address and refused when it contradicts it. A send to a protected = true address is refused.

Behaviour:

  • bussard updates or removes an automation only when its id starts with bussard_ and its description carries the line managed by bussard (model <model dir name>). An automation made by hand, even under a bussard_ id, is refused and never touched.
  • knx_ha_plan lists the bussard_ automations Home Assistant runs and flags addresses the project no longer has.
  • knx_ha_automation_plan returns the automation and a plan_digest, a SHA-256 over the id, the config to write and the config Home Assistant stores now. knx_ha_automation_apply takes the digest after the human's yes, renders the rule again against the current project, reads Home Assistant again, and refuses when either moved.
  • Before an update or removal, the previous automation's JSON is kept under captures/backups/ha/automation-<id>-<unix seconds>.json. Restoring is posting it back, or re-planning the old rule. Then bussard writes and calls automation.reload.
  • knx_ha_automation_remove plans without a digest and deletes with one.
  • The stderr audit lines are audit: knx_ha_automation_apply wrote <id> and audit: knx_ha_automation_remove deleted <id>.
Details

The rendering, for Home Assistant 2024.10 or later:

  • Trigger: the KNX integration's knx.telegram trigger on when.ga, incoming GroupValueWrite only.
  • Value match: a template condition on trigger.payload in the raw form the integration reports: an integer for a 1-, 2- or 4-bit DPT ({{ trigger.payload == 1 }}), a list of octets otherwise ({{ trigger.payload | list == [255] }}).
  • Sends: one knx.send action per send, with the raw payload bussard encodes from the value and DPT: an integer for a sub-byte DPT (1.001 0 becomes 0), a list of octets otherwise (5.001 50% becomes [128]). Home Assistant then needs no type.
  • Mode: single.
  • Marker: the description gets the line managed by bussard (model <model dir name>).

Argument errors and the server log

A tool call whose arguments do not fit comes back as a tool error that says what reached the server, followed by the fields the tool expects:

Error text What it means
"the call reached bussard without any arguments (the client sent none)" The client or a bridge dropped the arguments: the request carried no arguments member. The fix is on the client side; retry with the arguments as a JSON object.
"with an empty object as its arguments" The client sent {}.
anything else serde's own text, with the path of the offending field, e.g. com_object: invalid type: string "seven", expected u16.

The server logs every tools/call on stderr at info level (-v): the tool name, whether arguments was present, and the names of the fields received, never their values. A rejected call is also logged at warn level, so it shows without -v. With -vv the raw request is logged too, with every string value replaced by <redacted>.

Claude Desktop writes a server's stderr to ~/Library/Logs/Claude/mcp-server-<name>.log on macOS, where <name> is the key in mcpServers. Claude Code shows it in the session's MCP output.