BREMA for KNX MCP4KNX
Firmware that turns the TUL into an MCP server, so an agent can commission KNX devices without ETS — addresses, tables, parameters. Product data and the project record come from two services in your own network.
runs on: TUL
Most KNX gateways relay group telegrams: they talk to devices somebody else configured with ETS. This firmware speaks the connection-oriented management services ETS itself uses. It gives a device its individual address, reads and writes memory and properties, drives the Load State Machines, installs address and association tables, restarts the device so the change takes effect, and hands the result to Home Assistant.
The stick answers MCP over plain HTTP on your LAN — no proxy and no cloud account. The tools an agent is offered are generated from the firmware’s own registry, so they cannot drift from what the device can actually do. Two services you run in your own network complete it: knxprod-mcp for the manufacturers’ product data and knxproject-mcp for the installation’s record. The stick finds them by itself and forwards their tools.
It is the KNX incarnation of BREMA (Busware Rule Engine Model Assistant), where what a device means lives as data rather than compiled into the firmware. The project is documented in the open at github.com/tostmann/BREMA — that repository holds the documentation, not the firmware sources.
Do you still need ETS?
In a KNX installation, ETS does four jobs: it holds the manufacturers’ product data, keeps the project, programs the devices and helps diagnose the bus. Here they are spread over the firmware and the two services, and none of them needs ETS:
| Job | Without ETS, here |
|---|---|
| Product data | knxprod-mcp reads the .knxprod files you supply: which product an ApplicationId is, its com objects, its parameters with memory address and value meanings, and what raw memory bytes decode to. |
| Individual address | The stick checks that the address is free and that exactly one device is in programming mode, writes the address, verifies it and takes the device out of programming mode. |
| Group addresses | The address and association tables are built from the links and installed as one operation: load session, chunks verified by read-back, close, restart. |
| Parameters | The load procedure comes from the device’s product file; the parameter is written inside a load session, verified by read-back, and the device restarted. |
| Project | knxproject-mcp keeps the installation’s record between conversations: topology, devices, group addresses, links, parameters and the owner’s decisions, each with its source. |
| Diagnostics | A passive survey of every telegram on the line, an active sweep for the devices on a line, and each device’s identity, properties and memory read back. |
The whole chain — address, tables, parameter, restart — is documented end to end on a Merten 649802 blind actuator. A device with another load procedure is a new case: let the agent run it as a dry run first.
Where ETS is still the tool:
- KNX Secure. The stick does not speak it; a device that is to run secured is commissioned with ETS.
- System B devices. Devices with mask 07B0, OpenKNX devices among them, have their tables allocated at load time and in a format of their own. The stick so far writes tables only into fixed memory segments, so it cannot load them yet.
- An ETS project to hand over. The record cannot write a
.knxproj, and cannot read one yet. It imports ETS group-address exports (ESF), ETS3 project databases, and Home Assistant and FHEM configurations. - Recovery. A device left unusable by a wrong memory write may need ETS to get back.
- Licence terms. Some manufacturers allow their product files in KNX-recognised tools only. Check the terms before you load one.
Features
- A table install is one operation. Opening the load session, writing the table in chunks each verified by read-back, closing it and restarting the device is a single verb execution that nothing can interrupt half-way, and whose close runs even when a write fails. A device left mid-download resolves no group address at all, and a power cycle does not reliably recover it.
- Mutating verbs default to a dry run. The dry run performs every read and withholds only the write, so its report is truthful about whether the real thing would work. Reaching the bus takes an explicit decision.
- Danger classes per verb, reported by the stick itself: read-only, local state, changes a physical device, changes the stick’s own security state.
- Delivery verdicts instead of fire-and-forget — sent, link-acknowledged, application-acknowledged, application error, timeout, no bus.
- Memory writes are allow-listed, never addressed at runtime. A wrong write does not switch the wrong light; it can leave a device needing ETS to recover.
- Reads an installation it did not build — a passive survey of everything it hears, plus an active sweep that finds the devices on a line and reads the identity that maps each to its product file.
- Product data and the project record (lab feature) — the two services run as Docker containers next to the stick, which finds them via DNS-SD and forwards their tools and skills, on your network and through remote access alike. The project tools that write change the record, never the bus.
Requirements
- A TUL — ESP32-C6 with the NCN5130 TP1 transceiver. The flasher reads the stick and writes the firmware together with a pass issued for that individual device, so this runs on busware TUL hardware only: the KNX pins differ per product, and an image driving the wrong ones would drive somebody’s bus.
- An MCP-capable client. A MQTT broker is optional — everything else works without one.
- For KNX semantics, the manufacturer’s
.knxprodproduct file: it is the only place a ComObject number or a parameter address means anything. - Optional, for product data and the project record: a Linux machine with Docker in the same network segment as the stick — tested on a Raspberry Pi 5 and an x86-64 server.
Getting started
Flash it in the browser at install.busware.de/TUL/mcp/ and provision Wi-Fi in the same USB session over Improv — credentials are never compiled in. The stick then serves its own page at http://busware-knx-<id>.local/, showing its addresses, its hardware identity and the ready-made command:
claude mcp add --transport http busware-knx http://busware-knx-<id>.local/mcpPoint an agent at it and describe what you want commissioned. For product data and the project record, one Compose file starts both services: Running the services.
Documentation
- BREMA for KNX — what the KNX firmware does and how to get it, including the two services.
- knxprod-mcp — the product-data service, forwarded by the stick.
- knxproject-mcp — the project service: the record of your installation between conversations.
- Orchestrating KNX with an LLM (German) — a real commissioning session end to end, including the wrong turns, which are the more instructive half.
- Der BREMA-Fachartikel (German) — the long-form treatment: architecture, the gated onboarding loop, worked examples on real radio devices, and a reproducible four-model LLM comparison.
Limits
KNX is the first published backend. Zigbee, EnOcean and HomeMatic run on the same engine but are not released — only what has run on real hardware is offered for download.
The ground-truth service that keeps a model from inventing device facts is in use for the radio backends and is not openly available yet. For KNX, that index is knxprod-mcp: it runs in your own network, over the product files you obtained yourself. A shared catalogue is not offered — the files are the manufacturers’, and some allow them in KNX-recognised tools only. Without the service, the product file stays your input, and the firmware says so rather than inventing the mapping.
KNX and ETS are trademarks of KNX Association cvba.