nickol-knx-mcp/CHANGELOG.md

Changelog

All notable changes to this project are documented here. The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Unreleased

Fixed

• Climate entities no longer merge different devices of one room. A room with floor heating, a convector or radiator and an AC unit used to become a single Home Assistant climate: the convector's setpoint, the AC's controller mode and the AC fan speed as the "valve". Valves were also taken from unrelated 5.x statuses (light brightness, blind position), room "1.09" matched "2.09", and "Kids room 1" took "Kids room 2 temperature". A climate is now assembled per room and device type (floor / wall / radiator-convector / AC, detected in RU/EN/DE names): the room code ("1.09") and the numbers in the anchor name must match, a shared untyped room sensor may serve every device in the room as current temperature but never as a device's setpoint or mode, a valve needs a valve word and an AC never gets one. Hardened after an LLM-council review: a word that sets another device of the room apart ("shower", "hall") keeps its GAs away; if a control role still has more than one candidate the device goes to review as climate_ambiguous instead of taking the first; two mode GAs that cannot be told apart go to review as climate_duplicate_anchor instead of being dropped silently; room codes only count at the start of a name ("21.5 °C", "16.10", "ДД 34.1" are not rooms); digits inside dotted codes are not room numbers; only 20.102 and 20.105 start a climate; fan coils and VRV/VRF are their own device types; valve words narrowed to valve / клапан / Stellwert. On seven real projects: no control GA used by two climates, no address lost. A 1312-GA house goes from 16 climates (several wrong) to 33 (one per device), manual climate review 33 -> 12; a 3646-GA villa keeps 21 of 23 and sends the 3 it cannot disambiguate (three thermostats in one corridor, two identical AC mode GAs) to review instead of guessing.

• Home Assistant lights without address are no longer generated. A 5.001 lighting GA with no on/off GA in its zone used to become a light with only brightness_address, which Home Assistant rejects (address is required on a KNX light). On six real projects 51 such lights were generated, mostly motion-detector parameters on 5.001 ("sensitivity", "daytime command"). They now go to the review list as light_without_switch; no address is dropped silently.

• subdpt_suspect false positives. A 1-bit, date/time or text GA named after a quantity ("on by motion detector by illuminance", "CO2 threshold", "meter value recorded, date") is a flag or timestamp, not the value, and is no longer checked (12 of 12 such hits in the corpus were false). Legitimate DPTs of the same quantity are accepted: power 9.024 and 14.080, energy 13.010 to 13.016 and 14.031, and power factor has its own rule (14.057). Checked against xknx 3.20. On a real 1312-GA house: 17 findings -> 2.

• Self-reporting commands get their state address. When the actuator's status object (Read + Transmit flags) is linked to the command GA itself, there is no separate status GA to find. The generator now uses the command GA as state_address (and the brightness GA as brightness_state_address) instead of reporting a missing status. check_missing_status already treated these as satisfied; the two now agree. On a real house 43 fewer review items, 40 to 44 entities per large project gain a state address, and no entity count changes.

Changed

• On/off lighting is generated as a Home Assistant light, not a switch. The KNX light platform takes a plain on/off light with address + state_address, and light entities are what Assist and "all lights" act on. Lighting without a status GA is reported as light_without_status. Regenerated packages move these entities from switch: to light: (220 on a real house); review before replacing a deployed package.

0.8.2 - 2026-09-14

Added

• load_ga_export(path): audit a group-address list without a .knxproj. Reads an ETS ga-export/01 XML (ETS "Export Group Addresses", or the import file a planning tool such as TapPlan writes) into a project without devices: names, addresses, DPTs (DPST-x-y, DPT-x), descriptions, the Security flag and the range tree. GA-level checks and both generators work on it; device, Function and topology tools have nothing to read and say so. Parsed through the same hardened XML reader as .knxproj members, size-capped at 50 MB. Invalid or duplicate addresses and unknown DPT tokens are skipped with an entry in import_warnings, never silently.
• Climate: setpoint shift. A DPT 9.002 or 6.010 group address whose name says shift (shift / Sollwertverschiebung / смещение / сдвиг) in a climate zone now maps to setpoint_shift_address / setpoint_shift_state_address with setpoint_shift_mode DPT9002 or DPT6010 taken from the DPT (keys per the Home Assistant KNX climate docs). It used to fall through to a plain sensor.

Changed

• Multi-address entities are named after what their addresses share. A light built from "Kitchen Spots On-Off", "Kitchen Spots B.Value" and their feedbacks is now "Kitchen Spots", not "Kitchen Spots B.Value". Lights, covers and climates take the longest common word prefix of their member names, but only when it still carries an identity token and does not drop a word containing a digit; two entities that would collide keep their original names. Found by auditing a TapPlan export. Only function words are ever cut (value, brightness, up/down, mode, Яркость, Абсолютное диммирование, Движение, Вкл…); a room, device type, channel or anything else stays. On the maintainer's six real projects 214 of 1189 entities got a shorter name and no address mapping changed. A regenerated package will therefore show different entity names than one generated before — review the diff before replacing a package that is already deployed.

