KNX to OpenHAB Generator

A powerful tool to generate complete OpenHAB configurations (Items, Things, Sitemaps) directly from your ETS project export (.knxproj) or JSON dump.

It includes a Web UI for easy management, file uploads, and monitoring, as well as a CLI for automated workflows.

Features

• Automated Generation: Creates Things, Items, and Sitemaps automatically.
• Smart Detection: Identifies Dimmers, Rollershutters, and Thermostats based on DPT and naming.
• ETS Integration: Reads .knxproj files directly.
• Web Interface: Browser-based UI to upload projects and monitor generation (great for Raspberry Pi).
• Semantic Model: Automatically tags items for OpenHAB's model.
• InfluxDB Support: Auto-configure persistence via ETS description tags.

Documentation

• User Guide: Configuration, ETS preparation, Logic, and Troubleshooting.
• Production Guide: Installation on Raspberry Pi/DietPi (Service, Systemd).
• Developer Guide: Architecture, Testing, and Local Development.
• Technical Debt Tracking: Current technical debt and improvement plans.
• Refactoring Cleanup: Detailed analysis of project structure cleanup.

---

Quick Start (Installation)

One-Command Installer (Linux / Raspberry Pi)

Ideally use a fresh install of Raspberry Pi OS (Lite) or DietPi.

curl -sSL https://raw.githubusercontent.com/diddip21/knx_to_openhab/main/scripts/install.sh | bash

This will:

1. Install system dependencies (Python, git, etc.)
2. Clone the repository to /opt/knx_to_openhab
3. Set up the knxohui service (Web UI)
4. Configure permissions for self-updates

Uninstallation

curl -sSL https://raw.githubusercontent.com/diddip21/knx_to_openhab/main/scripts/uninstall.sh | bash

How to Use

1. Open the Web UI: Browser to http://<your-ip>:8085.
   • User: admin
   • Password: logihome (Change this in Settings!)
2. Upload Project: Upload your .knxproj export or JSON dump.
3. Configure: Go to Settings to map DPTs or adjust naming rules.
4. Generate: The system automatically generates Items, Things, and Sitemaps.
5. Update: Click the Version badge in the header to check for and apply updates.

---

📁 Project Structure

The project is organized into the following directories:

knx_to_openhab/
├── config.json              # Main configuration file
├── config.py                # Configuration loader
├── ets_to_openhab.py        # Core OpenHAB generation logic
├── knxproject_to_openhab.py # KNX project parser
├── utils.py                 # DPT utility functions
├── docker/                  # Docker test configurations
│   ├── test.Dockerfile
│   └── test-install.Dockerfile
├── docs/                    # Documentation
│   ├── DEVELOPER_GUIDE.md
│   ├── PRODUCTION_GUIDE.md
│   ├── REFACTORING_CLEANUP.md
│   ├── TECHNICAL_DEBT.md
│   └── USER_GUIDE.md
├── installer/               # Installation scripts and tools
│   ├── setup.sh
│   └── backup_cleanup.sh
├── scripts/                 # User-facing utility scripts
│   ├── install.sh           # Main installation script
│   ├── uninstall.sh         # Uninstallation script
│   ├── update.sh            # Update script
│   ├── fix_permissions.sh   # Permission repair script
│   ├── check_code.sh        # Code quality checks
│   └── run_tests.sh         # Test runner
├── src/                     # Modular architecture (in development)
│   ├── __init__.py
│   ├── exporters/           # File export modules
│   ├── generators/          # Item/Thing/Sitemap generators
│   ├── parsers/             # KNX project parsers
│   └── utils/               # Utility modules
├── templates/               # OpenHAB configuration templates
│   ├── items.template
│   ├── things.template
│   └── sitemap.template
├── tests/                   # Test suite
│   ├── api/                 # API endpoint tests
│   ├── integration/         # Integration tests
│   ├── tools/               # Test utilities
│   └── unit/                # Unit tests
└── web_ui/                  # Web interface
    ├── backend/             # Flask API server
    └── frontend/            # HTML/CSS/JS interface

Key Directories

• src/: New modular architecture (work in progress, gradually replacing legacy modules)
• templates/: OpenHAB configuration templates (Items, Things, Sitemaps)
• scripts/: User-facing scripts for installation, updates, and maintenance
• tests/: Comprehensive test suite with unit, integration, and API tests
• web_ui/: Complete web interface for project management
• docs/: All project documentation

---

Development

Running Tests

# Run all tests
pytest tests/

# Run with coverage
pytest tests/ --cov=. --cov-report=html

# Run specific test suite
pytest tests/unit/
pytest tests/integration/
pytest tests/api/

Code Quality

# Run code quality checks
./scripts/check_code.sh

Local Development

See the Developer Guide for detailed setup instructions.

---

Contributing

Contributions are welcome! Please:

1. Check the Technical Debt Tracking for areas needing improvement
2. Follow the code style and conventions
3. Add tests for new features
4. Update documentation as needed

---

License

This project is open-source.