# 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)
- Switch port (KNX -> HA commands, HA 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.
   If the "Add Port" UI is missing, open the integration options and manage ports
   there (fallback for HA versions without subentry support).
3. Each Port shows up as a device with an enable switch for quick on/off control.

### 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.
Group address format must be `X/Y/Z` (0-31/0-7/0-255) or `X/Y` (0-31/0-2047).
Only state addresses expose an `invert outgoing` toggle to flip KNX payloads.

### Switch Port
- `entity_id`: the HA switch to control/monitor.
- `command_address` (DPT 1): KNX group address for on/off commands.
- `state_address` (DPT 1): KNX group address that receives HA on/off state.

## 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.
- DPTs are auto-selected per address:
- Binary sensor `state_address`: DPT 1
- Switch `command_address`: DPT 1
- Switch `state_address`: DPT 1
- Cover `move_long_address`: DPT 1.008
- Cover `move_short_address`: DPT 1.007
- Cover `stop_address`: DPT 1
- Cover `position_address`: DPT 5.001
- Cover `position_state_address`: DPT 5.001
- Cover `angle_address`: DPT 5.001
- Cover `angle_state_address`: DPT 5.001

## 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.

## Versioning and Releases
- Current version: 0.0.20
- `CHANGELOG.md` lists versions with the newest entries at the top.
- Release creation is manual and only done when explicitly requested.