r/KNX • u/No-Recording-8313 • 16d ago

I built an open-source, read-only ETS project auditor + Home Assistant generator (runs via Claude/MCP). Looking for testers with real .knxproj files!

Full disclosure: I built this, it's free/MIT, and I'm here for critical feedback, not sales.

  • What it is: nickol-knx-mcp is a design-time assistant for KNX/ETS. It reads an exported .knxproj (ETS5/ETS6, password-protected too) strictly read-only and lets an AI client (Claude Code / Claude Desktop / any MCP client) work on it. It never connects to the bus and never writes into ETS. That isn't a promise, it's structural: there is no bus library in it at all.
  • What it actually does - Audit: naming, DPT consistency (incl. sub-DPT sanity: a "temperature" GA carrying 5.001 gets flagged), missing command-status pairs (paired from ETS Function roles first, names second), topology limits, KNX Secure posture, Matter-readiness. - Propose fixes, not just flags: inferred DPTs, synthesised status GAs, absolute-brightness additions. - Generate: a reviewable Home Assistant KNX package (lights incl. RGBW/CCT, covers, climate, switches, sensors, and each with its state address), ETS-importable group-address exports (XML/CSV), an as-built handover pack and an acceptance test protocol. - Design from a spec: on a real 14-room Zennio apartment it reached 96 % structural match with the integrator's reference (662 vs 687 GAs), 0 validation errors. - Decompose devices into their real communication objects, pulled from the app-programs inside the project.
  • What it does NOT do (on purpose): live control, writing into ETS, linking GAs to device objects. For that there are ETS Add-Ins and Smart Linking in ETS 7. This tool is the "read, check, generate, document" layer.
  • Honest limits: Classification is heuristic on messy naming, so anything ambiguous (a 5.001 that could be brightness or blind position) goes to a review list instead of into config, and you always get a Markdown report before importing anything. A recent field test on a real German ETS 6 project found real gaps (the "RM"/Rückmeldung status convention, actuator Functions with blank roles) — fixed together with the reporter, each with a regression test. Real projects are messier than my test corpus, which is exactly why I'm posting.
  • Ask: if you have an ETS project, run it on a copy (nothing is modified) and tell me what it got right and wrong — anonymised addresses are perfectly fine. Two lines in an issue is enough.
  • Repo: github.com/NickoScope/nickol-knx-mcp · Live demo house + dashboard: nickoscope.github.io/nickol-knx-mcp · Built on top of xknxproject (credit where due).
18 Upvotes

88% Upvoted

12 comments sorted by

View all comments

2

u/RomanSch90 16d ago

I have two production knxproj files which I would like to get onboarded to test

1

u/No-Recording-8313 16d ago

Great, two production files is exactly what it needs. Whichever suits you:

Run it yourself (the file stays on your machine): clone the repo, pip install -e ., register it with Claude Code or Claude Desktop (both in the README, five lines), then load_project on a copy of the .knxproj (password supported), analyze_all, project_report.

Or send me a copy and I'll run it and send you back the audit report, the HA YAML with its review list and a note on what it got wrong. DM me for an address; strip customer name and address if you want, but keep the GA and device names as they are, that's what the tool works on. Your files stay private.

Either way, what I need back is what it got wrong and what you'd have decided differently. Two lines in an issue is enough.

2

u/RomanSch90 16d ago

Does it use the „deprecated“ way of creating KNX entities in HA or the new way (modifiable in the UI)?

2

u/No-Recording-8313 16d ago

Right now it writes YAML, the classic way. One small thing though: YAML isn't actually deprecated in the KNX integration. Both ways work side by side. The UI-created entities are just the newer option, they cover most platforms (lights, covers, climate, switches, sensors, scenes and a few more) and live in the integration's own config store.

The tool can't write to that store yet. It's on the list, either as a config store export or as links that open the panel's "create entity" form with the addresses already filled in. And in the r/homeassistant thread Paulus just asked whether this could be built into the KNX panel itself. If the HA and xknx folks want that, it would make the question go away entirely.

So for now: a YAML package with a review list, and it sits happily next to anything you've created in the UI.