nickol-knx-mcp/CLAUDE.md

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.