HA-KNX-Bridge/README.md

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

### Light Port
- `entity_id`: the HA light to control/monitor.
- `address` (DPT 1.001): KNX group address for on/off commands.
- `state_address` (DPT 1.001): KNX group address that receives HA on/off state.
- `brightness_address` (DPT 5.001): KNX group address for brightness commands.
- `brightness_state_address` (DPT 5.001): KNX group address that receives HA brightness.
- `color_address` (DPT 232.600): KNX group address for RGB commands.
- `color_state_address` (DPT 232.600): KNX group address that receives HA RGB state.
- `rgbw_address` (DPT 251.600): KNX group address for RGBW commands.
- `rgbw_state_address` (DPT 251.600): KNX group address that receives HA RGBW state.
- `hue_address` (DPT 5.003): KNX group address for hue commands.
- `hue_state_address` (DPT 5.003): KNX group address that receives HA hue state.
- `saturation_address` (DPT 5.001): KNX group address for saturation commands.
- `saturation_state_address` (DPT 5.001): KNX group address that receives HA saturation state.
- `xyy_address` (DPT 242.600): KNX group address for XY color commands.
- `xyy_state_address` (DPT 242.600): KNX group address that receives HA XY color state.
- `color_temperature_address` (DPT 5.001/7.600/9): KNX group address for color temperature commands.
- `color_temperature_state_address` (DPT 5.001/7.600/9): KNX group address that receives HA color temperature state.
- `color_temperature_mode`: `relative` (DPT 5.001 percent), `absolute` (DPT 7.600 Kelvin), or `absolute_float` (DPT 9 Kelvin).
- `min_kelvin` / `max_kelvin`: Kelvin range used for `relative` color temperature mapping.
- Individual colors (DPT 1.001 + 5.001): `red_*`, `green_*`, `blue_*`, `white_*` on/off and brightness addresses with matching state addresses.

Notes:
- If `state_address` or `*_state_address` is empty, the command address is reused for outgoing updates.
- For XY color, the bridge sends the brightness as the Y (luminance) component.

## 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
- Light `address` / `state_address`: DPT 1.001
- Light `brightness_address` / `brightness_state_address`: DPT 5.001
- Light `color_address` / `color_state_address`: DPT 232.600
- Light `rgbw_address` / `rgbw_state_address`: DPT 251.600
- Light `hue_address` / `hue_state_address`: DPT 5.003
- Light `saturation_address` / `saturation_state_address`: DPT 5.001
- Light `xyy_address` / `xyy_state_address`: DPT 242.600
- Light `color_temperature_address` / `color_temperature_state_address`: DPT 5.001/7.600/9
- Light `red_*`, `green_*`, `blue_*`, `white_*` brightness: DPT 5.001
- Light `red_*`, `green_*`, `blue_*`, `white_*` on/off: DPT 1.001

## Roadmap
- Optional standalone KNX connection (without requiring the HA KNX integration).
- Additional entity types (sensor, climate).
- Advanced DPT mapping options and inversion settings.

## Versioning and Releases
- Current version: 0.0.21
- `CHANGELOG.md` lists versions with the newest entries at the top.