# Light Color Mapper

Syncs light colors in real-time from color sensor entities. Sensors and lights are paired by list index (sensor 0 → light 0, sensor 1 → light 1, etc.).

## Features

- Real-time color sync from sensor entities to lights
- Index-based sensor-to-light mapping (add in matching order)
- FPS throttling for performance control (0–60 fps)
- Brightness override or per-sensor brightness from attributes
- Configurable behavior when sensors are unavailable (turn off, keep last, default color)
- Control entity (switch/input_boolean) to enable/disable
- Optional auto-off when the control entity is disabled
- Custom post-update callback action (runs after each update cycle)

## How It Works

The automation triggers on any state change from the configured color sensors. Each sensor is paired with a light by list position:

| Sensor Index | Light Index |
| --- | --- |
| Sensor 0 | Light 0 |
| Sensor 1 | Light 1 |
| Sensor 2 | Light 2 |
| ... | ... |

When a sensor updates, **all** sensor-light pairs are re-evaluated to keep lights in sync.

### FPS Throttling

The automation uses `mode: restart` with a trailing delay to throttle updates:

- **FPS = 0**: No throttle — every state change triggers an immediate update.
- **FPS > 0**: After processing all lights, a delay of `1000 / FPS` ms is added. If a new sensor state arrives during the delay, the automation restarts with the latest data. This naturally caps updates to the configured FPS.

### Sensor Requirements

Each color sensor should expose:

| Attribute | Description |
| --- | --- |
| **State** | Hex color string (e.g., `#FF8800`) or `None` when not processing |
| `rgb_color` | Color as `[r, g, b]` list (used to set light color) |
| `brightness` | Brightness value 0–255 (used when no override is set) |

## Configuration

| Input | Description |
| --- | --- |
| **Control Entity** | Switch or input_boolean that enables/disables the automation |
| **Turn Off Lights on Disable** | Turn off all mapped lights when the control entity is switched off (default: true) |
| **Color Sensors** | List of color sensor entities (index-mapped to lights) |
| **Lights** | List of light entities (index-mapped to sensors) |
| **Maximum FPS** | Update rate limit, 0 = unlimited (default: 0) |
| **Brightness Override** | Fixed brightness for all lights, 0 = use sensor brightness (default: 0) |
| **When Sensor is Unavailable** | Action when sensor is None/unavailable: Turn Off, Keep Last, or Set Default Color |
| **Default Color** | Color to apply when sensor is unavailable and action is "Set Default Color" |
| **Post-Update Action** | Custom action to run after all lights are updated (e.g., fire an event, call a service) |

## Notes

- If the sensor and light lists have different lengths, only the shorter count of pairs is used (extra entities are ignored).
- When the control entity is turned off and "Turn Off Lights on Disable" is enabled, only the paired lights (up to `pair_count`) are turned off.

## Author

Alexei Dolgolyov (<dolgolyov.alexei@gmail.com>)