Merge eef4d2c379 into b2ca188df3

README.md

@@ -86,6 +86,7 @@ The attributes are absent when the Adaptive Lighting switch is off. Use a fallba
   - [:exclamation: Common Problems & Solutions](#exclamation-common-problems--solutions)
     - [:bulb: Lights Only Adapt After Reloading](#bulb-lights-only-adapt-after-reloading)
     - [:bulb: Lights Not Responding or Turning On by Themselves](#bulb-lights-not-responding-or-turning-on-by-themselves)
+  - [Color-temperature lights incorrectly detected as manually controlled](#color-temperature-lights-incorrectly-detected-as-manually-controlled)
     - [:signal_strength: WiFi Networks](#signal_strength-wifi-networks)
     - [:spider_web: Zigbee, Z-Wave, and Other Mesh Networks](#spider_web-zigbee-z-wave-and-other-mesh-networks)
     - [:rainbow: Light Colors Not Matching](#rainbow-light-colors-not-matching)
@@ -159,6 +160,7 @@ The YAML and frontend configuration methods support all of the options listed be
 | `take_over_control`                         | Pause adaptation of individual lights and hand over (manual) control to other sources that issue `light.turn_on` calls for lights that are on. 🔒                                                                                                                                                                                                                                             | `True`         | `bool`                                  |
 | `take_over_control_mode`                    | The adaptation pausing mode when other sources change brightness and/or color of lights. `pause_all` always pauses both brightness and color adaptation. `pause_changed` pauses the adaptation of only the changed attributes and continues adapting unchanged attributes, e.g., continues color adaptation when only brightness was changed.                                                 | `pause_all`    | one of `['pause_all', 'pause_changed']` |
 | `detect_non_ha_changes`                     | Detects and halts adaptations for non-`light.turn_on` state changes. Needs `take_over_control` enabled. 🕵️ Caution: ⚠️ Some lights might falsely indicate an 'on' state, which could result in lights turning on unexpectedly. Note that this calls `homeassistant.update_entity` every `interval`! Disable this feature if you encounter such issues.                                        | `False`        | `bool`                                  |
+| `detect_color_mode_changes`                 | Treat a reported color-mode change alone as manual control when `detect_non_ha_changes` is enabled. Disable for lights that report requested color temperatures as RGB/HS; brightness and meaningful color changes are still detected. Equivalent-color mode-only changes will then be ignored.                                                                                               | `True`         | `bool`                                  |
 | `autoreset_control_seconds`                 | Automatically reset the manual control after a number of seconds. Set to 0 to disable. ⏲️                                                                                                                                                                                                                                                                                                     | `0`            | `int` 0-31536000                        |
 | `only_once`                                 | Adapt lights only when they are turned on (`true`) or keep adapting them (`false`). 🔄                                                                                                                                                                                                                                                                                                        | `False`        | `bool`                                  |
 | `adapt_only_on_bare_turn_on`                | When turning lights on initially. If set to `true`, AL adapts only if `light.turn_on` is invoked without specifying color or brightness. ❌🌈 This e.g., prevents adaptation when activating a scene and marks the light as manually controlled. If `false`, AL adapts regardless of the presence of color or brightness in the initial `service_data`. Needs `take_over_control` enabled. 🕵️ | `False`        | `bool`                                  |
@@ -785,6 +787,24 @@ Addressing these issues will significantly improve your Home Assistant experienc
 In case lights are suddenly turning on by themselves, this is most likely due to the light incorrectly reporting an "on" state to Home Assistant, leading to an undesired Adaptive Lighting action.
 To prevent adapting in cases *where the state of the light is suddenly "on" and only adapt if there is an associated `light.turn_on` service call*, set `detect_non_ha_changes: false`.
 
+### Color-temperature lights incorrectly detected as manually controlled
+
+Some integrations report a requested color temperature as RGB/HS instead of
+reporting the active color-temperature mode. With `detect_non_ha_changes: true`,
+that representation change alone normally counts as manual control, even if the
+reported color is equivalent.
+
+For those lights, set `detect_color_mode_changes: false` in their Adaptive
+Lighting instance's advanced settings. Brightness and meaningful color changes
+are still detected using the existing comparison tolerances; this does **not**
+disable external-change detection. The default is `true`, preserving detection
+of external scenes that change only the color mode. Disabling the option also
+means an intentional mode-only change to an equivalent color is ignored.
+
+This is an instance-wide setting. Use a separate instance if only some lights
+need it. It cannot correct inaccurate color readback or distinguish an external
+change that falls within the existing tolerances.
+
 To keep detecting manual changes to lights that are already on while leaving unmatched `off` to `on` state events unchanged, enable `manual_control_on_external_turn_on`. Matching uses the exact context of the most recently recorded `light.turn_on` call. Some integrations replace or omit that context, so Adaptive Lighting cannot distinguish every physical versus Home Assistant turn-on source.
 
 #### :signal_strength: WiFi Networks

custom_components/adaptive_lighting/const.py

@@ -47,6 +47,17 @@ DOCS[CONF_DETECT_NON_HA_CHANGES] = (
     "Disable this feature if you encounter such issues."
 )
 
+CONF_DETECT_COLOR_MODE_CHANGES, DEFAULT_DETECT_COLOR_MODE_CHANGES = (
+    "detect_color_mode_changes",
+    True,
+)
+DOCS[CONF_DETECT_COLOR_MODE_CHANGES] = (
+    "Treat a reported color-mode change alone as manual control when "
+    "`detect_non_ha_changes` is enabled. Disable for lights that report requested "
+    "color temperatures as RGB/HS; brightness and meaningful color changes are "
+    "still detected. Equivalent-color mode-only changes will then be ignored."
+)
+
 CONF_INCLUDE_CONFIG_IN_ATTRIBUTES, DEFAULT_INCLUDE_CONFIG_IN_ATTRIBUTES = (
     "include_config_in_attributes",
     False,
@@ -427,6 +438,7 @@ VALIDATION_TUPLES: list[tuple[str, Any, Any]] = [
         ),
     ),
     (CONF_DETECT_NON_HA_CHANGES, DEFAULT_DETECT_NON_HA_CHANGES, bool),
+    (CONF_DETECT_COLOR_MODE_CHANGES, DEFAULT_DETECT_COLOR_MODE_CHANGES, bool),
     (
         CONF_AUTORESET_CONTROL,
         DEFAULT_AUTORESET_CONTROL,

custom_components/adaptive_lighting/services.yaml

@@ -238,6 +238,11 @@ change_switch_settings:
           options:
           - pause_all
           - pause_changed
+    detect_color_mode_changes:
+      description: Treat a reported color-mode change alone as manual control when `detect_non_ha_changes` is enabled. Disable for lights that report requested color temperatures as RGB/HS; brightness and meaningful color changes are still detected. Equivalent-color mode-only changes will then be ignored.
+      required: false
+      selector:
+        boolean: null
     detect_non_ha_changes:
       description: 'Detects and halts adaptations for non-`light.turn_on` state changes. Needs `take_over_control` enabled. 🕵️ Caution: ⚠️ Some lights might falsely indicate an ''on'' state, which could result in lights turning on unexpectedly. Note that this calls `homeassistant.update_entity` every `interval`! Disable this feature if you encounter such issues.'
       required: false

custom_components/adaptive_lighting/strings.json

@@ -67,6 +67,7 @@
               "take_over_control": "take_over_control: Pause adaptation of individual lights and hand over (manual) control to other sources that issue `light.turn_on` calls for lights that are on. 🔒",
               "take_over_control_mode": "take_over_control_mode",
               "detect_non_ha_changes": "detect_non_ha_changes: Detects and halts adaptations for non-`light.turn_on` state changes. Needs `take_over_control` enabled. 🕵️ Caution: ⚠️ Some lights might falsely indicate an 'on' state, which could result in lights turning on unexpectedly. Note that this calls `homeassistant.update_entity` every `interval`! Disable this feature if you encounter such issues.",
+              "detect_color_mode_changes": "detect_color_mode_changes: Treat a reported color-mode change alone as manual control when `detect_non_ha_changes` is enabled. Disable for lights that report requested color temperatures as RGB/HS; brightness and meaningful color changes are still detected. Equivalent-color mode-only changes will then be ignored.",
               "autoreset_control_seconds": "autoreset_control_seconds",
               "only_once": "only_once: Adapt lights only when they are turned on (`true`) or keep adapting them (`false`). 🔄",
               "adapt_only_on_bare_turn_on": "adapt_only_on_bare_turn_on: When turning lights on initially. If set to `true`, AL adapts only if `light.turn_on` is invoked without specifying color or brightness. ❌🌈 This e.g., prevents adaptation when activating a scene and marks the light as manually controlled. If `false`, AL adapts regardless of the presence of color or brightness in the initial `service_data`. Needs `take_over_control` enabled. 🕵️",
@@ -272,6 +273,10 @@
           "description": "The adaptation pausing mode when other sources change brightness and/or color of lights. `pause_all` always pauses both brightness and color adaptation. `pause_changed` pauses the adaptation of only the changed attributes and continues adapting unchanged attributes, e.g., continues color adaptation when only brightness was changed.",
           "name": "take_over_control_mode"
         },
+        "detect_color_mode_changes": {
+          "description": "Treat a reported color-mode change alone as manual control when `detect_non_ha_changes` is enabled. Disable for lights that report requested color temperatures as RGB/HS; brightness and meaningful color changes are still detected. Equivalent-color mode-only changes will then be ignored.",
+          "name": "detect_color_mode_changes"
+        },
         "detect_non_ha_changes": {
           "description": "Detects and halts adaptations for non-`light.turn_on` state changes. Needs `take_over_control` enabled. 🕵️ Caution: ⚠️ Some lights might falsely indicate an 'on' state, which could result in lights turning on unexpectedly. Note that this calls `homeassistant.update_entity` every `interval`! Disable this feature if you encounter such issues.",
           "name": "detect_non_ha_changes"

custom_components/adaptive_lighting/switch.py

@@ -100,6 +100,7 @@ from .const import (
     CONF_BRIGHTNESS_MODE,
     CONF_BRIGHTNESS_MODE_TIME_DARK,
     CONF_BRIGHTNESS_MODE_TIME_LIGHT,
+    CONF_DETECT_COLOR_MODE_CHANGES,
     CONF_DETECT_NON_HA_CHANGES,
     CONF_EXPAND_LIGHT_GROUPS,
     CONF_INCLUDE_CONFIG_IN_ATTRIBUTES,
@@ -802,6 +803,8 @@ def _attributes_have_changed(
     old_attributes: dict[str, Any],
     new_attributes: dict[str, Any],
     context: Context,
+    *,
+    detect_color_mode_changes: bool = True,
 ) -> LightControlAttributes:
     # 2023-11-19: HA core no longer removes light domain attributes when off
     # so we must protect for `None` here
@@ -812,7 +815,7 @@ def _attributes_have_changed(
     # Check for color mode changes BEFORE attribute conversion
     # This detects external changes like Hue scenes switching from color_temp to RGB
     # See: https://github.com/basnijholt/adaptive-lighting/issues/1275
-    if _has_color_mode_changed(
+    if detect_color_mode_changes and _has_color_mode_changed(
         light,
         old_attributes,
         new_attributes,
@@ -955,6 +958,7 @@ class AdaptiveSwitch(SwitchEntity, RestoreEntity):
         self._current_settings = data
 
         self._detect_non_ha_changes = data[CONF_DETECT_NON_HA_CHANGES]
+        self._detect_color_mode_changes = data[CONF_DETECT_COLOR_MODE_CHANGES]
         self._include_config_in_attributes = data[CONF_INCLUDE_CONFIG_IN_ATTRIBUTES]
         self._config: dict[str, Any] = {}
         if self._include_config_in_attributes:
@@ -3002,6 +3006,7 @@ class AdaptiveLightingManager:
                 new_attributes=refreshed_state.attributes,
                 light=light,
                 context=context,
+                detect_color_mode_changes=switch._detect_color_mode_changes,
             )
         if changed_attributes:
             self.update_manual_control_state(

custom_components/adaptive_lighting/translations/en.json

@@ -68,6 +68,7 @@
               "take_over_control": "take_over_control: Pause adaptation of individual lights and hand over (manual) control to other sources that issue `light.turn_on` calls for lights that are on. 🔒",
               "take_over_control_mode": "take_over_control_mode",
               "detect_non_ha_changes": "detect_non_ha_changes: Detects and halts adaptations for non-`light.turn_on` state changes. Needs `take_over_control` enabled. 🕵️ Caution: ⚠️ Some lights might falsely indicate an 'on' state, which could result in lights turning on unexpectedly. Note that this calls `homeassistant.update_entity` every `interval`! Disable this feature if you encounter such issues.",
+              "detect_color_mode_changes": "detect_color_mode_changes: Treat a reported color-mode change alone as manual control when `detect_non_ha_changes` is enabled. Disable for lights that report requested color temperatures as RGB/HS; brightness and meaningful color changes are still detected. Equivalent-color mode-only changes will then be ignored.",
               "autoreset_control_seconds": "autoreset_control_seconds",
               "only_once": "only_once: Adapt lights only when they are turned on (`true`) or keep adapting them (`false`). 🔄",
               "adapt_only_on_bare_turn_on": "adapt_only_on_bare_turn_on: When turning lights on initially. If set to `true`, AL adapts only if `light.turn_on` is invoked without specifying color or brightness. ❌🌈 This e.g., prevents adaptation when activating a scene and marks the light as manually controlled. If `false`, AL adapts regardless of the presence of color or brightness in the initial `service_data`. Needs `take_over_control` enabled. 🕵️",
@@ -273,6 +274,10 @@
           "description": "The adaptation pausing mode when other sources change brightness and/or color of lights. `pause_all` always pauses both brightness and color adaptation. `pause_changed` pauses the adaptation of only the changed attributes and continues adapting unchanged attributes, e.g., continues color adaptation when only brightness was changed.",
           "name": "take_over_control_mode"
         },
+        "detect_color_mode_changes": {
+          "description": "Treat a reported color-mode change alone as manual control when `detect_non_ha_changes` is enabled. Disable for lights that report requested color temperatures as RGB/HS; brightness and meaningful color changes are still detected. Equivalent-color mode-only changes will then be ignored.",
+          "name": "detect_color_mode_changes"
+        },
         "detect_non_ha_changes": {
           "description": "Detects and halts adaptations for non-`light.turn_on` state changes. Needs `take_over_control` enabled. 🕵️ Caution: ⚠️ Some lights might falsely indicate an 'on' state, which could result in lights turning on unexpectedly. Note that this calls `homeassistant.update_entity` every `interval`! Disable this feature if you encounter such issues.",
           "name": "detect_non_ha_changes"

docs/configuration.md

@@ -63,6 +63,7 @@ All configuration options are listed below with their default values. These opti
 | `take_over_control`                         | Pause adaptation of individual lights and hand over (manual) control to other sources that issue `light.turn_on` calls for lights that are on. 🔒                                                                                                                                                                                                                                             | `True`         | `bool`                                  |
 | `take_over_control_mode`                    | The adaptation pausing mode when other sources change brightness and/or color of lights. `pause_all` always pauses both brightness and color adaptation. `pause_changed` pauses the adaptation of only the changed attributes and continues adapting unchanged attributes, e.g., continues color adaptation when only brightness was changed.                                                 | `pause_all`    | one of `['pause_all', 'pause_changed']` |
 | `detect_non_ha_changes`                     | Detects and halts adaptations for non-`light.turn_on` state changes. Needs `take_over_control` enabled. 🕵️ Caution: ⚠️ Some lights might falsely indicate an 'on' state, which could result in lights turning on unexpectedly. Note that this calls `homeassistant.update_entity` every `interval`! Disable this feature if you encounter such issues.                                        | `False`        | `bool`                                  |
+| `detect_color_mode_changes`                 | Treat a reported color-mode change alone as manual control when `detect_non_ha_changes` is enabled. Disable for lights that report requested color temperatures as RGB/HS; brightness and meaningful color changes are still detected. Equivalent-color mode-only changes will then be ignored.                                                                                               | `True`         | `bool`                                  |
 | `autoreset_control_seconds`                 | Automatically reset the manual control after a number of seconds. Set to 0 to disable. ⏲️                                                                                                                                                                                                                                                                                                     | `0`            | `int` 0-31536000                        |
 | `only_once`                                 | Adapt lights only when they are turned on (`true`) or keep adapting them (`false`). 🔄                                                                                                                                                                                                                                                                                                        | `False`        | `bool`                                  |
 | `adapt_only_on_bare_turn_on`                | When turning lights on initially. If set to `true`, AL adapts only if `light.turn_on` is invoked without specifying color or brightness. ❌🌈 This e.g., prevents adaptation when activating a scene and marks the light as manually controlled. If `false`, AL adapts regardless of the presence of color or brightness in the initial `service_data`. Needs `take_over_control` enabled. 🕵️ | `False`        | `bool`                                  |

docs/troubleshooting.md

@@ -67,6 +67,24 @@ Addressing these issues will significantly improve your Home Assistant experienc
 In case lights are suddenly turning on by themselves, this is most likely due to the light incorrectly reporting an "on" state to Home Assistant, leading to an undesired Adaptive Lighting action.
 To prevent adapting in cases *where the state of the light is suddenly "on" and only adapt if there is an associated `light.turn_on` service call*, set `detect_non_ha_changes: false`.
 
+### Color-temperature lights incorrectly detected as manually controlled
+
+Some integrations report a requested color temperature as RGB/HS instead of
+reporting the active color-temperature mode. With `detect_non_ha_changes: true`,
+that representation change alone normally counts as manual control, even if the
+reported color is equivalent.
+
+For those lights, set `detect_color_mode_changes: false` in their Adaptive
+Lighting instance's advanced settings. Brightness and meaningful color changes
+are still detected using the existing comparison tolerances; this does **not**
+disable external-change detection. The default is `true`, preserving detection
+of external scenes that change only the color mode. Disabling the option also
+means an intentional mode-only change to an equivalent color is ignored.
+
+This is an instance-wide setting. Use a separate instance if only some lights
+need it. It cannot correct inaccurate color readback or distinguish an external
+change that falls within the existing tolerances.
+
 To keep detecting manual changes to lights that are already on while leaving unmatched `off` to `on` state events unchanged, enable `manual_control_on_external_turn_on`. Matching uses the exact context of the most recently recorded `light.turn_on` call. Some integrations replace or omit that context, so Adaptive Lighting cannot distinguish every physical versus Home Assistant turn-on source.
 
 #### :signal_strength: WiFi Networks

tests/test_color_mode_policy.py

@@ -0,0 +1,156 @@
+"""Reported-mode policy must not disable meaningful external-change detection."""
+
+from unittest.mock import AsyncMock, Mock, patch
+
+import pytest
+from homeassistant.components.adaptive_lighting.adaptation_utils import (
+    LightControlAttributes,
+)
+from homeassistant.components.adaptive_lighting.const import (
+    CONF_DETECT_COLOR_MODE_CHANGES,
+    DOMAIN,
+    SERVICE_CHANGE_SWITCH_SETTINGS,
+)
+from homeassistant.components.adaptive_lighting.switch import (
+    AdaptiveLightingManager,
+    _attributes_have_changed,
+    validate,
+)
+from homeassistant.components.light import (
+    ATTR_BRIGHTNESS,
+    ATTR_COLOR_TEMP_KELVIN,
+    ATTR_RGB_COLOR,
+)
+from homeassistant.core import Context
+from homeassistant.util.color import color_temperature_to_rgb
+
+from .test_switch import setup_lights_and_switch
+
+
+@pytest.mark.parametrize("kelvin", [2000, 2700, 4000, 6500])
+@pytest.mark.parametrize("reverse", [False, True])
+def test_equivalent_color_readback(kelvin, reverse):
+    """An opt-in policy tolerates CT represented as RGB without disabling detection."""
+    old = {ATTR_BRIGHTNESS: 128, ATTR_COLOR_TEMP_KELVIN: kelvin}
+    new = {ATTR_BRIGHTNESS: 128, ATTR_RGB_COLOR: color_temperature_to_rgb(kelvin)}
+    if reverse:
+        old, new = new, old
+
+    # Existing behavior, including Hue scene mode changes, is the default.
+    assert _attributes_have_changed(
+        "light.test",
+        old.copy(),
+        new.copy(),
+        Context(),
+    ) == (LightControlAttributes.COLOR)
+    assert (
+        _attributes_have_changed(
+            "light.test",
+            old.copy(),
+            new.copy(),
+            Context(),
+            detect_color_mode_changes=False,
+        )
+        == LightControlAttributes.NONE
+    )
+
+
+@pytest.mark.parametrize(
+    ("brightness", "rgb", "expected"),
+    [
+        (128, (255, 0, 0), LightControlAttributes.COLOR),
+        (255, color_temperature_to_rgb(4000), LightControlAttributes.BRIGHTNESS),
+        (255, (255, 0, 0), LightControlAttributes.ALL),
+    ],
+)
+def test_semantic_policy_still_detects_changes(brightness, rgb, expected):
+    """Opting out of mode-only detection must retain per-axis value detection."""
+    assert (
+        _attributes_have_changed(
+            "light.test",
+            {ATTR_BRIGHTNESS: 128, ATTR_COLOR_TEMP_KELVIN: 4000},
+            {ATTR_BRIGHTNESS: brightness, ATTR_RGB_COLOR: rgb},
+            Context(),
+            detect_color_mode_changes=False,
+        )
+        == expected
+    )
+
+
+def test_color_mode_policy_default_and_runtime_settings():
+    """Existing configurations stay strict; runtime edits retain explicit false."""
+    defaults = validate(None, {})
+    assert defaults[CONF_DETECT_COLOR_MODE_CHANGES] is True
+    configured = validate(None, {CONF_DETECT_COLOR_MODE_CHANGES: False})
+    assert configured[CONF_DETECT_COLOR_MODE_CHANGES] is False
+    assert validate(None, {}, configured)[CONF_DETECT_COLOR_MODE_CHANGES] is False
+
+
+def test_observed_homekit_readback():
+    """A timestamp-free observer sample differs only in color representation."""
+    old = {ATTR_BRIGHTNESS: 115, ATTR_COLOR_TEMP_KELVIN: 2127}
+    new = {ATTR_BRIGHTNESS: 114.75, ATTR_RGB_COLOR: (255, 142, 28)}
+    assert _attributes_have_changed(
+        "light.test",
+        old.copy(),
+        new.copy(),
+        Context(),
+    ) == (LightControlAttributes.COLOR)
+    assert (
+        _attributes_have_changed(
+            "light.test",
+            old.copy(),
+            new.copy(),
+            Context(),
+            detect_color_mode_changes=False,
+        )
+        == LightControlAttributes.NONE
+    )
+
+
+async def test_runtime_service_changes_comparison_policy(hass):
+    """Changing settings updates the switch field used by subsequent polls."""
+    switch, _ = await setup_lights_and_switch(hass)
+    assert switch._detect_color_mode_changes is True
+    await hass.services.async_call(
+        DOMAIN,
+        SERVICE_CHANGE_SWITCH_SETTINGS,
+        {"entity_id": switch.entity_id, CONF_DETECT_COLOR_MODE_CHANGES: False},
+        blocking=True,
+    )
+    assert switch._detect_color_mode_changes is False
+    await hass.services.async_call(
+        DOMAIN,
+        SERVICE_CHANGE_SWITCH_SETTINGS,
+        {"entity_id": switch.entity_id, "use_defaults": "factory"},
+        blocking=True,
+    )
+    assert switch._detect_color_mode_changes is True
+
+
+@pytest.mark.parametrize("detect_mode", [True, False])
+async def test_manager_uses_color_mode_policy(hass, detect_mode):
+    """Exercise the polling path, not just the comparison helper."""
+    light = "light.test"
+    hass.states.async_set(
+        light,
+        "on",
+        {ATTR_BRIGHTNESS: 128, ATTR_RGB_COLOR: color_temperature_to_rgb(4000)},
+    )
+    manager = AdaptiveLightingManager(hass)
+    manager.last_service_data[light] = {
+        ATTR_BRIGHTNESS: 128,
+        ATTR_COLOR_TEMP_KELVIN: 4000,
+    }
+    switch = Mock(_detect_non_ha_changes=True, _detect_color_mode_changes=detect_mode)
+    try:
+        with patch(
+            "homeassistant.components.adaptive_lighting.switch.async_update_entity",
+            new_callable=AsyncMock,
+        ):
+            changed = await manager.significant_change(switch, light, Context())
+        assert changed == (
+            LightControlAttributes.COLOR if detect_mode else LightControlAttributes.NONE
+        )
+    finally:
+        manager.disable()