diff --git a/README.md b/README.md index a3b5d5f..918f9ae 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,7 @@ It reads your `.knxproj`, analyzes group addresses / DPTs / topology, generates [![Live demo](https://img.shields.io/badge/live%20demo-online-brightgreen?logo=homeassistant&logoColor=white)](https://nickoscope.github.io/nickol-knx-mcp/) [![Join the discussion](https://img.shields.io/badge/💬_join_the-discussion-8957e5?logo=github&logoColor=white)](https://github.com/NickoScope/nickol-knx-mcp/discussions/1) [![nickol-knx-mcp MCP server](https://glama.ai/mcp/servers/NickoScope/nickol-knx-mcp/badges/score.svg)](https://glama.ai/mcp/servers/NickoScope/nickol-knx-mcp) +[![Case study](https://img.shields.io/badge/📐_case_study-spec_PDF_→_KNX_(96%25)-0b3d2e)](docs/case-study.md) 🇷🇺 **Русская версия:** [README.ru.md](README.ru.md) diff --git a/README.ru.md b/README.ru.md index 03f72b4..b1d41ee 100644 --- a/README.ru.md +++ b/README.ru.md @@ -6,6 +6,7 @@ Читает `.knxproj`, анализирует group addresses / DPT / топологию, генерирует Home Assistant KNX YAML и ETS-импортируемые group-address файлы (XML/CSV), делает человекочитаемые отчёты — **никогда не подключаясь к живой шине KNX.** [![nickol-knx-mcp MCP server](https://glama.ai/mcp/servers/NickoScope/nickol-knx-mcp/badges/score.svg)](https://glama.ai/mcp/servers/NickoScope/nickol-knx-mcp) +[![Кейс](https://img.shields.io/badge/📐_кейс-ТЗ_PDF_→_KNX_(96%25)-0b3d2e)](docs/case-study.ru.md) > ⚠️ **Статус: BETA.** Сервис проверен на синтетическом проекте (16 GA) и проходит end-to-end тест, но **на реальных `.knxproj` пока тестировался ограниченно**. Нужны тестировщики — см. [CONTRIBUTING.md](CONTRIBUTING.md). > diff --git a/docs/case-study.md b/docs/case-study.md new file mode 100644 index 0000000..d297add --- /dev/null +++ b/docs/case-study.md @@ -0,0 +1,55 @@ +# Case study — from a spec PDF to a validated 662-GA KNX structure, in minutes + +🇷🇺 **Русская версия:** [case-study.ru.md](case-study.ru.md) + +## The question +How far can a project **specification alone** be turned into a finished, standards-correct KNX +group-address structure — and how close would it get to professional work? + +## Input +A real residential project — **14 rooms (~155 m²)**, Zennio-based: switched + dimmed lighting, +electric underfloor heating, ventilation with heat recovery, motorised curtains, +water / electricity / heat metering, leak & fire safety — described **only in a 42-page technical +specification (PDF)**. No group addresses, no DPTs, no naming were given: the spec lists equipment +and functions, not a KNX structure. + +## The workflow +``` +spec PDF + │ an AI assistant, grounded in the KNX Association standard + industry practice, + ▼ DESIGNS the full group-address structure +GA structure (taxonomy · naming · DPTs · command/status pairs · scenes · reserves) + │ nickol-knx-mcp VALIDATES it and GENERATES the outputs + ▼ +Home Assistant package + ETS-importable group-address XML +``` + +## Output +- **662 group addresses** across **10 functional domains**, as a `ga-export/01` XML ready for ETS + *Import Group Addresses* → place devices → export `.knxproj`. +- Produced in **minutes**. + +## The check — against a professional reference implementation of the same project +| Metric | Result | +|---|---| +| Structural match | **96 %** (662 vs 687 GA) | +| Domain taxonomy | **10 / 10 identical** | +| Address names | **118 byte-identical**, 68 % with a close analog | +| DPT discipline | exact sub-types throughout; DPT 5.001 ≈ 1 : 1 | +| Validation (nickol-knx-mcp) | **0 errors**; reserve / logic noise auto-classified | +| Home Assistant | **9 climate zones · 11 shutters · 12 dimmers** + sensors, generated directly | + +## What it shows +The standardised, time-consuming **"skeleton"** of a KNX project — the part defined by the standard +and the equipment — can be auto-designed to **near-professional quality in minutes, vs the days** of +manual group-address work. That frees the engineer's time for the genuinely creative part: the +project-specific logic, which stays the engineer's craft (the residual few % are exactly those +one-off logic functions). + +## Honesty notes +- **No client data or project files are shared.** The reference implementation is used only as an + anonymous benchmark; the case study reports parameters and match figures, nothing identifying. +- The **design** is produced by an AI assistant grounded in KNX knowledge (the KNX Association + standard + broad industry practice). **nickol-knx-mcp's role** is read-only validation and + Home Assistant / ETS export — it never connects to a live bus. +- Figures are from a structure that actually passed the tool's own checks (0 errors). diff --git a/docs/case-study.ru.md b/docs/case-study.ru.md new file mode 100644 index 0000000..489a00b --- /dev/null +++ b/docs/case-study.ru.md @@ -0,0 +1,54 @@ +# Кейс — из PDF-ТЗ в выверенную KNX-структуру на 662 GA, за минуты + +> 🌍 **English version:** [case-study.md](case-study.md) + +## Вопрос +Насколько далеко можно **из одного ТЗ** получить готовую, корректную по стандарту KNX-структуру +групповых адресов — и насколько близко к работе профессионала? + +## Вход +Реальный жилой проект — **14 помещений (~155 м²)**, на оборудовании Zennio: коммутируемый и +диммируемый свет, электрический тёплый пол, вентиляция с рекуперацией, моторизованные шторы, +учёт воды / электро / тепла, протечки и пожарная безопасность — описан **только в 42-страничном +ТЗ (PDF)**. Ни группадресов, ни DPT, ни нейминга в ТЗ нет: там оборудование и функции, не KNX-структура. + +## Конвейер +``` +PDF-ТЗ + │ AI-ассистент, опираясь на стандарт KNX Association + мировую практику, + ▼ ПРОЕКТИРУЕТ полную структуру групповых адресов +GA-структура (таксономия · нейминг · DPT · пары команда/статус · сцены · резервы) + │ nickol-knx-mcp ВАЛИДИРУЕТ её и ГЕНЕРИРУЕТ выходные файлы + ▼ +пакет Home Assistant + ETS-импортируемый XML групповых адресов +``` + +## Выход +- **662 групповых адреса** в **10 функциональных доменах**, как `ga-export/01` XML, готовый для ETS + *Import Group Addresses* → размещение устройств → экспорт `.knxproj`. +- Получено за **минуты**. + +## Сверка — с профессиональной эталонной реализацией того же объекта +| Метрика | Результат | +|---|---| +| Структурное совпадение | **96 %** (662 против 687 GA) | +| Таксономия доменов | **10 из 10 совпали** | +| Имена адресов | **118 дословных**, 68 % с близким аналогом | +| DPT-дисциплина | точные под-типы у всех; DPT 5.001 ≈ 1 : 1 | +| Валидация (nickol-knx-mcp) | **0 ошибок**; шум (резервы/логика) распознан автоматически | +| Home Assistant | **9 климат-зон · 11 штор · 12 диммеров** + датчики, собраны сразу | + +## Что это показывает +Стандартизованный и трудоёмкий **«скелет»** KNX-проекта — то, что определяется стандартом и +оборудованием — проектируется автоматически до **почти профессионального уровня за минуты против +дней** ручной работы с группадресами. Это освобождает время инженера для по-настоящему творческой +части — проектной логики, которая остаётся его ремеслом (оставшиеся проценты — ровно эти одноразовые +логические функции). + +## Честные оговорки +- **Никакие клиентские данные и файлы проектов не публикуются.** Эталонная реализация используется + только как анонимный ориентир; в кейсе — параметры и проценты совпадения, ничего идентифицирующего. +- **Проектирование** выполняет AI-ассистент, заземлённый на знания KNX (стандарт KNX Association + + мировая практика). **Роль nickol-knx-mcp** — валидация только на чтение и экспорт в Home Assistant / + ETS; к живой шине он не подключается. +- Цифры — со структуры, которая реально прошла проверки инструмента (0 ошибок).