From ce64250eacf0444f9cc64fce3263678d2af3c42e Mon Sep 17 00:00:00 2001 From: Nikolay1 Date: Wed, 15 Jul 2026 22:04:53 +0200 Subject: [PATCH] docs(readme): align narrative with product (Room Library R1 + shipped roadmap) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Positioning-only sync (tool table untouched): - Intro: 'Three things' → 'Four things' + new bullet 'Compose a new project from parametrised room templates' (dry-run, new projects only, R1). - Add Scenario 4 (compose_rooms → allocation manifest + ETS XML/CSV + device BOM; generated .knxproj re-read by standard loader, 0 errors / 0 warnings; R2 docking + device selection flagged as planned). - Roadmap: reframe check_device_parameters and check_policy as shipped (they are already in the tool table); add Room Library R1 shipped / R2 planned; keep ETS7 Smart Linking note. - Package layout: add room_library.py + room_templates/. - README.ru.md: mirror the intro, Scenario 4 and package-layout edits (ru has no Roadmap section). NOTE: ru tool table still lags at 25 vs EN 30. Co-Authored-By: Claude Opus 4.8 --- README.md | 24 +++++++++++++++++++++--- README.ru.md | 19 ++++++++++++++++++- 2 files changed, 39 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 99b59f7..5134c82 100644 --- a/README.md +++ b/README.md @@ -2,11 +2,12 @@ **A design-time KNX / ETS6 assistant exposed as an [MCP](https://modelcontextprotocol.io) server.** -Three things you can do with it — all **without ever touching the live KNX bus**: +Four things you can do with it — all **without ever touching the live KNX bus**: 1. **Design a project from a spec** — turn an equipment list / project specification into a complete, validated group-address structure **plus the full implementation document set** (ETS-importable XML/CSV, human-readable report, Home Assistant YAML, acceptance test protocol, as-built handover pack). 2. **Audit, repair & finish an existing project** — validate naming · DPT & sub-DPT · command↔status · KNX Secure · Matter-readiness, get **concrete fix proposals** (inferred DPTs, synthesised status GAs), grade completeness, and diff two project versions. 3. **Generate the smart-home layer** — assembled Home Assistant entities (colour lights, climate, covers, sensors) that read *real device state*, with everything ambiguous deferred to human review. +4. **Compose a new project from parametrised room templates** — from a list of rooms (with a `basic`/`comfort` preset per slot) assemble a **new**, validated project → an allocation manifest + ETS GA XML/CSV + a device BOM proposal. Dry-run, new projects only (**R1**). Under the hood: a **device library** that expands each actuator into its real communication objects — from generic recipes up to the **exact vendor object model** parsed straight from ETS application programs. @@ -78,8 +79,9 @@ issue. The tool is read-only and never connects to a bus, so testing is safe (se Recent reviews from practising KNX integrators (in [Discussions](https://github.com/NickoScope/nickol-knx-mcp/discussions)) are steering what comes next: -- **Cross-device parameter consistency** *(feasibility validated by a PoC — not yet a shipped tool)* — flag the one device whose ETS **parameter** settings differ from its N identical siblings: a thermostat with a different setpoint/hysteresis, a presence detector with a different detection time. The PoC extracts per-device parameters straight from the `.knxproj` and finds the odd one out on real 42–275-device projects — read-only, no ETS, no bus — and correctly reports **nothing** on a clean project (no false positives across a different vendor / integrator school). -- **Project Policy Profile** — validate a project against *your own* agreed rules (naming, GA taxonomy, command/status exemptions) instead of one universal "professional standard", since conventions differ per integrator. +- **Cross-device parameter consistency** *(shipped — `check_device_parameters`)* — flag the one device whose ETS **parameter** settings differ from its N identical siblings: a thermostat with a different setpoint/hysteresis, a presence detector with a different detection time. Extracts per-device parameters straight from the `.knxproj` and finds the odd one out on real 42–275-device projects — read-only, no ETS, no bus — and correctly reports **nothing** on a clean project (no false positives across a different vendor / integrator school). +- **Project Policy Profile** *(shipped — `check_policy`)* — validate a project against *your own* agreed rules (naming, GA taxonomy, command/status exemptions) instead of one universal "professional standard", since conventions differ per integrator; with no profile it validates against the taxonomy inferred from the project itself. +- **Room Template Library** — compose a **new** project from parametrised room templates. **R1 shipped** (`compose_rooms` + `validate_room_template`: new projects, dry-run, allocation manifest + ETS XML/CSV + device BOM). **R2 planned**: docking into an existing project + exact device selection. - On **in-ETS group-address linking** we deliberately *don't* reinvent the wheel: for linking GAs to communication objects inside ETS there are already ETS App-Store add-ins today, and native **Smart Linking** is coming in ETS7 — we point you to those and keep our focus on read-only **audit** and an **evidential project model**. Have a project to test, a workflow that breaks, or a feature to shape? → **[Discussions](https://github.com/NickoScope/nickol-knx-mcp/discussions)**. @@ -176,6 +178,20 @@ spec encodes. *after* deploy: a real git history of `/config` (deploy key + pre-commit secret scanner) plus encrypted offsite backups in GitHub Releases, with a monthly restore drill. +### 🧱 Scenario 4 — Compose a new project from room templates + +- **From rooms, not a blank sheet**: pick from six built-in **parametrised room templates** (bedroom, + children, living, kitchen, bathroom, corridor), choose a `basic` / `comfort` preset **per slot** (a house + can mix comfort climate with basic lighting), and `compose_rooms` assembles a **new** project. +- **Out comes**: an allocation `manifest` (main = domain, middle = role, sub sequential), ETS-importable + **GA XML/CSV** via the existing generators, and a **device BOM** proposal from the device library. +- **Validated by the real reader**: the generated `.knxproj` is re-read through the standard `load_project` + — the same path used for third-party projects — and passes all four linters (naming / missing-status / + DPT / policy) with **0 errors / 0 warnings**. +- **Dry-run by default, new projects only.** The template format is a public contract (`room_templates/SCHEMA.md`): + identity is a locale-neutral `slot_id`, never a human name. +- R2: docking into an existing project + exact device selection — planned. + ### 🧩 The foundation — a growing device library - `parse_devices_from_project` extracts **exact vendor object models** — including **ref-level** (`ComObjectRef`) publishers like HDL/Ekinex — from the manufacturer @@ -362,6 +378,8 @@ nickol-knx-mcp/ │ ├── generate_ha.py # Home Assistant KNX YAML generation │ ├── generate_ets.py # ETS XML + CSV generation │ ├── report.py # Markdown report +│ ├── room_library.py # Room Library R1 — compose a new project from templates +│ ├── room_templates/ # built-in room YAML templates + SCHEMA.md (public contract) │ └── server.py # FastMCP server, 30 tools, confined writes ├── tests/test_pipeline.py ├── examples/claude_desktop_config.json diff --git a/README.ru.md b/README.ru.md index 0a8e372..17aaf83 100644 --- a/README.ru.md +++ b/README.ru.md @@ -4,11 +4,12 @@ **Design-time ассистент KNX/ETS6 в виде MCP-сервера.** -Три задачи, которые он решает — **никогда не подключаясь к живой шине KNX**: +Четыре задачи, которые он решает — **никогда не подключаясь к живой шине KNX**: 1. **Спроектировать проект из ТЗ** — превратить спецификацию оборудования в полную валидную структуру групповых адресов **плюс весь комплект документов для реализации** (ETS-импорт XML/CSV, человекочитаемый отчёт, Home Assistant YAML, протокол приёмки, пакет сдачи as-built). 2. **Проверить, починить и довести готовый проект** — валидация (именование · DPT и sub-DPT · команда↔статус · KNX Secure · Matter-готовность), **конкретные предложения фиксов** (вывод DPT, синтез статусных адресов), грейд полноты, семантический дифф двух версий. 3. **Сгенерировать слой умного дома** — собранные сущности Home Assistant (цветной свет, климат, шторы, датчики), читающие *реальное состояние устройств*; всё неоднозначное — на человеческое ревью. +4. **Собрать новый проект из параметризованных шаблонов комнат** — из списка комнат (пресет `basic`/`comfort` на каждый слот) собрать **новый** валидный проект → allocation-манифест + ETS GA XML/CSV + предложение device BOM. Dry-run, только новые проекты (**R1**). Под капотом — **библиотека устройств**, раскладывающая каждый актуатор на его реальные объекты связи: от типовых рецептов до **точной вендорской модели**, распарсенной прямо из application programs ETS. @@ -142,6 +143,20 @@ KNX Community в мае 2026 прямо просит такую интеграц деплоя: настоящая git-история `/config` (deploy key + pre-commit сканер секретов) плюс шифрованные offsite-бэкапы в GitHub Releases и ежемесячный restore drill. +### 🧱 Сценарий 4 — собрать новый проект из шаблонов комнат + +- **Из комнат, а не с чистого листа**: выбрать из шести встроенных **параметризованных шаблонов комнат** + (спальня, детская, гостиная, кухня, ванная, коридор), задать пресет `basic` / `comfort` **на каждый + слот** (дом может сочетать комфорт-климат с базовым светом), и `compose_rooms` собирает **новый** проект. +- **На выходе**: allocation-`manifest` (main = домен, middle = роль, sub последовательно), ETS-импортируемые + **GA XML/CSV** через существующие генераторы и предложение **device BOM** из библиотеки устройств. +- **Проверено штатным ридером**: сгенерированный `.knxproj` перечитывается через штатный `load_project` + — тем же путём, что и сторонние проекты — и проходит все четыре линтера (naming / missing-status / + DPT / policy) при **0 ошибок / 0 предупреждений**. +- **Dry-run по умолчанию, только новые проекты.** Формат шаблона — публичный контракт (`room_templates/SCHEMA.md`): + идентичность задаётся локаль-независимым `slot_id`, а не человеческим именем. +- R2: docking в существующий проект + точный подбор устройств — в планах. + ### 🧩 Фундамент — растущая библиотека устройств - `parse_devices_from_project` извлекает **точные вендорские модели объектов** — включая вендоров с публикацией на **ref-уровне** (`ComObjectRef`): HDL/Ekinex — из application @@ -287,6 +302,8 @@ nickol-knx-mcp/ │ ├── generate_ha.py # генерация HA KNX YAML │ ├── generate_ets.py # генерация ETS XML + CSV │ ├── report.py # Markdown-отчёт +│ ├── room_library.py # Room Library R1 — сборка нового проекта из шаблонов +│ ├── room_templates/ # YAML-шаблоны комнат + SCHEMA.md (публичный контракт) │ └── server.py # FastMCP сервер, 25 инструментов, confined writes ├── tests/test_pipeline.py ├── examples/claude_desktop_config.json