# 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](ha-brain/README.md). |

## 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.