bussard
Open-source CLI for KNXOpen-Source CLI für KNX

Your KNX installation, in plain text.Deine KNX-Installation, in Textform.

Start from scratch or import your ETS project. bussard keeps your KNX configuration in TOML files that you edit by hand or with your favorite LLM. It programs your devices, decodes the bus and keeps a history of every edit, so you can undo it.Starte ein neues Projekt oder importiere dein ETS-Projekt. bussard hält deine KNX-Konfiguration in TOML-Dateien, die du von Hand oder mit deinem LLM bearbeitest. Es programmiert deine Geräte, decodiert den Bus und speichert jede Änderung in einer Historie, damit du sie zurücknehmen kannst.

Download Read the docsZur Doku v0.1.0 · macOS, Linux, Windows
bussard
$ bussard import house.knxproj
imported 318 group addresses, 72 devices, 540 link entries → the current directory
$ claude mcp add knx -- bussard mcp --dir "$PWD"
> The hallway button should also switch the porch light.Der Flurtaster soll auch das Terrassenlicht schalten.
✓ Outdoor actuator, channel C, now listens to
  Hallway light. Project only, saved to history.Außenaktor, Kanal C, hört jetzt auf
  Flurlicht. Nur im Projekt, in der Historie gesichert.
$ bussard plan 1.1.7
1.1.7 Outdoor actuator
  + c-switch now listens on 1/1/1 (Hallway light)
$ bussard apply 1.1.7 --allow-remote-gateway
apply 1 change(s) to 1.1.7 via 192.0.2.10:3671? [y/N] y
backup written to captures/backups/
apply verified: address table Loaded (4 entries), …
$ 
FeaturesFeatures

Day-to-day KNX work, in a chat.KNX-Alltag im Chat.

Ask an assistant that speaks MCP, such as Claude Code, Claude Desktop or Codex CLI. It sets up your project from the ETS export, then edits it and writes a device only after your yes. Pick a step to see an example.Frag einen Assistenten, der MCP spricht, etwa Claude Code, Claude Desktop oder Codex CLI. Er richtet dein Projekt aus dem ETS-Export ein, dann bearbeitet er es und schreibt ein Gerät erst nach deinem Ja. Wähle einen Schritt für ein Beispiel.

bussard mcp
Set up my house. The ETS export is house.knxproj.
toolknx_setup{"project_file": "house.knxproj", "download": true}
The export is password-protected. I opened a password form on this computer; the password stays out of this chat. Also, 6 devices lack vendor product data. May I download it?
Yes.
Found the KNX IP Interface at 192.0.2.10. Imported 86 group addresses, 24 devices and 190 links. Validation: no errors, 3 warnings.
Richte mein Haus ein. Der ETS-Export ist house.knxproj.
toolknx_setup{"project_file": "house.knxproj", "download": true}
Der Export ist passwortgeschützt. Ich habe ein Passwortformular auf diesem Rechner geöffnet; das Passwort bleibt aus dem Chat heraus. Außerdem fehlen für 6 Geräte die Produktdaten des Herstellers. Darf ich sie herunterladen?
Ja.
KNX IP Interface unter 192.0.2.10 gefunden. 86 Gruppenadressen, 24 Geräte und 190 Verknüpfungen importiert. Prüfung: keine Fehler, 3 Hinweise.

Register the server on an empty folder and the assistant does the setup. At the terminal, bussard init house.knxproj does the same.Registriere den Server auf einem leeren Ordner, und der Assistent übernimmt das Setup. Im Terminal macht bussard init house.knxproj dasselbe.

How it worksSo funktionierts

A KNX project, configured in TOML.KNX-Projekte, konfiguriert in TOML.

Everything bussard knows about your installation is stored in text files. Edit them in any editor, or let Claude / ChatGPT do it. Commands either write that config to devices or read the bus and explain it with the same config. Every edit can be undone.Alles, was bussard über dein Projekt weiß, ist in Text Dateien gespeichert. Bearbeite sie in einem beliebigen Editor oder lass das von Claude / ChatGPT erledigen. Mit Befehlen kannst du dann die Konfiguration auf die Geräte schreiben oder den Bus lesen. Jede Änderung lässt sich zurücknehmen.

