mirror of
https://github.com/NickoScope/nickol-knx-mcp.git
synced 2026-09-29 19:31:12 +02:00
Nikolay MiroshnichenkoandClaude Opus 4.8
bba8befcde
Design-time MCP server that reads .knxproj (read-only), validates naming/DPT/status, and generates Home Assistant KNX YAML + ETS-importable group addresses (XML/CSV). No live bus access — confined-workspace writes only. Includes: 12 MCP tools, end-to-end smoke test, MIT license, English-first README (+ Russian), CONTRIBUTING with a real-project test call, SECURITY policy, CHANGELOG, GitHub Actions CI (Python 3.10–3.12), and issue/PR templates. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
71 lines
3.6 KiB
Markdown
71 lines
3.6 KiB
Markdown
# ETS / KNX Assistant — project rules
|
|
|
|
This file is the design playbook for working on this KNX project with the
|
|
`nickol-knx` MCP server. Claude Code loads it automatically as project context.
|
|
Apply these rules when reading the `.knxproj`, generating Home Assistant config,
|
|
or producing ETS group-address exports.
|
|
|
|
## Hard safety rules
|
|
- **Never** propose writing to a live KNX bus. The `nickol-knx` server has no bus
|
|
access; keep it that way. Live control happens only through the Home Assistant
|
|
layer, and only when the user explicitly asks.
|
|
- **Always** generate a Markdown report (`project_report`) and let the user read
|
|
it **before** any import into ETS or deploy into Home Assistant.
|
|
- All generated files go into the Git-tracked workspace. Commit before and after
|
|
changes so every step is reversible.
|
|
|
|
## Two-layer architecture
|
|
- **KNX (ETS)** owns foundational logic and runs autonomously. The integrator
|
|
programs it. Treat the `.knxproj` as the source of truth for addresses + DPTs.
|
|
- **Home Assistant** is the upper smart layer (automations, templates). HA must
|
|
read *real device state*, never assume it.
|
|
|
|
## Group address structure (3-level Main/Middle/Sub)
|
|
- Main group = function domain. Suggested split:
|
|
`0 Central/Scenes · 1 Lighting · 2 Shutters/Blinds · 3 HVAC · 4 Sensors ·
|
|
5 Energy · 6 Diagnostics · 7 Reserve`.
|
|
- Middle group = sub-function or zone (e.g. Switch / Dimming / Status / Position).
|
|
- Keep **commands and status in distinct, predictable middle groups** (e.g.
|
|
command in `.../0/...`, feedback in `.../4/...`). The pairing engine matches by
|
|
name tokens, so consistent naming matters more than adjacency.
|
|
- Reserve address space in every range; never pack ranges 100%.
|
|
|
|
## Command / status pairs (the most important rule)
|
|
- **Every controllable actuator must have a status object.** A switch needs a
|
|
state GA; a dimmer needs a brightness-state GA; a blind needs position + position
|
|
state. `check_missing_status` flags anything without one.
|
|
- HA entities must have a `state_address` (or `*_state_address`) wherever the KNX
|
|
device can report it. No status = HA shows stale/guessed state.
|
|
|
|
## DPT discipline
|
|
- Every GA must have a DPT set. Missing DPT is a hard error (`check_dpt`): HA
|
|
cannot decode it.
|
|
- Same logical name → same DPT. Inconsistent DPTs across same-named GAs are a bug.
|
|
- Common DPTs: switch `1.001`, status `1.011`, up/down `1.008`, stop `1.010`,
|
|
dimming `3.007`, brightness/position `5.001`, temperature `9.001`, humidity
|
|
`9.007`, CO₂/ppm `9.008`, lux `9.004`, energy kWh `13.013`, power W `14.056`,
|
|
scene `17.001`/`18.001`, HVAC mode `20.102`.
|
|
|
|
## Naming
|
|
- Names encode **zone + function** (e.g. "Kitchen ceiling light switch",
|
|
"Bedroom blind position status"). The status keyword (`status`/`state`/`статус`/
|
|
`Rückmeldung`) is what lets the engine pair feedback to its command.
|
|
- No empty names, no duplicates. Main and middle ranges get descriptive names.
|
|
|
|
## Category separation
|
|
Keep these domains in their own ranges and HA platforms: lighting, dimming,
|
|
shutters, HVAC, sensors, scenes, energy, diagnostics.
|
|
|
|
## KNX Secure
|
|
- When KNX Data Secure / IP Secure is enabled, secure tunneling needs the **ETS
|
|
Keyring export** (`.knxkeys`). Exports from this tool carry the `Security` flag
|
|
per GA; the keyring itself is handled in ETS/HA, never by this server.
|
|
|
|
## Typical workflow
|
|
1. `load_project` the `.knxproj`.
|
|
2. `analyze_all` → fix 🔴 errors in ETS, add missing status GAs.
|
|
3. `project_report` → human review.
|
|
4. `generate_ets_group_addresses` (xml) → import into ETS for any new GAs.
|
|
5. `generate_ha_package` → review YAML → deploy to Home Assistant.
|
|
6. Commit every artifact to Git.
|