Fixed

• suggest_repairs crashed on any project with a missing status GA (UnboundLocalError in repair.py). Introduced by a local-variable rename in the 12.09 typing cleanup; the test that covers it was not part of CI, which is why it shipped. CI now runs every test file in tests/ (11 were missing), not a hand-picked subset.

• suggest.py: multi-output actuators are split by their vendor object marker. Zennio-style devices (Lumento DX4, MAXinBOX, KLIC-DI…) put every output of a device into ONE ETS channel and separate them only in the object text ([1] Switch On/Off, [2] On/Off (Status)). The channel classifier used to see several switch commands in one channel, give up, and let every status object fall through to a sensor suggestion. Channels are now split into vendor sub-units first. On a real 3646-GA project: entities 341 → 513, sensor noise 752 → 367, agreement with the name/Function engine 92 % → 95 % (platform) and 94 % → 95 % (address keys).

• Device diagnostics are no longer suggested as sensors (error flags, communication failures, firmware/version, bus voltage, reset — matched in the vendor object text or the GA name, EN/DE/RU). They are counted in hints["diagnostics_skipped"] and kept out of the name-based fallback as well. 53 such objects on the same project.

0.8.1 - 2026-09-12

Added

• Published to PyPI and prepared for the official MCP Registry. server.json (schema 2025-12-11, registryType: pypi, server name io.github.NickoScope/nickol-knx-mcp) plus the mcp-name ownership marker in the README, which the registry reads from the published PyPI description. 0.8.0 carried the marker in the wrong case, which the registry rejects, hence this release.

Added

• Official MCP Registry preparation: server.json (schema 2025-12-11, registryType: pypi, server name io.github.nickoscope/nickol-knx-mcp, stdio transport, the two optional env vars) and the ownership marker <!-- mcp-name: … --> in the README, which the registry checks inside the published PyPI description. Package builds clean (uv build, twine check PASSED). Publishing itself still needs a PyPI token (owner action), then mcp-publisher login github && mcp-publisher publish.