.knxproj ETS project export, optional ETS-Projektexport, optional .knxprod vendor product data, optional Herstellerdaten, optional import import-product Your KNX config as TOML files Deine KNX-Konfiguration als TOML-Dateien groups.toml · devices/*.toml · bussard.lock · with history and undo built in groups.toml · devices/*.toml · bussard.lock · mit Historie und Undo Claude / ChatGPT Claude / ChatGPT files or MCP Dateien oder MCP edits the files bearbeitet die Dateien MCP write path Schreibweg validate · plan · apply · flash observe path Beobachtungsweg monitor · capture · read · viz bussard CLI, MCP server, live network view CLI, MCP-Server, Live-Netzwerkansicht KNXnet/IP gateway KNXnet/IP-Gateway tunneling or routing Tunneling oder Routing KNX bus KNX-Bus actuatorpush buttonsensorweather AktorTasterSensorWetter
Green is the write path: bussard turns the config into device tables and downloads them. Amber is the observe path: telegrams get device names, group address names and typed values from the same config.Grün ist der Schreibweg: bussard macht aus der Konfiguration Gerätetabellen und lädt sie auf die Geräte. Gelb ist der Beobachtungsweg: Telegramme bekommen Gerätenamen, Gruppenadressnamen und typisierte Werte aus derselben Konfiguration.

One line per group address (groups.toml) and one file per device (devices/1.1.47.toml) including a table per channel. Keys and values come from the vendor's product data, so a channel reads like its page in ETS. Vendor ids and memory offsets live in the generated bussard.lock, which nobody edits.Die Gruppenadressen (groups.toml) und die Geräte (devices/*.toml) werden jeweils in einer Datei mit Tabellen für jeden Kanal konfiguriert. Die Keys und Werte stammen aus den Produktdaten des Herstellers, daher liest sich ein Kanal wie seine Seite in der ETS. Hersteller-IDs und Speicher-Offsets stehen im generierten bussard.lock, das niemand bearbeitet.

groups.toml
project = "Demo House"

groups = [
 {address="1/1/1", name="Hallway Light", dpt="1.001"},
 {address="1/1/7", name="Porch Light", dpt="1.001"},
 {address="1/1/8", name="Porch Status", dpt="1.001"},
 {address="3/0/0", name="Alarm", protected=true, dpt="1.005"},
]
devices/1.1.47.toml
address = "1.1.47"
name = "Switch actuator, 2-gang / blinds actuator, 1-gang"
product = "230021SU"

[location]
floor = "DG"
room = "Gast 2 Süd"

[channel.relaisausgaenge-1]
betriebsart = "Lüftungsklappe / Dachfenster"
langzeitbetrieb.listen = ["3/1/20"]
rueckmeldung-lueftungsklappen-dachfensterposition.send = "3/1/23"
Writing to devicesAuf Geräte schreiben

Every device write follows the same six steps.Jeder Schreibvorgang folgt denselben sechs Schritten.

You see what will change before anything is sent, and the previous state is saved so you can go back. An assistant edits the project. It writes a device only on a server started with --allow-programming, after your yes to its plan.Bevor etwas geschrieben wird, siehst du, was sich ändert. Der vorherige Zustand wird gesichert, damit du zurück kannst. Ein Assistent bearbeitet das Projekt. Auf ein Gerät schreibt er nur mit einem Server, der mit --allow-programming gestartet wurde, und erst nach deinem Ja zu seinem Plan.

  1. ReadLesenRead the device's tables and parameters.Tabellen und Parameter vom Gerät lesen.
  2. DiffVergleichenCompare them with your project.Mit deinem Projekt vergleichen.
  3. ConfirmBestätigenThe plan names the gateway and asks for a yes.Der Plan nennt das Gateway und fragt nach einer Bestätigung.
  4. Back upSichernSave what the device holds now to disk.Den aktuellen Stand des Geräts auf die Platte sichern.
  5. WriteSchreibenWrite the changed tables and parameters.Die geänderten Tabellen und Parameter schreiben.
  6. VerifyPrüfenRead back and compare with your project.Zurücklesen und mit deinem Projekt vergleichen.
Reading the busDen Bus lesen

One telegram, fully decoded.Ein Telegramm, vollständig decodiert.

Raw KNX telegrams carry addresses and bytes. bussard resolves both against your config, so a line in monitor reads like a sentence.Rohe KNX-Telegramme enthalten Adressen und Bytes. bussard löst beides gegen deine Konfiguration auf, sodass sich eine Zeile in monitor wie ein Satz liest.

12:03:44.809time receivedEmpfangszeit
1.1.1sender, individual addressSender, physikalische Adresse
Push Button Hallwaydevice name from its file in devices/Gerätename aus seiner Datei in devices/
→
0/0/0group addressGruppenadresse
Hallway Light SwitchGA name from groups.tomlGA-Name aus groups.toml
= Ondecoded valuedecodierter Wert
(1.001,datapoint type, sets the decoderDatenpunkttyp, bestimmt den Decoder
obj "Rocker 1")com object that sent it, from its device filesendendes Kommunikationsobjekt, aus seiner Gerätedatei
Addresses come from the telegram. Names, datapoint types and com objects come from the TOML files. A group address missing from the config shows as raw hex until you add it.Adressen kommen aus dem Telegramm. Namen, Datenpunkttypen und Kommunikationsobjekte kommen aus den TOML-Dateien. Eine Gruppenadresse, die in der Konfiguration fehlt, erscheint als rohes Hex, bis du sie ergänzt.
LLM accessLLM-Zugriff

Four tiers for the MCP server.Vier Stufen für den MCP-Server.

An agent gets exactly the access you start the server with:Ein Agent bekommt genau den Zugriff, mit dem du den Server startest:

$ claude mcp add knx -- bussard mcp --dir "$PWD"

bussard mcp --listen serves the same tools over HTTP, for a client that connects to a URL.bussard mcp --listen bietet dieselben Tools über HTTP an, für einen Client, der sich mit einer URL verbindet.

Home Assistant users: bussard ha-config writes the KNX integration config from the same TOML files. With --allow-home-assistant the assistant writes it for you, after your yes.Für Home Assistant erzeugt bussard ha-config die Konfiguration der KNX-Integration aus denselben TOML-Dateien. Mit --allow-home-assistant schreibt der Assistent sie für dich, nach deinem Ja.

Download

Simple Installation. Einfache Installation.

Just download and run. Each file has a .sha256 checksum next to it. Links always point to the latest release.Einfach herunterladen und starten. Zu jeder Datei gibt es eine .sha256-Prüfsumme. Die Links zeigen immer auf das neueste Release.

This machineDieser Rechner
macOS
Apple Silicon
Download
bussard-macos-arm64 · sha256
This machineDieser Rechner
macOS
Intel
Download
bussard-macos-x64 · sha256
This machineDieser Rechner
Linux
x86_64
Download
bussard-linux-x64 · sha256
This machineDieser Rechner
Linux
arm64, Raspberry Pi 4 and laterarm64, Raspberry Pi 4 und neuer
Download
bussard-linux-arm64 · sha256
This machineDieser Rechner
Windows
x64
Download
bussard-windows-x64.exe · sha256

Or let an installer do itOder ein Installer macht's

# macOS and Linux# macOS und Linux
curl -fsSL https://raw.githubusercontent.com/tmbo/bussard/main/install.sh | sh

# or with Homebrew# oder mit Homebrew
brew tap tmbo/tap && brew trust tmbo/tap
brew install tmbo/tap/bussard

# Windows, in PowerShell# Windows, in der PowerShell
irm https://raw.githubusercontent.com/tmbo/bussard/main/install.ps1 | iex

The installers verify the checksum and put bussard on your PATH. A binary downloaded by hand needs chmod +x, and on macOS once xattr -d com.apple.quarantine, because it is not notarized. Windows shows a SmartScreen warning for the same reason.Die Installer prüfen die Prüfsumme und legen bussard in den PATH. Eine von Hand geladene Binary braucht chmod +x und auf macOS einmal xattr -d com.apple.quarantine, weil sie nicht notarisiert ist. Windows zeigt aus demselben Grund eine SmartScreen-Warnung.

Or build from sourceOder aus dem Quellcode bauen

# needs Rust 1.88 or newer# braucht Rust 1.88 oder neuer
git clone https://github.com/tmbo/bussard
cd bussard
cargo install --path crates/bussard-cli

You need a KNXnet/IP gateway to talk to a bus. An ETS export and vendor .knxprod files are optional but make the first minutes much nicer.Du brauchst ein KNXnet/IP-Gateway, um mit einem Bus zu sprechen. Ein ETS-Export und .knxprod-Dateien der Hersteller sind optional, machen die ersten Minuten aber deutlich angenehmer.

This is early software that writes to real building hardware. Device programming covers System B (masks 07B0, 27B0, 57B0) and System 7 (masks 0700, 0701, 0705); the device support page lists the rest. Read the safety notes before your first write, and try it on a spare device or the simulator first.Das ist frühe Software, die auf echte Gebäudetechnik schreibt. Geräteprogrammierung deckt System B (Masken 07B0, 27B0, 57B0) und System 7 (Masken 0700, 0701, 0705) ab; den Rest listet die Seite Geräteunterstützung. Lies die Sicherheitshinweise vor dem ersten Schreiben und probiere es zuerst an einem Ersatzgerät oder im Simulator aus.

DocumentationDokumentation

Everything from the first command to the wire format.Alles vom ersten Befehl bis zum Protokoll.