Initial HA KNX Bridge scaffold

README.md

@@ -0,0 +1,46 @@
+# HA KNX Bridge
+
+Bridge existing Home Assistant entities to KNX group addresses. The integration lets you
+add "Ports" that bind an HA entity to KNX addresses for state updates and commands.
+
+Current minimal scope:
+- Binary Sensor port (state -> KNX)
+- Cover port (KNX -> HA commands, HA state -> KNX)
+
+## Requirements
+- Home Assistant 2025.12 or newer (tested for compatibility with 2026.2).
+- The built-in KNX integration must be set up and running.
+
+## Install (HACS)
+1. Add this repository as a custom integration in HACS.
+2. Install the integration.
+3. Restart Home Assistant.
+4. Add the "HA KNX Bridge" integration from the UI.
+
+## Configure
+1. During setup, select the existing Home Assistant KNX integration entry.
+2. Add Ports from the integration's configuration page.
+
+### Binary Sensor Port
+- `entity_id`: the HA binary_sensor to mirror.
+- `state_address` (DPT 1): KNX group address that receives the HA state.
+
+### Cover Port
+- `entity_id`: the HA cover to control/monitor.
+- `move_long_address` (DPT 1.008 Up/Down): KNX group address for open/close commands.
+- `stop_address` (DPT 1): KNX group address for stop commands.
+- `position_address` (DPT 5.001): KNX group address for set position.
+- `position_state_address` (DPT 5.001): KNX group address that receives HA position updates.
+- `angle_address` (DPT 5.001): KNX group address for set tilt position.
+- `angle_state_address` (DPT 5.001): KNX group address that receives HA tilt updates.
+
+If a group address is left empty, it is ignored.
+
+## Notes
+- For DPT 1.008 (Up/Down), the bridge treats `0 = Up/Open` and `1 = Down/Close`.
+- For DPT 5.001, values are interpreted as 0-100 percent where 0 = closed and 100 = open.
+
+## Roadmap
+- Optional standalone KNX connection (without requiring the HA KNX integration).
+- Additional entity types (light, switch, sensor, climate).
+- Advanced DPT mapping options and inversion settings.