knx-xml-context

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)

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)

ID Format Rules

Hardware Mandatory Attributes

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

Character Encoding in IDs

DatapointType & ObjectSize Formats

<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

python validate_knx_comprehensive.py my_device.xml

Output:

✓ 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

<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

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

ID Naming & Consistency (Golden Rule)

• ✅ Use numeric suffixes: _P-1, _O-2, _R-3
• ✅ Deep Referential Integrity: Cross-check every RefId, ParameterType, and ParamRefId.
• ❌ Avoid text suffixes: _P-Button, _O-Switch
• ⚠️ Zero Typo Risk: Even a single extra 0 in a reference suffix (e.g., 00001 vs 000001) will trigger a "Sequence contains no matching element" crash in ETS/Kaenx.

Hardware2ProgramRefId Format

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

Troubleshooting

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

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