nickol-knx-mcp/examples/demo-home/README.md

Demo House — end-to-end example

A complete, synthetic worked example of the whole stack this project targets:

demo-home.knxproj   →   nickol-knx-mcp   →   generated/ (report · HA entities · ETS export)
   (KNX design)          (design-time)              ↓
                                            ha-brain/ (Home Assistant smart logic)

It exists so you can see real input → real output without needing your own project, and as a showcase of how the KNX (I/O) and Home Assistant (logic) layers fit together.

What's here

Path	What it is
demo-home.knxproj	The synthetic project: 239 group addresses, 47 ETS Functions, 13 zones (living w/ fireplace, kitchen, master + 2 kids bedrooms each with ensuite, guest WC, laundry, 2 corridors, staircase). Lighting (switch/dim/CCT/RGBW), underfloor heating + AC, sensors, scenes.
generated/project_report.md	project_report output — inventory + 🔴🟡🔵 findings + HA mapping preview.
generated/home-assistant-knx.yaml	generate_ha_package output — KNX entities (switch / light incl. RGBW/RGB/CCT colour / cover / climate / binary_sensor / sensor) + a review list. Nothing is dropped silently.
generated/group-addresses.xml / .csv	generate_ets_group_addresses output — ETS-importable.
ha-brain/	The Home Assistant smart layer on top of these entities — circadian lighting, multi-factor climate, presence/season/time logic, statistics. See its own README.

What the tool found (and the deliberate flaws)

The project intentionally contains 5 mistakes so the checks have something to catch — see them flagged in generated/project_report.md:

#	Planted mistake	Caught?
1	A group address with no DPT (Living room CO2, 4/2/1)	✅ check_dpt 🔴
2	Two GAs with the same name, different DPT (Kitchen temperature)	✅ check_dpt
3	A dimmer with an on/off status but no brightness status (Kitchen worktop LED)	✅ check_missing_status (missing_value_status)*
4	A switch with no status at all (Guest WC ceiling)	✅ check_missing_status
5	A GA with an empty name (2/5/2)	✅ check_naming 🔴

* Now fixed (role-aware feedback completeness). This demo originally surfaced an honest limitation — the missing-status check asked "does this control have a status?", so the Kitchen dimmer's on/off status masked its missing brightness status. detect_role_completeness now flags a brightness/position command (5.001) that has no matching value status (missing_value_status), without borrowing a sibling device's status. Recall on this demo is now 5/5.

Inventory: 239 GAs · 47 Functions · 0 errors that block parsing. The HA generator produced 19 switches, 13 lights (incl. RGBW / RGB / CCT colour), 6 covers, 6 climate zones, 13 binary sensors, 41 sensors — on/off, brightness, colour and climate command/status pairs assembled into multi-address entities, with 18/19 switches getting a state_address paired via ETS Function roles.

Generated by the current tool. Lights carry rgbw_address / color_address / color_temperature_address (+ color_temperature_mode) where the project has colour; climate entities carry temperature_address, target_temperature_state_address, operation_mode_address and command_value_state_address — keys verified against the Home Assistant KNX docs. A climate is emitted only when its required keys are present, otherwise the zone is sent to review, so an invalid entity is never written. Reserve / logic / scratch group addresses are classified and kept out of the error and missing-status checks (none in this clean synthetic project, but it stops the tool crying wolf on real ones).

⚠️ Caveats (please read)

• Synthetic & generated — does NOT import into stock ETS. This .knxproj was authored programmatically (ETS6 schema project/22) — not exported from ETS. It parses cleanly with xknxproject (the library this tool uses) and is intended for tool validation and demonstration. A professional KNX engineer confirmed that ETS rejects it on import ("Project file has no valid signature") — ETS cryptographically signs its own projects and that signature can't be forged (by design). So: use this file with xknxproject-based tooling. To get a real, ETS-signed project, import the group-address export (generated/group-addresses.xml) into a fresh ETS project via Import Group Addresses and export from ETS — that file opens everywhere and is the gold standard. This round-trip was done and validated: a KNX engineer imported the export into ETS6 and sent back a real signed .knxproj, and the tool ran the full pipeline on it cleanly (note that an Import Group Addresses round-trip does not carry ETS Functions, so command/status pairing then relies on naming alone).
• The flaws are on purpose. Do not "fix" them — they are the point.
• ha-brain/ is a design demo. Valid Home Assistant YAML built on best practices, but not deployed against a live bus here; entity IDs assume the names generate_ha_package produces.