¶ KNX Configuration UI
¶ User Guide
¶ A comprehensive web-based interface for configuring KNX entities in Home Assistant
Table of Contents
- Getting Started
- Navigation Overview
- Entity Types
- Adding Entities - Long Form
- Quick Entry Table
- Importing from CSV
- KNX Address Format
- Validation & Home Assistant Integration
- Backup & Restore
- Import from YAML
- Tips & Best Practices
- Troubleshooting
¶ 1. Getting Started
Access the KNX Configuration UI through your browser:
- Direct URL: http://<device-ip>:10111/
- Via NGINX: http://<device-ip>/knx-ui/
The interface provides a dark-themed, responsive dashboard for managing all your KNX entities.
Main dashboard showing the Light entity list
¶ 2. Navigation Overview
The sidebar navigation provides quick access to all entity types and features:
Sidebar navigation menu
¶ Main Sections:
- KNX Entities - Configure individual device types
- Light, Cover, Climate (includes Fans), Weather
- Sensor, Binary Sensor, Scene, Button
- Expose, Select, Number, Notify
- Bulk Import - Quick Entry Table and CSV import
- Backup & Restore - Configuration management
- System Controls - Restart Home Assistant / KNX Server
¶ 3. Entity Types
|
Entity Type |
Description |
Common Use Cases |
| Light | Switching and dimming lights | Ceiling lights, lamps, LED strips |
| Cover | Blinds, shutters, curtains | Window blinds, roller shutters |
| Climate | Temperature control | Thermostats, heating/cooling |
| Fan | Fan speed control | Ceiling fans, ventilation |
| Sensor | Numeric sensor values | Temperature, humidity, brightness |
| Binary Sensor | On/Off state sensors | Motion, presence, door contacts |
| Scene | Pre-configured scenes | "Movie mode", "Good night" |
| Button | One-shot triggers | Doorbell, panic button |
| Expose | Expose HA entities to KNX | Share HA data with KNX |
| Select | Multi-option selection | HVAC modes, presets |
| Number | Numeric value control | Setpoints, levels |
| Notify | KNX notifications | Display messages |
¶ 4. Adding Entities - Long Form
The long form provides full control over all entity options. Use this when you need to configure advanced settings.
¶ 4.1 Adding a Light
- Navigate to Light in the sidebar
- Click the green + ADD button
- Fill in the required fields
- Click Save to add the entity
- When Done, Click on Validate Configuration. This will validate and write the file. If you’re done, you click on Restart Home Assistant and the changes will be finalized. Otherwise Continue Editing. Validate Configuration when done with the lighting section.
Empty light creation form
¶ Required Fields:
- Name: Descriptive name (e.g., 'Living Room Main Light')
- Address: KNX group address for switching (e.g., 1/0/1)
¶ Optional Fields:
- State Address: Feedback address for light state
- Brightness Address: For dimmable lights
- Color/RGBW Address: For color-changing lights
Light form with example data filled in
¶ 4.2 Adding a Climate Controller
- Navigate to Climate in the sidebar
- Click + ADD
- Select the climate type from the dropdown
Climate controller creation form
¶ Climate Types:
- Climate with On/Off Address
- Climate with Controller Mode
- Climate with Controller Mode (Text)
¶ 4.3 Adding a Fan
Fans are configured under the Climate section with a special type.
- Navigate to Climate in the sidebar
- Click + ADD
- Select "Fan With 2 Byte Address" or "Fan With 1 Byte Address"
[Screenshot: 08-fan-form.png]
Fan configuration form
¶ Fan Fields:
- Name: Fan name
- Address: Speed control address
- State Address: Current speed feedback
- Max Step: Maximum speed level (for step-based fans)
¶ 4.4 Adding a Cover (Blinds/Shutters)
- Navigate to Cover in the sidebar
- Click + ADD
¶ Common Fields:
- Name: Cover name
- Move Long Address: Up/Down movement
- Move Short Address: Step movement
- Stop Address: Stop command
- Position Address: Position control (0-100%)
- Position State Address: Current position feedback
¶ 5. Quick Entry Table
For adding multiple entities quickly, use the Quick Entry Table feature.
- Navigate to Bulk Import in the sidebar
- Click Quick Entry Table
- Select the entity type tab (Light, Cover, Climate, Fan, etc.)
- Click + Add Row to add new entries
- You will see an error message with the required fields
- As you fill them in, tab over to the next field and the errors will automatically resolve. When you have all the required fields filled in, the Import All button will highlight.
- Fill in the name and address for each entity
- Click Validate & Import to save all entities
Quick Entry Table with type selection tabs
¶ Quick Entry Features:
- Type Selection: Choose entity type via tabs
- Bulk Add: Add multiple rows at once
- Validation: Real-time address validation
- Delete Rows: Remove unwanted entries before import
¶ 6. Importing from CSV
For large-scale imports, use CSV files.
CSV drag-and-drop upload area
¶ CSV Format
The CSV must include headers matching the entity fields:
¶ For Lights:
name,address,state_address
Living Room Light,1/0/1,1/0/2
Kitchen Light,1/0/3,1/0/4
¶ For Covers:
name,move_long_address,stop_address,position_address
Bedroom Blinds,2/0/1,2/0/2,2/0/3
¶ For Climate:
name,on_off_address,temperature_address,target_temperature_address
Main Thermostat,3/0/1,3/0/2,3/0/3
¶ Import Steps:
- Browse and Find your CSV file from the Browse Button
- Review the parsed data in the preview table
- Fix any validation errors (shown in red)
- Click Validate & Import
¶ 7. KNX Address Format
KNX group addresses must follow the standard 3-level format:
¶ Valid Format:
Main/Middle/Sub
¶ Examples:
- 1/0/1 - Light switching
- 1/0/2 - Light dimming
- 2/1/5 - Cover position
- 3/2/10 - Climate setpoint
¶ Address Ranges:
|
Level |
Range |
Description |
| Main | 0-31 | Main group |
| Middle | 0-7 | Middle group |
| Sub | 0-255 | Sub address |
¶ Tips for Address Entry:
- Use forward slashes / as separators
- No spaces in addresses
- Addresses are validated in real-time
- Invalid addresses show red error highlighting
- Start the first field with a leading 0 and the system will automatically add the slashes / .
¶ 8. Validation & Home Assistant Integration
When you save entities, the system performs multi-level validation:
¶ Validation Levels:
¶ 1. Frontend Validation
- Checks required fields are filled
- Validates address format
- Shows errors immediately in the form
¶ 2. Backend Validation
- Generates YAML configuration
- Verifies YAML syntax is correct
¶ 3. Home Assistant Validation
- Sends configuration to Home Assistant
- HA validates against its KNX schema
- Reports any integration errors
¶ Atomic Operations
All save operations use an atomic backup-validate-commit pattern:
- Backup current configuration
- Apply changes
- Validate with Home Assistant
- If successful: Commit changes
- If failed: Rollback to backup
This ensures your configuration is never left in a broken state.
¶ Restarting Services
After making changes, you may need to restart services:
- Restart Home Assistant: Reloads all integrations and applies new YAML
- Restart KNX Server: Restarts the configuration UI backend
¶ 9. Backup & Restore
The Backup & Restore page provides configuration management features.
Backup & Restore management page
¶ Create Backup
Click Create Backup to save the current configuration. Backups are timestamped automatically.
Backup created successfully
¶ Restore from Backup
- Find the backup in the list
- Click the Restore button
- Confirm the restore operation
- The system will regenerate all YAML files
¶ Download/Upload Configuration
- Download: Export configuration as JSON file
- Upload: Import configuration from JSON file
¶ Factory Reset
WARNING: This will delete ALL entity configurations!
- Click Factory Reset
- Type "RESET" to confirm
- All entities will be removed
Factory Reset confirmation dialog
¶ 10. Import from YAML
If you've manually edited the Home Assistant YAML files, you can sync those changes back to the UI.
- Go to Backup & Restore
- Click Import from YAML
Import from YAML confirmation dialog
¶ This will:
- Read all knx_*.yaml files from Home Assistant
- Parse the YAML configuration
- Convert to JSON format
- Overwrite the current data file
Note: A backup is automatically created before importing.
¶ 11. Tips & Best Practices
¶ Address Organization
Organize your KNX addresses by function:
1/x/x - Lighting
2/x/x - Covers/Blinds
3/x/x - Climate
4/x/x - Sensors
5/x/x - Scenes
¶ Naming Conventions
Use consistent naming for easier management:
[Room] [Device Type] [Number]
Examples:
- Living Room Ceiling Light
- Bedroom Blinds Left
- Kitchen Temperature Sensor
¶ Bulk Operations
- Use Quick Entry Table for adding 5-20 entities
- Use CSV Import for 20+ entities
- Use Long Form for entities needing advanced options
¶ State Addresses
Always configure state addresses when available:
- Provides feedback on actual device state
- Enables proper status display in Home Assistant
- Required for some automations
¶ Testing Changes
After adding entities:
- Restart Home Assistant to load new configuration
- Check the Home Assistant Developer Tools > States
- Verify entities appear with correct names
- Test basic operations (on/off, up/down)
¶ 12. Troubleshooting
¶ Entity Not Appearing in Home Assistant
- Check if YAML was generated: Look in /homeassistant/knx/ for knx_*.yaml files
- Restart Home Assistant after adding entities
- Check Home Assistant logs for YAML errors
- Verify addresses are valid and not duplicated
¶ Validation Errors
¶ "Invalid address format"
- Ensure format is X/X/X with valid ranges
- No spaces or special characters
¶ "Duplicate address"
- Each group address should only be used once per function
- Check if address is already used by another entity
¶ "Home Assistant validation failed"
- Check HA logs for detailed error message
- Verify HA KNX integration is installed
- Ensure KNX gateway is configured
¶ Configuration Not Saving
- Check browser console for errors
- Verify network connection to device
- Check KNX server is running: systemctl status knx-server
- Check server logs for errors
¶ Rollback After Error
If changes cause issues:
- Go to Backup & Restore
- Find the latest working backup
- Click Restore
- Restart Home Assistant
Version Information
- KNX Configuration UI: v1.0
- Supported Home Assistant: 2024.1+
- Supported KNX Integration: Built-in HA KNX
For issues and feature requests, contact your system administrator.