• suggest.py — structure-first entity suggestions (experimental, library-only, no MCP tool yet). Prototype of a second Home Assistant KNX SuggestionProvider (core PR #180891 contract): device channel → communication-object flags (write = command sink, transmit = status source) → DPT pattern → HA UI entity config (ga_switch, ga_brightness, ga_up_down, ga_position_state, ga_temperature_current, …). Names are used only as tie-breaks and always recorded in metadata.review. Channels the FB provider covers are skipped; channel-less devices get pseudo-channels from vendor object texts; shared status GAs and duplicate writers are handled. tests/test_suggest.py reproduces the FB provider's own nameless fixture from structure alone; tools/eval_suggest.py measures agreement with the name/Function engine on real projects.

Fixed

• check_policy(write_example_to=…) writes an example profile seeded from the loaded project's own main groups instead of a static template (issue #13, avataru). The template listed mains the project did not have (sensor/energy/diagnostics/reserve), contradicting the real layout and sending the model off to "correct" a fine taxonomy. Now: each existing main is written with its inferred domain, range name and category mix; mains with no clear majority are written commented-out with their mix so the integrator decides; the default taxonomy stays only as a labelled comment; reserve.expect_range follows the project. _infer_taxonomy and the example now share one implementation (taxonomy_seed). Regression cases in tests/test_policy.py (now in CI).

Added

• check_topology() — topology & individual-address sanity, grounded in the KNX standard (tool count 30 → 31; analyze.py, server.py). Flags devices-per-line over the TP1 limits (info at

  64 per segment, warning at >256 per line — KNX Handbook p.36/40/55), individual addresses that don't parse as a valid A.L.D (area 0-15, line 0-15, device 0-255 — confirmed against the xknx IndividualAddress class), duplicate individual addresses (error), and multi-line TP projects with no coupler (device .0) on a line (info). Empty topology / device-less synthetic projects return no findings. Folded into analyze_all under a topology key and its severity totals. tests/test_topology.py.

Security

• Hardened parsing of untrusted .knxproj / .knxprod (safexml.py). A project file is a user-supplied ZIP-of-XML, so both XML and ZIP attack classes apply; every place we open an archive or parse XML ourselves now goes through one hardened module. XML: a dependency-free reject of any <!DOCTYPE/<!ENTITY (the billion-laughs / XXE vector — legitimate ETS XML never carries one), plus defusedxml parser-level blocking when installed (added as a dependency). ZIP: a pre-flight against absolute caps (archive size, entry count, per-member and total decompressed size, compression ratio) rejects zip-bombs, member names are checked for path-traversal / absolute paths, and each member is read through a streaming cap so a header that under-declares its size still can't exhaust memory. Wired into load_project, check_device_parameters and the app-program parser; on a violation callers return a normal {"error": ...} rather than a traceback. Still strictly read-only. Raised by external security review. tests/test_safexml.py.

Changed

• Contextual domain classification — a DPT alone no longer decides the domain (project.py, explain.py, generate_ha.py, policy.py). A 1-bit switch is domain-agnostic (a light just as easily as a pump or an AC), yet the classifier defaulted DPT 1.001 → lighting, so "Living room AC on/off" came out as lighting and then tripped downstream checks. The domain is now a combination of signals: an explicit name domain wins; a strong, domain-encoding DPT (shutter 1.008, HVAC-mode 20.102, temperature 9.001, dimming 3.007) keeps its domain; for a domain-soft DPT (1.001/1.011/5.001) the main group name disambiguates; with no signal at all a bare 1-bit GA is honestly unknown rather than a guessed lighting. When an explicit name contradicts a strong DPT the result is unknown (a genuine conflict, surfaced by explain_ga as contested) — not a silent pick. Matching is word-boundary, not substring, so "ac" no longer fires inside "terrace". Name terms broadened (English + Russian HVAC incl. ac/a/c/air conditioner, RGB/colour lighting). Verified on three real projects: every "AC on/off" is now HVAC; policy taxonomy-outlier noise fell sharply (demo 11→2, one real project 31→6, another 200→57) because check_policy now flags only misplaced actuators (lighting/shutter/HVAC) and treats sensors, scene links, thresholds and timeout parameters as the cross-cutting GAs they are. explain_ga shows the winning signal and tier; the HA generator still emits a switch for a now-HVAC simple on/off, so no device is dropped.

  Dogfooding the classifier against a deliberately messy synthetic house then hardened it further: the main-range name map no longer lets a "middle 0" clobber its main group's name (both start at the same raw address, so the old modulo heuristic overwrote "Освещение" with "Вкл/Выкл" and the range rescue silently died — depth in the range tree decides now); a category that comes from a whole-main-group DPT fallback is soft (a guess by construction — only an exact (main, sub) table entry is strong), so a vendor enum like 20.609 no longer poses as authoritative HVAC; DPT 1.010 start/stop is soft (ventilation timers use it too, not just shutters); terms learned: Cyrillic а/с, сплит, вытяжк, яркост (RU only — EN "brightness" also means weather lux), meteo/weather (sensor now outranks hvac so "Метеостанция - Температура" is a sensor, not an HVAC actuator). Round 2: presence 1.018 is a sensor (was diagnostics — its name always says so and the table fought it); 9.001 temperature is soft (room temp defaults to hvac, a weather-named temp re-domains to sensor without a fake conflict); illuminance terms ("освещённость" ≠ "освещение"); and a passive-range rule — a measurement inside a Sensors/Energy/Diagnostics main takes that domain, while a command is never retyped by a passive range. Real-project noise after both rounds: demo 2 outliers / 239 GAs (the two central macros), a 685-GA flat 10 (all defensible — a genuinely mixed water/energy main), a 3646-GA house 75 (~2%).

Added

• Room Template Library — R1 (vertical slice) (room_library.py, room_templates/, two new MCP tools; tool count 28 → 30). Compose a new KNX project from a list of parametrised room templates ("constructor"). The template format is a deliberate public contract (room_templates/SCHEMA.md): schema_version, a locale-neutral semantic slot_id (identity never comes from a human name), labels.{ru,en} for presentation, per-slot basic/comfort presets (not one monolithic room level — a house can mix comfort climate with basic lighting), and parameters where area_m2 is an explicit hint with provenance, never a normative fact. Six built-in rooms ship: bedroom, children, living, kitchen, bathroom, corridor. Templates describe functions (function-first); logic (presence→light) is declared as non-executable automation_intents metadata only. A separate resolved IR (its own dataclasses — not the public GARecord) drives allocation (main = domain, middle = role, sub sequential) with a hard error on sub-address exhaustion (never a silent overflow). Critically, the composer writes a real .knxproj (ZIP of ETS XML) and re-reads it through the standard load_project — the same path used for third-party projects — so generation never touches the classifier and is validated by the real reader. New tools: validate_room_template(template?, path?) (schema check) and compose_rooms(rooms, language="ru", project_name?, output_dir?, dry_run=true) — outputs an allocation manifest, ETS GA XML/CSV via the existing generators, and a device BOM proposal from the device library. New projects only, dry-run by default; docking into an existing project and exact device selection are R2. The generated house passes all four linters (naming / missing-status / DPT / policy) with 0 errors and 0 warnings. tests/test_room_library.py (golden RU/EN, idempotency, permutation invariance, address-exhaustion error, round-trip 0-error lint, negative-oracle manifest).

• Explainable aggregate scores (advanced.py, handover.py). Every headline percentage now ships the numbers behind it instead of a bare figure: Matter readiness, the completeness grade and command/status coverage each carry a math block with the numerator, denominator, the exact formula (that reproduces the percentage) and, for Matter, the functions excluded from the denominator because their category has no Matter cluster (previously a silent skip — the biggest source of "why is this number what it is?"). The completeness grade also states its band thresholds. A reviewer can now audit or reproduce any score. Report-only, additive. Raised by external review. tests/test_explainable_aggregates.py.

• Provenance / confidence (explain.py, new MCP tool explain_ga). The enriched model mixes ETS facts, DPT-derived structure and name heuristics; downstream tools then treat the result almost like a fact. explain_ga(address) makes the reasoning auditable for one GA: per decision (category / kind / status pairing) it reports the signals that fired with a confidence tier — authoritative (an ETS Function role) > structural (the KNX DPT) > heuristic (a name keyword) — and flags conflicts (e.g. a GA the DPT calls lighting while the name says "AC" → contested), the hotspot for silent misclassification. Additive and read-only (no change to the core model). Asked for by three independent reviewers (two external councils + a field integrator). tests/test_explain.py. Tool count 27 → 28.

• Role-aware feedback completeness (detect_role_completeness in analyze.py, surfaced through check_missing_status). "Does the function have a status?" was not enough — a dimmer with an on/off status but no brightness status silently passed and inflated coverage/Matter scores. The new check flags a brightness/position command (DPT 5.001) whose device has no matching value status (missing_value_status), using a device-identity match so it does not borrow a sibling's status. Closes the demo's own documented limitation — recall on the demo house is now 5/5. Raised by an external expert review. tests/test_role_completeness.py.

• Project Policy Profile (policy.py, new MCP tool check_policy). Validate a project against its own agreed rules (main-group taxonomy, naming regex, command/status exemptions) instead of one universal "professional standard" — a direct answer to integrator feedback that conventions differ per school. With a YAML profile the declared taxonomy is authoritative; with no profile the taxonomy is inferred from the project itself and GAs that deviate from their main group's own majority domain are flagged (policy_taxonomy_outlier) — never against an alien standard. Ships an example profile (examples/policy-profile.example.yaml) and tests/test_policy.py. Tool count 26 → 27.

• Cross-device parameter QA (param_check.py, new MCP tool check_device_parameters). Reads per-device ParameterInstanceRef values straight from the .knxproj project part (data xknxproject does not expose), groups identical devices by application program, and flags the odd one out: clear_outliers (a strong majority with a small minority — e.g. one thermostat with a different setpoint/hysteresis, one presence detector with a different detection time) and split_configs (balanced 2+ variants — review, often two zones). Parameter names resolved from the app-program. Findings are ranked by significance: a focus list of config-value outliers (setpoint/hysteresis/time/threshold — where an odd device is usually a real mistake), separated from mode/type flags and per-room text labels — on a real 275-device project this turns 422 raw outliers into a 9-item focus (incl. the thermostats whose init-setpoint differs from their siblings). Read-only; no ETS/bus; encrypted projects are skipped honestly. Validated on real 42–275-device projects; synthetic tests/test_param_check.py. Community-driven (asked for in Discussions). Tool count 25 → 26.

• skills/ha-git-backup — an ops-companion skill for the engineer package: a two-circuit Home Assistant backup system (real git in /config with a deploy key and a pre-commit secret scanner + age-encrypted full backups in GitHub Releases), with install/sync/scan/offsite/restore scripts, HA automations, a restore runbook and a mandatory monthly drill. Field-tested; the secret scanner ships canary-tested (BusyBox grep -e lesson recorded).

• Manufacturer names from the archive itself (appprog_parser.py): parse_devices_from_project now reads vendor names from the knx_master.xml shipped inside every .knxproj/.knxprod (e.g. M-0073 → HDL, M-00B6 → Ekinex S.p.A.) instead of relying on a hardcoded id map that can never be complete; the static map remains as fallback.

Fixed

• Root-cause suppression (external-review noise). A GA with an empty name has an unreliable classification, so it no longer cascades into a missing_status_address warning and a policy_taxonomy_outlier — the single root cause (empty_name from check_naming) is kept and the dependent findings are suppressed. On the demo house the empty 2/5/2 now yields one finding instead of three. tests/test_root_cause.py.

• Noise & unsafe repairs surfaced by an external expert review on the demo house. (1) Scene-control GAs (DPT 17/18) are no longer flagged as missing_status — they recall a preset and have no single state to read back (now scene_no_status, INFO), and suggest_repairs no longer synthesises a bogus boolean status GA for them. (2) Generic group commands (All blinds down, All shutters up) are now recognised as central macros (INFO) like All lights off, not missing-status warnings. (3) Synthesised repair names match the GA's language — an English project no longer gets a Russian (статус)/Значение яркости suffix. On the demo house this cut missing_status_address warnings from ~7 (mostly scenes) to the one genuine case. tests/test_council_fixes.py.

• skills/ha-git-backup: install.sh now pins core.sshCommand + a repo-local known_hosts so the nightly sync pushes from HA's Core container (was failing Host key verification failed).

0.8.0 — 2026-07-07

Lessons from a second field project (a different integrator naming school): positional command/status pairing, ref-level application programs, and two detector blind spots. All four changes were validated against a real 859-GA as-built project.

Added

• Positional command/status pairing (#4, pairing.py / analyze.py). A widespread naming school keeps feedback in a parallel middle group (command 1/0/s ↔ status 1/1/s) with the GA name duplicated 1:1 and no status keyword at all — invisible to lexical pairing. detect_missing_status now also pairs positionally (same main, same sub, different middle, identical name, DPT-compatible) and recognises self-reporting commands (the actuator's R+T communication object linked to the command GA itself). On the field project this cut missing-status warnings from 339 to 89 — the ~90 that are actually real — and reports a status_pairing_summary info with both counters.
• Application-program parser v2 (#6, appprog_parser.py). Vendors like HDL, Ekinex and Creatrol publish object names/DPTs/flags on <ComObjectRef> while the base <ComObject> is a near-empty stub. The parser now merges ref-level data over the base (conservatively: refs only fill empty fields; a DPT is taken only when every declaring ref agrees, disagreeing variants are recorded as dpt_variants, never guessed). Unverified DPTs on the field project's 15 device models dropped 4341 → 1167 (−73%). The app-program version is now picked by the highest ApplicationVersion instead of list position — a stale v16 was being parsed where v18 existed.

Fixed

• main_group_unnamed read the wrong names (#3, analyze.py): main-group names are now taken from the authoritative group_ranges (a GA record's main_name can carry a middle range's name), eliminating both false "unnamed" findings and masked truly-unnamed mains.
• Completeness grader missed pattern-named ranges (#5, advanced.py): a middle range literally called «Сцены» full of plain-named scene GAs now counts as scene evidence — the grader reads main/middle range names in addition to GA names (and the scene token matches Russian plural forms).
• Pinned mcp>=1.10,<2 — the MCP Python SDK v2 (in alpha) renames mcp.server.fastmcp.FastMCP to mcp.server.MCPServer; without the upper bound a future pip install would pull v2 and break the server import. Verified against the SDK docs.

0.7.0 — 2026-07-02

Added

• Exact device decomposition from a local catalog (device_library.py). When the NICKOL_KNX_CATALOG env var points at a device-library YAML file or directory (schema: library-schema.md), decompose_device now returns the exact vendor object model (source: catalog-exact) — real per-channel blocks, object counts, app-program version and first-instance objects with their true DPTs — instead of the generic recipe. Falls back to the built-in recipes (source: recipe-approximate) for any device not in the catalog, so behaviour is unchanged when the env is unset. The catalog itself is vendor-catalog data kept local and is not shipped with the package. Objects the vendor app-program leaves without a DatapointType stay dpt: null — never guessed.
• parse_devices_from_project (new MCP tool + appprog_parser.py) — deterministic parser that extracts the exact vendor comm-object model from the M-* application programs embedded in a .knxproj / .knxprod: per device it reports order number, app-program version, object counts and detected per-channel blocks (unit · objects-per-instance · stride), converting DPST-x-y → x.00y. Read-only and PII-safe (reads only vendor catalog data, never the client P-*/0.xml). With output_path it writes a device-library YAML into the workspace — feeding the local catalog above, so parse → catalog → decompose_device (catalog-exact) is a closed loop. Now 25 MCP tools.

0.6.0 — 2026-07-01

Completes the roadmap — the tool now validates, repairs, generates (HA / ETS / handover / IoT), diffs, grades and drafts acceptance protocols, all design-time & read-only.

Added — B-tier

• B2 — climate-correctness review (generate_ha.py). Climate generation now emits an explicit review note: controller/operation modes made explicit, setpoint-shift command and state paired, and a flag raised for any mode object that lacks a corresponding state address.
• B3 — semantic project diff (diffproj.py, new module; new MCP tools diff_projects / diff_loaded). Compares two .knxproj versions and reports added / removed / DPT-changed / renamed / security-changed group addresses — a reviewable delta between as-designed revisions.
• B4 — acceptance test protocol (advanced.py; new MCP tool generate_test_protocol). Produces a per-function acceptance checklist in Markdown for commissioning sign-off.
• B5 — Matter readiness (advanced.py; new MCP tool check_matter). Reports which functions round-trip cleanly to a Matter cluster and which do not.
• B6 — energy scaffold (advanced.py; new MCP tool check_energy). Checks metering / energy DPT coverage and scaffolds PV / battery / EVSE structure.

Added — C-tier

• C1 — KNX IoT semantic export (iot.py, new module; new MCP tool generate_knx_iot). Emits a KNX IoT Turtle / RDF skeleton for the project.
• C2 — naming suggestions (advanced.py; new MCP tool suggest_names). Naming-hygiene proposals for group addresses that drift from the zone + function convention.
• C3 — as-built completeness grader (advanced.py; new MCP tool grade_completeness). Grades a project from bare functional skeleton to as-built, by presence of professional patterns (central macros, motion tuning, astro/meteo, monitoring, deep metering, scenes, reserves, debug).

Added — A-tier quick wins

• A5 — Areas / voice note (generate_ha.py). Documents that HA Areas and voice assignment are UI-only concerns, not derivable from the .knxproj.
• A6 — time/date expose (generate_ha.py). Emits a KNX expose block for DPT-19.001 clock broadcast so HA can serve time/date to the bus.

0.5.0 — 2026-07-01

From validator to repairer. Previous releases flagged problems in a .knxproj; this one starts proposing the fix. The headline is a repair-suggestion engine that turns each finding into a concrete, reviewable change, alongside two new detectors for gaps that silently break the Home Assistant layer: relative-only dimmers and actuator-dependent cover behaviour.

Added

• B1 — repair-suggestion engine (repair.py, new module; new MCP tool suggest_repairs). For each finding it proposes a concrete fix rather than only naming the problem: infer a DPT for a group address that has none, correct a suspect sub-DPT, synthesise a status/feedback GA in a free address slot, or add an absolute-brightness GA for a relative-only dimmer. Suggestions only — a human reviews them, and accepted new GAs feed generate_ets_group_addresses; the server never writes to ETS or the bus. On a real 3646-GA project it produced 145 proposals: 32 set-DPT, 1 change-DPT, and 112 synthesised status GAs.
• A2 — relative-only-dimming detector (analyze.py, relative_only_dimming finding). A 3.007 relative dimmer with no 5.001 absolute-brightness GA in its zone is flagged, because Home Assistant cannot set a brightness level from relative dimming alone.
• A3 — cover invert / travel-time surfacing (generate_ha.py). The cover review reason is now verify_cover_invert and carries a note listing the actuator-dependent flags that are not in the .knxproj (invert_position / invert_updown / invert_angle, travelling_time_up / travelling_time_down), plus a warning when a cover's position lacks a state address.

0.4.0 — 2026-07-01

Two new lint dimensions: does the DPT sub-type match what the name promises, and is the project's KNX Secure posture consistent. This release adds a conservative sub-DPT sanity linter and a report-only KNX Data Secure posture summary (no key material ever touched), plus the itemised QA findings in the handover pack.

Added

• A1 — sub-DPT sanity linter (analyze.py, surfaced by check_dpt and analyze_all as the subdpt_suspect finding). When a group-address name implies a specific DPT sub-type (temperature → 9.001, power → 14.056, brightness/position → 5.001, and similar), the linter flags a wrong sub-type or a wrong main type. Multilingual keyword matching, deliberately conservative — it only fires when the name is unambiguous, so it does not second-guess correct or generic DPTs.
• A4 — KNX Data Secure posture (analyze.py secure_posture(), new MCP tool check_secure). A report-only summary of the project's security posture: secured vs plaintext GA counts, middle groups that mix secure and plaintext objects, and a keyring (.knxkeys) handover checklist. It reads only the per-GA Security flag — no key material is read, derived, or emitted.
• KNX Secure posture section in the handover pack — section 5 of handover.md is rewritten from a flat secure-GA count into the full posture section (counts, mixed-group flag, keyring handover checklist), so the as-built deliverable states the security posture explicitly.
• Itemised QA findings in the handover pack — section 6 of handover.md now lists the actual 🔴 errors and 🟡 warnings (address + name, grouped by check), not just totals, so the handover doubles as a review checklist. Info-level items (intentional reserves / logic / macros) stay collapsed.

0.3.0 — 2026-07-01

Spec→structure: a device library and a design methodology, plus the as-built handover pack. This release turns the tool from a .knxproj validator into a design aid: from a project spec you can now expand each device into its group-address recipe and reason about the whole structure. Shipped alongside the Track B project handover pack and a set of noise-reduction refinements, the latter two driven by a second real signed Zennio project (a 3646-GA multi-vendor villa, 5× larger, no ETS Functions).

Added

• Device library + decompose_device — one device is not one GA (device_library.py, new MCP tools decompose_device + list_device_recipes). Each actuator channel expands into a set of communication objects — command, status, dimming (3.007), absolute value/position (5.001), HVAC mode (20.102/20.105), colour (232.600/251.600) — each with its own DPT. Given a manufacturer order number, device type or alias (e.g. ZDIDBDX4, dimmer, JRA/S, presence detector) and a channel count, the tool returns the objects a professional typically wires per channel and the total GA count, so a spec/ТЗ device list can be turned into a group-address structure. Recipes cover switch, dimmer, RGBW LED, shutter/blind, floor-heating, AC gateway, DALI, presence, metering, leak and touch-panel families across Zennio + ABB. Recipes are generic vendor facts compiled from KNX manufacturer ETS product databases and public documentation — the typical-wired subset, not the full selectable master menu. New regression tests cover the dimmer/shutter/panel/unknown paths.
• docs/spec-to-structure.md — the spec→structure methodology. Documents the reverse of validation (design a group-address structure from a spec), the decompose_device pipeline, and an honest, measured account of what is reproducible from a spec (~90 %: taxonomy, domains, logic structure, command/status pairing, DPT discipline) versus what is not (the exact per-device object count — an integrator parameterisation choice that varies 2–9× between projects; predict a range, never a false-precise number).
• generate_handover_pack — the as-built commissioning deliverable (Track B). From a read-only .knxproj it assembles handover.md (equipment inventory by manufacturer, group-address map by domain, command/status feedback coverage %, KNX Secure scope, QA state), a standalone topology.svg area/line/device diagram, the full group-addresses.csv and the ha-package.yaml. On the villa: 275 devices across 8 manufacturers, 14 domains, 93 % feedback coverage — one command produces the whole handover bundle.
• Divider/separator scratch detection — commissioning placeholder names made only of punctuation (---, =====) or a marker wrapped in it (-----addition------) now classify as scratch intent, so a missing DPT on them is an INFO note, not a 🔴 error.
• Logic-function object awareness — a typed GA (e.g. 9.x temperature) wired into a Zennio [LF] … Data Entry container (intentionally type-agnostic, raw 2-byte) surfaces as INFO dpt_on_logic_object instead of a false dpt_mismatch_co warning.
• Central-macro status tolerance — all-groups broadcast commands (Общее …, Все группы, Все шторы - Стоп) surface as INFO central_macro_no_status instead of a missing_status_address warning, since a fan-out broadcast has no single state to read back.

Fixed

• Handover domain names — the group-address map now reads main/middle range names straight from the project's GroupRanges instead of GARecord.main_name, which the parser could mislabel (a middle range's name leaking into the main). Domains now render correctly (e.g. [1] Освещение 1 этаж, [5] Климат) instead of a middle-group name.

0.2.0 — 2026-06-30

Colour/climate entity assembly and GA-intent noise reduction. Two feature tracks shipped together, both driven by real ETS projects: full colour-light (RGBW/RGB/CCT) and KNX climate entity generation with a status-pairing (B1) correctness fix, and a GA-intent classifier that stops intentional non-functional addresses from raising false errors. On a real 685-GA Zennio project the intent work cut false errors 29 → 6 and missing-status noise 79 → 45 while preserving all 12 genuine dpt_mismatch_co catches.

Added

• Colour lights, climate entities and a status-pairing fix (Track A), driven by the real signed demo and a 685-GA Zennio project.
  • Colour control is assembled into the light entity: RGB (DPT 232.600 → color_address), RGBW (251.600 → rgbw_address), xyY (242.600 → xyy_address) and absolute colour-temperature (7.600 → color_temperature_address + color_temperature_mode), each with its status, matched to the zone's light by identity. A colour GA with no on/off in its zone is routed to review instead of dropped.
  • Climate entities are now generated: anchored on an HVAC mode (DPT 20.102/20.105), the zone's current temperature (9.001), target-temperature status, operation/controller modes and valve command_value_state are gathered by location and emitted only when the HA- required minimum (temperature_address + target_temperature_state_address) is present — otherwise the zone goes to review, so an invalid climate entity is never written. Keys verified against the Home Assistant KNX docs. (Real files: demo 6, Zennio 7 climate zones.)
  • B1 fix — no borrowed status. A command now only takes a status whose identity nests with its own (a shared zone token like "kitchen" is not enough), and a status maps to exactly one entity. This stopped "worktop LED" inheriting "island pendants" brightness and removed all shared-status addresses on the real files.
  • New DPTs: 232.600 / 251.600 / 242.600 / 7.600 (colour), 20.105 (controller mode), 1.100 (heat/cool). New regression tests cover colour assembly, the B1 borrow guard and climate (valid zone emitted, mode-only zone reviewed).
• GA-intent classification — noise reduction on real projects (intent.py). Every group address is now classified as functional / reserve / logic / scratch. Intentional non-functional GAs no longer "cry wolf": reserve spares with no DPT become an INFO note (reserve_without_dpt) instead of a 🔴 error; reserve names repeated across different DPTs are not flagged duplicate_name / inconsistent_dpt; internal logic / virtual signals and scratch leftovers are excluded from missing-status warnings. The dpt_mismatch_co check and every real functional finding are untouched. Driven by a real 685-GA Zennio project where this cut false errors 29 → 6 and missing-status noise 79 → 45 while preserving all 12 real dpt_mismatch_co catches. list_group_addresses, the report inventory and the analyze_all summary now expose the intent breakdown. New regression test covers the reserve / logic / scratch patterns (and proves real DPT + status problems still surface).
• docs/ — a self-contained GitHub Pages landing site (project overview, two-layer architecture, demo-house stats, an interactive 5-tab dashboard preview, the HA "brain", and a call for testers).
• examples/demo-home/ — a complete synthetic worked example: a 239-GA / 47-Function demo .knxproj, the tool's generated report + Home Assistant entities + ETS export, and a ha-brain/ Home Assistant smart layer (circadian lighting, multi-factor climate, presence/ season/time logic, statistics). Includes 5 deliberate mistakes to show the checks (and an honest note on the one the missing-status check doesn't yet catch).

0.1.2 — 2026-06-28

Home Assistant mapping quality — a second hardening pass driven by running the tool against more public ETS 4.2 / 5.0 / 5.5 / 6 projects (yene/knxproj DemoCase, tuxedo0801/KnxProjParser, dataheld/knxray, whaeuser/open-knxviewer). Three new regression tests; zero crashes across the whole corpus.

Added

• Dimmable lights are assembled completely. A light now collects BOTH its on/off status (1.x) and brightness status (5.x) via identity-based pairing, folds the on/off command into the same light entity (no more duplicate switch), and pairs correctly even when the device identity is a single name token (e.g. HaloSpotLeft.A.VALUE ↔ HaloSpotLeft.A.STATE%). Switches gained the same identity-based status pairing.
• Wider shutter detection. A cover's up/down is recognised on canonical DPT 1.008 or any 1.x command named up/down (UP/DOWN, auf/ab); stop is recognised on DPT 1.007 / 1.010 / 1.017 or a "stop"/"stopp"/"стоп" name. Position and stop siblings attach only to the same shutter (zone-identity guard), so multiple blinds in one main group no longer cross-wire. Real ETS4/5 projects that use 1.001+1.017 now map to full covers.
• Date / time / text DPTs recognised (10.001 time, 11.001 date, 19.001 datetime, 16.000/16.001 string): routed to review as manual_datetime / manual_text (HA KNX has dedicated date/time/text platforms) instead of an opaque unmapped_dpt.

0.1.1 — 2026-06-28

Hardening release. Every change below was surfaced by running the tool end-to-end against real ETS5/ETS6 project files (the XKNX/xknxproject test fixtures), not the synthetic smoke test — which alone never exercised the real parser or the MCP server path. Five new regression tests now guard these cases.

Fixed

• Critical: the load_project MCP tool recursed infinitely (RecursionError) on every real .knxproj. The server tool function load_project shadowed the imported project loader of the same name, so it called itself instead of parsing. It now delegates to load_project_file. This made the tool's primary entry point unusable over MCP; the synthetic smoke test missed it because it calls the parser directly, bypassing the server.

Added

• ETS Function role pairing — the headline feature — is now actually implemented. command↔status pairs are taken from ETS Function roles (e.g. SwitchOnOff ↔ InfoOnOff) via pairing.function_status_pairs(), consumed by both check_missing_status and the HA generator. Previously Functions were ignored entirely despite the README claiming they were the primary signal. Consequences fixed: a feedback GA named only "Status" now pairs correctly (name tokens no longer required), HA entities get the right state_address, and function-paired commands are no longer false-flagged as missing a status.
• No silent drops in HA generation ("no silent caps"). Every group address is now either emitted as an entity or listed in the review output; the YAML header reports how many need manual review. Previously, GAs the generator could not classify simply vanished.
• Smarter shutter classification. German/directional names are recognised (Behang, Lamelle, auf/ab, Raffstore, Markise, plus RU equivalents). A shutter-looking command whose DPT lacks a sub-type now gets an actionable shutter_incomplete_dpt review hint (set 1.008 / 1.010 / 5.001 in ETS) instead of being dropped as "unknown".
• Venetian slats handled as tilt. A slat GA (Lamelle / slat / ламель / tilt) is attached to its parent blind cover as move_short_address instead of becoming a standalone cover; an unmatched slat is flagged shutter_slat_unattached for manual attachment.
• Diagnostics alarms are inputs. A 1-bit diagnostics GA (wind/frost/rain/smoke/leak alarm, fault) is now a read-only binary_sensor instead of a phantom command switch.

0.1.0 — 2026-06-28

Initial public beta.

Added

• Design-time MCP server with 12 tools: load_project, list_group_addresses, get_devices, get_topology, check_naming, check_missing_status, check_dpt, analyze_all, generate_ha_package, generate_ets_group_addresses, project_report, workspace_info.
• Read-only .knxproj parsing via xknxproject (ETS5/ETS6, password-protected supported).
• GA classification (category + kind) from DPT and multilingual (EN/DE/RU) name keywords.
• Naming, missing-status, and DPT validation checks.
• Home Assistant KNX YAML generation with a conservative review list for ambiguous items.
• ETS-importable group-address export in XML (knx.org/xml/ga-export/01) and CSV.
• Markdown project report.
• Confined-workspace write guarantee (NICKOL_KNX_WORKSPACE); no bus access by design.
• CLAUDE.md design playbook, end-to-end smoke test (synthetic 16-GA project), example Claude Desktop config.

Known limitations

• Tested end-to-end on a synthetic project only; real-world .knxproj testing is ongoing (see the call for testers in the README).