# Changelog — CDiT Adaptive Lighting fork All notable CDiT-fork changes are documented here. The upstream `basnijholt/adaptive-lighting` changelog is in upstream's release notes; this file covers only changes specific to this fork. The format is loosely based on [Keep a Changelog](https://keepachangelog.com/). --- ## Standing on the shoulders of giants This fork builds on **[basnijholt/adaptive-lighting](https://github.com/basnijholt/adaptive-lighting)** — years of work by [@basnijholt](https://github.com/basnijholt) and 130+ contributors. The curve math, light intercept, HACS distribution, simulator webapp, and the long tail of edge cases the original handles correctly all come from that codebase. This fork is a narrow set of opinions layered on a deep, mature foundation; the credit for *making this idea work at all* belongs upstream. If you're not specifically a CDiT-style single-household installation, please prefer the upstream integration — it's better-maintained, supports more use cases, and has the entire community behind it. Issues with core curve math or light handling belong on the upstream tracker, where they reach the maintainers who can actually fix them for everyone. --- ## [2.0.0-cdit.1] — Unreleased The first major CDiT release. **Breaking change**: existing upstream config entries will not load — see "Upgrading" below. ### Added - **Sectioned options dialog** rendered via HA's `section()` helper. Six groups (Targets, Daytime curve, Sun schedule, Light control, Advanced, Diagnostics) replace the upstream 40-field flat form. - **Native HA selectors throughout** — `NumberSelector` (slider for brightness 1–100 %, box for color temp 1000–10000 K), `EntitySelector` (typed to `domain=sensor, device_class=timestamp` for sun events, `domain=light, multiple=True` for the light list), `BooleanSelector`. - **Conditional field visibility** — `send_split_delay` only appears when its driver `separate_turn_on_commands` is enabled. - **Entity-driven sun timing** — two new options `sunrise_entity` and `sunset_entity` accept any sensor with `device_class: timestamp`. Defaults to the built-in `sensor.sun_next_rising` / `sensor.sun_next_setting`. Plug in Sun2 (`sensor.sun2_dawn`, `sensor.sun2_astro_dawn`, etc.) without any code changes. - **Synthetic tanh brightness/color-temp curve** with a hardcoded 30-minute ramp half-width around each sun event. Tunable in `const.py` via `RAMP_HALF_WIDTH_SECONDS` (currently `1800`). - **`OptionsFlowWithReload`** — saving options reloads the integration cleanly without a manual reload. - **Strict version-break guard** — `async_setup_entry` raises `ConfigEntryError` with a clear message when a config entry's version is older than the current major. - **Sleep-switch tombstone cleanup** — on first load after upgrade, orphan `switch.adaptive_lighting_sleep_mode_*` entities owned by this integration are removed from the entity registry and logged at `INFO`. - **Plain-language strings** — every label, description, and abort message rewritten to read like a sentence a human wrote, not engineer shorthand. Sections get a one-sentence framer at the top. ### Changed - **`DEFAULT_MIN_BRIGHTNESS`**: `1` → `5`. 1 % reads as off on most bulbs; 5 % is the dim-but-visible floor. - **`DEFAULT_MIN_COLOR_TEMP`**: `2000 K` → `2200 K`. Less sodium-vapor orange; warmer-lamp tone. - **Master switch icon**: `mdi:theme-light-dark` → `mdi:weather-sunny-alert`. - **`adapt_color` switch icon**: `mdi:sun-thermometer` → `mdi:invert-colors`. - **`adapt_brightness` switch icon**: `mdi:brightness-4` → `mdi:brightness-percent`. - **Minimum Home Assistant version**: pinned to `2025.1.0` in `manifest.json`. - **Manifest metadata** — `codeowners`, `documentation`, and `issue_tracker` now point to `CaseyRo/adaptive-lighting`. ### Removed **21 configuration fields**, **1 entity**, **1 service**, all part of upstream features that the CDiT fork does not use. - **Sleep mode cluster** (6 fields + 1 entity): `sleep_brightness`, `sleep_rgb_or_color_temp`, `sleep_color_temp`, `sleep_rgb_color`, `sleep_transition`, `transition_until_sleep`. The `switch.adaptive_lighting_sleep_mode_` entity is no longer created. Each profile now provides **three switches** (master, adapt_color, adapt_brightness) instead of four. - **Manual sun timing** (8 fields): `sunrise_time`, `min_sunrise_time`, `max_sunrise_time`, `sunrise_offset`, `sunset_time`, `min_sunset_time`, `max_sunset_time`, `sunset_offset`. Replaced by the two `*_entity` options above. - **Brightness curve shape** (3 fields): `brightness_mode`, `brightness_mode_time_dark`, `brightness_mode_time_light`. The curve is now always a tanh ramp. - **Take-over-control cluster** (4 fields): `take_over_control`, `take_over_control_mode`, `detect_non_ha_changes`, `autoreset_control_seconds`. Manual overrides are expected to live at the scene/automation layer. - **Anti-AL flags** (2 fields): `only_once`, `adapt_only_on_bare_turn_on`. If you don't want continuous adaptation on a light, don't run AL on that light. - **Service**: `adaptive_lighting.set_manual_control` no longer exists. The dependent state machine in `switch.py` and `AdaptiveLightingManager` remains as dead code in this release; follow-up cleanup will delete it. ### Migration / upgrading from upstream 1. Update via HACS (or copy `custom_components/adaptive_lighting/` over your existing install). 2. Restart Home Assistant. 3. The existing config entry shows as "failed to load" with the message "Adaptive Lighting v2 (CDiT fork) is incompatible with the existing config entry." 4. Delete the failed entry: **Settings → Devices & Services → Adaptive Lighting → ⋮ → Delete**. 5. Add a fresh entry: **Settings → Devices & Services → Add Integration → Adaptive Lighting**. 6. Open the new entry's **Configure** dialog and walk through the six sections. 7. (Optional) Install [Sun2](https://github.com/pnbruckner/ha-sun2) via HACS and point `sunrise_entity` / `sunset_entity` at one of its sensors. ### Internal - `color_and_brightness.py`: rewritten. `SunLightSettings` is now a pure curve-math dataclass with 5 fields. Sun event timestamps are passed in as arguments by the caller (which reads them from HA entities) rather than computed via `astral`. - `config_flow.py`: rewritten. ~250 LOC instead of 175 LOC, but each section, selector factory, and conditional is now isolated and testable. - `__init__.py`: adds version-check + tombstone-cleanup guards at the top of `async_setup_entry`. - Total integration code shrank by **~400 LOC** despite the new schema builder. ### Known limitations - `AdaptiveLightingManager` (in `switch.py`) still contains the manual-control bookkeeping infrastructure. The branches that would populate it are now dead code (the relevant `AdaptiveSwitch` attributes are bridge stubs hardcoded to `False`), but the bookkeeping dicts and helper methods remain. Cleanup is deferred to a follow-up change. - Locale files other than `en.json` are out of sync with the new schema and may render English strings until they are re-translated. Out of scope for this release. - `astral` is still a transitive dependency. The curve-evaluation path no longer imports it, so pruning is just a `pyproject.toml` edit when the package as a whole stops using it.