bussard documentation¶
bussard is an open-source command line tool for a KNX building bus. It keeps your installation as a folder of plain text files, your bussard project, and writes that project to the devices over a KNXnet/IP gateway. It decodes everything on the bus with the same project, and runs as an MCP server so an LLM assistant can read and edit the project with you.
It is for the owner of a KNX house who wants to know what every button does, change one safely and undo it, and for the integrator who needs the exact command, its flags and what it refuses. See the landing page for the overview and the GitHub repository for the source.
Talk to your house¶
You say what you want in chat, and an assistant such as Claude runs bussard for you over MCP. Start here if you own the house and would rather not learn commands.
- Install bussard.
- Connect an assistant on an empty folder and say "set up my house": it finds the gateway and imports your ETS export, if you have one.
- The first weekend: an audit, a backup of every device, one change and its undo.
Work at the terminal¶
You type the commands yourself and read their output. Start here if you are an integrator, or want the exact command and its flags.
- Install bussard.
- Your first project:
bussard importturns an ETS project export (.knxproj) into a bussard project in a minute; without one,bussard initcreates an empty project and you scan, reconstruct or adopt the devices you have. - The how-to guides, one task each.
Every guide shows both forms, in chat and at the terminal. Read Safety before your first write.
Getting started¶
- Install bussard: installers, the binary and its checksum, building from source.
- Your first project: import or init, validate, monitor.
- Connect an assistant: an LLM over MCP and a first conversation.
- The first weekend: an owner's path from install to a backup on a USB stick.
How-to guides¶
- Watch the bus: monitor, read, the browser view, capture and history.
- Find what you have: audit, scan, describe, reconstruct, free tunnel slots.
- Change what a button does: plan, apply and undo a link change.
- Change a parameter: the device dialog, then apply or flash.
- Add a device: adopt, flash a fresh device, label on the bench.
- Back up and replace a device: backup, restore, replace a dead device.
- Commission a line: plan group addresses, commission, test.
- Exchange with ETS: names into ETS, what a new export changes.
- Work with an integrator: bundles and shared repositories.
- Home Assistant: generate and tune the Home Assistant config.
- KNX Secure: the key store, secure tunnelling, secure a group address.
Reference¶
- Commands: every command by group, with its flags, refusals and verification steps.
- Global options and environment variables: what every command shares, exit codes, the
.envfile. - The project folder and its files: every file and key, the lock, the key store, parse errors.
- Diagnostics, product data, JSON output, MCP tools, viz API, Home Assistant.
Explanation¶
- How bussard works: the project, product data, the bus and a write.
- Safety: the rules, on one page, to read before the first write.
- Write commands: what each write command does and its rails.
- KNX Secure: keys, the key store, secrets, what secured means.
- The assistant: MCP tiers, history and undo, protected addresses.
- Device support: supported devices, the tunnel budget, known limits.