About KNX2HOME
Understanding KNX project file parsing
What does KNX2HOME do?
KNX2HOME is a tool that analyzes KNX project files (.knxproj) and automatically generates Home Assistant configurations. The goal is to speed up and simplify the manual configuration of KNX devices in Home Assistant.
Why is parsing complex?
1. Gap between standard and practice
While KNX is a standardized protocol, the standardization primarily covers data types (DPT). The semantic meaning of group addresses must be inferred from metadata, naming conventions, and address structure - all of which vary by project.
2. Inconsistent metadata
KNX project files are configured using ETS (Engineering Tool Software), but the quality and completeness of metadata depends on:
- The integrator who created the project
- What naming conventions they use
- Whether they properly linked device channels and com objects
- Whether DPT types are filled in for group addresses
3. Implicit relationships
KNX group addresses are flat - there's no explicit structure that says "these 3 addresses form one light entity". KNX2HOME must infer this through:
- Device channel analysis (most reliable)
- LA-prefix patterns (e.g., "LA01 on", "LA01 dim")
- Address ranges (e.g., 1/1/x for lights)
- Suffix patterns (e.g., "Lamp s", "Lamp d", "Lamp w")
- Name-based aggregation for complex structured names
Multi-strategy approach
To properly parse different project files, KNX2HOME uses multiple strategies in order of reliability:
- Structured Mapping (Device Channels) - Most reliable. Uses device topology and channel definitions from ETS.
- Link-driven Aggregation - Uses explicit links between com objects and group addresses.
- LA-Pattern Aggregation - Recognizes "LA01", "LA02" patterns with suffixes like " on", " off", " dim".
- Address-based Aggregation - Groups addresses within the same address range (e.g., 1/1/0-2 for one light).
- Name-based Aggregation - Matches complex names like "Physics 0.01 s", "Physics 0.01 d", "Physics 0.01 w".
- Heuristics - Last fallback: classification based on DPT type, name keywords, and address patterns.
Important notice about reliability
KNX2HOME is a tool, not a replacement for manual verification.
Our tests and validation show a classification accuracy of approximately ~95% for well-structured KNX projects. This means that:
- Most entities are correctly classified (light, switch, sensor, etc.)
- There may always be some edge cases that require manual adjustment
- Projects with inconsistent naming or incomplete metadata may require more manual work
- Complex configurations (such as RGB lights, HVAC systems) may not be fully automatically recognized
⚠️ Always verify the generated configuration before using it in production!
Tips for better results
- Use clear names in ETS - Descriptive names like "Living Room Light" work better than "LA01".
- Fill in DPT types - This greatly helps with correct classification.
- Structure with channels - Use device channels to group related group addresses.
- Use user hints - You can use `[switch]`, `[light]`, `[sensor]`, etc. in names to force classification.
- Use the entity configurator - In the tool, you can adjust entities, rename, or remove them before exporting.
Technical details
Supported DPT types:
- • DPT 1.x (Boolean) - Switches, binary sensors
- • DPT 3.7 (Dimming) - Light dimming control
- • DPT 5.x (8-bit) - Brightness, angles, percentages
- • DPT 9.x (Float) - Temperature, humidity, pressure
- • DPT 10/11/19 - Time, date, datetime
- • DPT 17/18 (Scene) - Scene triggers
- • DPT 20.x - HVAC modes, delays
Supported entities:
- • Switches (on/off control)
- • Lights (with brightness/dimming)
- • Binary Sensors (read-only booleans)
- • Sensors (temperature, humidity, etc.)
- • Covers (blinds, shutters)
- • Scenes (scene activation)
- • Time/Date/DateTime entities
Open Source
KNX2HOME is open source software. Contributions, bug reports, and feature requests are welcome!
View on GitHub