KNX XML Development Context

This skill provides instant context for KNX XML development, including validation rules, crash points, and optimization best practices from Kaenx Creator source code analysis.

When to Use This Skill

•Load context for KNX XML development in new conversations
•Check validation rules before importing to Kaenx Creator
•Design Dynamic sections for ETS UI
•Debug import errors in Kaenx Creator
•Create or modify .knxprod files
•NOT for general XML editing (use standard XML tools)

Prerequisites

•Python 3.x (for validation script)
•Access to POC_KNX_XML_Source/ directory

How to Use

Step 1: Load Context

Simply mention "knx context" or "knx validation" in your message, and this skill will be activated.

Step 2: Reference Quick Cards

Use the quick reference cards below for common validation rules.

Step 3: Run Validation (Optional)

bash

python POC_KNX_XML_Source/Validate_Tool/validate_knx_comprehensive.py <xml_file>

Step 4: Consult Strict Rules

Always check: POC_KNX_XML_Source/XML_Import_Rule/Rule.md

Quick Reference Cards

Critical Crash Points (Must Avoid)

Issue	Requirement	Error Type
`Hardware.VersionNumber`	Must exist (NOT `Version`)	NullReferenceException
`Hardware2ProgramRefId` suffix	≥13 chars after `_HP-`	ArgumentOutOfRangeException
All ID suffixes	Must be numeric only	FormatException
`Manufacturer.RefId`	≥3 characters	OutOfRangeException
`RefId` duplicates	Must be UNIQUE globally	Import Error (Nicht eindeutig)
OrderNumber	Alphanumeric only (no special chars)	Encoding Warning

ID Format Rules

Element	Offset	Valid Example	Invalid Example
Parameter	2	`..._P-123`	`..._P-Btn1` ❌
ParameterRef	2	`..._R-456`	`..._R-Mode` ❌
ComObject	0	`..._O-1`	`..._O-Switch` ❌
ModuleDef	3	`..._MD-1`	`..._MD-Main` ❌
ParameterBlock	3	`..._PB-1`	`..._PB-Config` ❌

Hardware Mandatory Attributes

xml

<Hardware 
    Name="DeviceName"
    SerialNumber="1234567890"
    VersionNumber="1"             <!-- MANDATORY -->
    BusCurrent="10"               <!-- MANDATORY -->
    HasIndividualAddress="true"   <!-- MANDATORY -->
    HasApplicationProgram="true"  <!-- MANDATORY -->
/>

Character Encoding in IDs

Char	Encoded	Char	Encoded
`-`	`.2D`	`.`	`.2E`
	`.20`	`/`	`.2F`
`+`	`.2B`	`,`	`.2C`

DatapointType & ObjectSize Formats

xml

<ComObject DatapointType="DPST-1-1" />  <!-- Switch On/Off -->
<ComObject DatapointType="DPT-9" />      <!-- 2-Byte Float -->
<ComObject ObjectSize="1 Bit" />
<ComObject ObjectSize="2 Bytes" />

Examples

Example 1: Validate Before Import

bash

python validate_knx_comprehensive.py my_device.xml

Output:

code

✓ PASSED (12): XML syntax, Hardware.VersionNumber...
⚠️ WARNINGS (2): Missing BusCurrent...
❌ ERRORS (1): Parameter ID has non-numeric suffix
RESULT: FAIL - 1 error(s) will cause import failure

Example 2: Dynamic Section with Master Switch

xml

<Channel Name="Channel 1" Number="1">
    <ParameterBlock Id="PB-1" Name="CH1_Config">
        <ParameterRefRef RefId="P_CH1_Mode_Ref" />
        <choose ParamRefId="P_CH1_Mode_Ref">
            <when test="0" />  <!-- Disabled: empty -->
            <when test="1">    <!-- Switch Mode -->
                <ParameterRefRef RefId="P_Switch_Delay_Ref" />
                <ComObjectRefRef RefId="O_Switch_Ref" />
            </when>
        </choose>
    </ParameterBlock>
</Channel>

Best Practices

5 Golden Rules for Dynamic Section

•Default to Hidden: Always wrap refs in <choose><when>
•Master Switch Pattern: Every block starts with Enum, value 0 = Disabled
•Nesting is King: Use nested <choose> for hierarchical UI
•Use Comparison Operators: test="<3", test=">0" for flexible conditions
•Conflict Prevention: Check GPIO state before showing options

ID Naming Convention

•✅ Use numeric suffixes: _P-1, _O-2, _R-3
•❌ Avoid text suffixes: _P-Button, _O-Switch

Hardware2ProgramRefId Format

code

✅ ..._HP-0000-00-00001   (13 chars after _HP-)
❌ ..._HP-1-1-1           (5 chars - CRASH!)

Troubleshooting

Error Message	Root Cause	Solution
Unknown Error (Crash)	NullReference or OutOfRange	Check Hardware.VersionNumber exists
Input string was not in correct format	Non-numeric ID suffix	Rename IDs to use numbers only
Sequence contains no matching element	Missing reference	Verify CatalogItem contains encoded OrderNumber
Index outside bounds	String too short	Pad Hardware2ProgramRefId to 13+ chars

Resources

For detailed documentation, see:

•Validation Specification - Full 46+ crash points
•Python Validator - Automated validation script
•Optimization Guide - Best practices with case study

Workflow Summary

code

1. Design XML    → Follow Optimization Guide
2. Validate      → Run Python script
3. Import        → Kaenx Creator
4. Export        → .knxprod file
5. Test          → ETS