Individual manual control of brightness and color (#1356)

* refactor: introduce light control parameter enum

* refactor: replace manual control flag with parameter enum

* test: update deprecated color temp attribute

* build: set execution bits on task scripts

* feat: individual manual control of brightness and color

* test: add tests for individual manual control evaluation

* fix: sequential manual changes not always detected

If multiple attributes of a light were changed within an interval, only the last change was detected because the check in the interval only used the latest event. For example, if there was a brightness change and a following color change, only the color attribute was detected as manually controlled. To fix this, the manual control attribute flags are now set directly from the event handler so that all events are processed.

* fix: invalid service description

* docs: fix missing space in config description

* refactor: pluralize multivalued bitmask enum name

Author: protyposis

README.md

@@ -46,6 +46,8 @@ def _type_to_str(type_: Any) -> str:  # noqa: PLR0911
         return "bool"
     if isinstance(type_, vol.All):
         return _format_voluptuous_instance(type_)
+    if isinstance(type_, vol.Any):
+        return " or ".join(_type_to_str(t) for t in type_.validators)
     if isinstance(type_, vol.In):
         return f"one of `{type_.container}`"
     if isinstance(type_, selector.SelectSelector):

custom_components/adaptive_lighting/_docs_helpers.py

@@ -3,7 +3,8 @@
 import logging
 from collections.abc import AsyncGenerator
 from dataclasses import dataclass
-from typing import Any, Literal
+from enum import IntFlag, auto
+from typing import Any
 
 from homeassistant.components.light import (
     ATTR_BRIGHTNESS,
@@ -12,6 +13,8 @@
     ATTR_BRIGHTNESS_STEP_PCT,
     ATTR_COLOR_NAME,
     ATTR_COLOR_TEMP_KELVIN,
+    ATTR_EFFECT,
+    ATTR_FLASH,
     ATTR_HS_COLOR,
     ATTR_RGB_COLOR,
     ATTR_RGBW_COLOR,
@@ -45,6 +48,41 @@
 ServiceData = dict[str, Any]
 
 
+class LightControlAttributes(IntFlag):
+    """Attributes of lights that the adaptation engine can control."""
+
+    NONE = 0
+    BRIGHTNESS = auto()
+    COLOR = auto()
+
+    ALL = BRIGHTNESS | COLOR
+
+    def __str__(self) -> str:
+        """Return a string representation of the attributes."""
+        if self == LightControlAttributes.NONE:
+            return "NONE"
+
+        return "|".join(
+            member.name
+            for member in type(self)
+            if member is not LightControlAttributes.NONE
+            and member in self
+            and member.name is not None
+        )
+
+    def has_any(self) -> bool:
+        """Determine whether any attribute is selected."""
+        return self != LightControlAttributes.NONE
+
+    def has_none(self) -> bool:
+        """Determine whether no attribute is selected."""
+        return self == LightControlAttributes.NONE
+
+    def has_all(self) -> bool:
+        """Determine whether all attributes are selected."""
+        return (self & LightControlAttributes.ALL) == LightControlAttributes.ALL
+
+
 def _split_service_call_data(service_data: ServiceData) -> list[ServiceData]:
     """Splits the service data by the adapted attributes.
 
@@ -145,7 +183,7 @@ class AdaptationData:
     service_call_datas: AsyncGenerator[ServiceData]
     force: bool
     max_length: int
-    which: Literal["brightness", "color", "both"]
+    attributes: LightControlAttributes
     initial_sleep: bool = False
 
     async def next_service_call_data(self) -> ServiceData | None:
@@ -161,7 +199,7 @@ def __str__(self) -> str:
             f"sleep_time={self.sleep_time}, "
             f"force={self.force}, "
             f"max_length={self.max_length}, "
-            f"which={self.which}, "
+            f"attributes={self.attributes}, "
             f"initial_sleep={self.initial_sleep}"
             ")"
         )
@@ -171,20 +209,25 @@ class NoColorOrBrightnessInServiceDataError(Exception):
     """Exception raised when no color or brightness attributes are found in service data."""
 
 
-def _identify_lighting_type(
+def _identify_light_control_attributes(
     service_data: ServiceData,
-) -> Literal["brightness", "color", "both"]:
+) -> LightControlAttributes:
     """Extract the 'which' attribute from the service data."""
     has_brightness = ATTR_BRIGHTNESS in service_data
     has_color = any(attr in service_data for attr in COLOR_ATTRS)
-    if has_brightness and has_color:
-        return "both"
+
+    parameters = LightControlAttributes.NONE
+
     if has_brightness:
-        return "brightness"
+        parameters |= LightControlAttributes.BRIGHTNESS
     if has_color:
-        return "color"
-    msg = f"Invalid service_data, no brightness or color attributes found: {service_data=}"
-    raise NoColorOrBrightnessInServiceDataError(msg)
+        parameters |= LightControlAttributes.COLOR
+
+    if parameters == LightControlAttributes.NONE:
+        msg = f"Invalid service_data, no brightness or color attributes found: {service_data=}"
+        raise NoColorOrBrightnessInServiceDataError(msg)
+
+    return parameters
 
 
 def prepare_adaptation_data(
@@ -220,7 +263,7 @@ def prepare_adaptation_data(
         filter_by_state,
     )
 
-    lighting_type = _identify_lighting_type(service_data)
+    attributes = _identify_light_control_attributes(service_data)
 
     return AdaptationData(
         entity_id=entity_id,
@@ -229,5 +272,58 @@ def prepare_adaptation_data(
         service_call_datas=service_data_iterator,
         force=force,
         max_length=service_datas_length,
-        which=lighting_type,
+        attributes=attributes,
     )
+
+
+def manual_control_event_attribute_to_flags(
+    manual_control_attribute: bool | str,
+) -> LightControlAttributes:
+    """Convert manual control event data to light control attributes."""
+    if isinstance(manual_control_attribute, bool) and manual_control_attribute:
+        return LightControlAttributes.ALL
+    if manual_control_attribute == "brightness":
+        return LightControlAttributes.BRIGHTNESS
+    if manual_control_attribute == "color":
+        return LightControlAttributes.COLOR
+    return LightControlAttributes.NONE
+
+
+def has_brightness_attribute(
+    service_data: ServiceData,
+) -> bool:
+    """Determine whether the service data contains brightness attributes."""
+    return any(attr in BRIGHTNESS_ATTRS for attr in service_data)
+
+
+def has_color_attribute(
+    service_data: ServiceData,
+) -> bool:
+    """Determine whether the service data contains color attributes."""
+    return any(attr in COLOR_ATTRS for attr in service_data)
+
+
+def has_effect_attribute(
+    service_data: ServiceData,
+) -> bool:
+    """Determine whether the service data contains effect attributes."""
+    return ATTR_FLASH in service_data or ATTR_EFFECT in service_data
+
+
+def get_light_control_attributes(
+    service_data: ServiceData,
+) -> LightControlAttributes:
+    """Get the light control attributes affected by the service call data."""
+    parameters = LightControlAttributes.NONE
+
+    if has_brightness_attribute(service_data):
+        parameters |= LightControlAttributes.BRIGHTNESS
+
+    if has_color_attribute(service_data):
+        parameters |= LightControlAttributes.COLOR
+
+    if has_effect_attribute(service_data):
+        parameters |= LightControlAttributes.BRIGHTNESS
+        parameters |= LightControlAttributes.COLOR
+
+    return parameters

custom_components/adaptive_lighting/adaptation_utils.py

@@ -1,6 +1,7 @@
 """Constants for the Adaptive Lighting integration."""
 
 from datetime import timedelta
+from enum import Enum
 from typing import Any
 
 import homeassistant.helpers.config_validation as cv
@@ -16,6 +17,14 @@
 
 DOMAIN = "adaptive_lighting"
 
+
+class TakeOverControlMode(Enum):
+    """Modes for pausing adaptation when control of a light is taken over externally."""
+
+    PAUSE_ALL = "pause_all"
+    PAUSE_CHANGED = "pause_changed"
+
+
 DOCS = {CONF_ENTITY_ID: "Entity ID of the switch. 📝"}
 
 
@@ -34,6 +43,7 @@
     "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."
 )
 
@@ -188,9 +198,19 @@
 
 CONF_TAKE_OVER_CONTROL, DEFAULT_TAKE_OVER_CONTROL = "take_over_control", True
 DOCS[CONF_TAKE_OVER_CONTROL] = (
-    "Disable Adaptive Lighting if another source calls `light.turn_on` while lights "
-    "are on and being adapted. Note that this calls `homeassistant.update_entity` "
-    "every `interval`! 🔒"
+    "Pause adaptation of individual lights and hand over (manual) control to other sources that "
+    "issue `light.turn_on` calls for lights that are on. 🔒"
+)
+
+CONF_TAKE_OVER_CONTROL_MODE, DEFAULT_TAKE_OVER_CONTROL_MODE = (
+    "take_over_control_mode",
+    TakeOverControlMode.PAUSE_ALL.value,
+)
+DOCS[CONF_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."
 )
 
 CONF_TRANSITION, DEFAULT_TRANSITION = "transition", 45
@@ -284,8 +304,9 @@
     "light as being `manually controlled`. 📝",
     CONF_LIGHTS: "entity_id(s) of lights, if not specified, all lights in the "
     "switch are selected. 💡",
-    CONF_MANUAL_CONTROL: 'Whether to add ("true") or remove ("false") the '
-    'light from the "manual_control" list. 🔒',
+    CONF_MANUAL_CONTROL: 'Whether to add ("true") or remove ("false") all '
+    'adapted attributes of the light from the "manual_control" list, or the '
+    "name of an attribute for selective addition. 🔒",
 }
 
 DOCS_APPLY = {
@@ -351,6 +372,20 @@ def int_between(min_int: int, max_int: int) -> vol.All:
     (CONF_BRIGHTNESS_MODE_TIME_DARK, DEFAULT_BRIGHTNESS_MODE_TIME_DARK, int),
     (CONF_BRIGHTNESS_MODE_TIME_LIGHT, DEFAULT_BRIGHTNESS_MODE_TIME_LIGHT, int),
     (CONF_TAKE_OVER_CONTROL, DEFAULT_TAKE_OVER_CONTROL, bool),
+    (
+        CONF_TAKE_OVER_CONTROL_MODE,
+        DEFAULT_TAKE_OVER_CONTROL_MODE,
+        selector.SelectSelector(  # type: ignore[arg-type]
+            selector.SelectSelectorConfig(
+                options=[
+                    TakeOverControlMode.PAUSE_ALL.value,
+                    TakeOverControlMode.PAUSE_CHANGED.value,
+                ],
+                multiple=False,
+                mode=selector.SelectSelectorMode.DROPDOWN,
+            ),
+        ),
+    ),
     (CONF_DETECT_NON_HA_CHANGES, DEFAULT_DETECT_NON_HA_CHANGES, bool),
     (
         CONF_AUTORESET_CONTROL,
@@ -446,6 +481,9 @@ def apply_service_schema(initial_transition: int = 1) -> vol.Schema:
     {
         vol.Optional(CONF_ENTITY_ID): cv.entity_ids,  # type: ignore[arg-type]
         vol.Optional(CONF_LIGHTS, default=[]): cv.entity_ids,  # type: ignore[arg-type]
-        vol.Optional(CONF_MANUAL_CONTROL, default=True): cv.boolean,
+        vol.Optional(CONF_MANUAL_CONTROL, default=True): vol.Any(
+            cv.boolean,
+            vol.In(["brightness", "color"]),
+        ),
     },
 )

custom_components/adaptive_lighting/const.py

@@ -57,7 +57,7 @@ set_manual_control:
           domain: light
           multiple: true
     manual_control:
-      description: Whether to add ("true") or remove ("false") the light from the "manual_control" list. 🔒
+      description: Whether to add ("true") or remove ("false") all adapted attributes of the light from the "manual_control" list, or the name of an attribute for selective addition. 🔒
       example: true
       default: true
       selector:
@@ -220,13 +220,22 @@ change_switch_settings:
       selector:
         time: null
     take_over_control:
-      description: Disable Adaptive Lighting if another source calls `light.turn_on` while lights are on and being adapted. Note that this calls `homeassistant.update_entity` every `interval`! 🔒
+      description: Pause adaptation of individual lights and hand over (manual) control to other sources that issue `light.turn_on` calls for lights that are on. 🔒
       required: false
       example: true
       selector:
         boolean: null
+    take_over_control_mode:
+      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.
+      required: false
+      example: pause_changed
+      selector:
+        select:
+          options:
+          - pause_all
+          - pause_changed
     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. Disable this feature if you encounter such issues.'
+      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
       example: false
       selector:

custom_components/adaptive_lighting/services.yaml

@@ -52,8 +52,9 @@
           "brightness_mode": "brightness_mode",
           "brightness_mode_time_dark": "brightness_mode_time_dark",
           "brightness_mode_time_light": "brightness_mode_time_light",
-          "take_over_control": "take_over_control: Disable Adaptive Lighting if another source calls `light.turn_on` while lights are on and being adapted. Note that this calls `homeassistant.update_entity` every `interval`! 🔒",
-          "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. Disable this feature if you encounter such issues.",
+          "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.",
           "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. If `false`, AL adapts regardless of the presence of color or brightness in the initial `service_data`. Needs `take_over_control` enabled. 🕵️",
@@ -85,6 +86,7 @@
           "brightness_mode": "Brightness mode to use. Possible values are `default`, `linear`, and `tanh` (uses `brightness_mode_time_dark` and `brightness_mode_time_light`). 📈",
           "brightness_mode_time_dark": "(Ignored if `brightness_mode='default'`) The duration in seconds to ramp up/down the brightness before/after sunrise/sunset. 📈📉",
           "brightness_mode_time_light": "(Ignored if `brightness_mode='default'`) The duration in seconds to ramp up/down the brightness after/before sunrise/sunset. 📈📉.",
+          "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.",
           "autoreset_control_seconds": "Automatically reset the manual control after a number of seconds. Set to 0 to disable. ⏲️",
           "send_split_delay": "Delay (ms) between `separate_turn_on_commands` for lights that don't support simultaneous brightness and color setting. ⏲️",
           "adapt_delay": "Wait time (seconds) between light turn on and Adaptive Lighting applying changes. Might help to avoid flickering. ⏲️"
@@ -144,7 +146,7 @@
           "name": "lights"
         },
         "manual_control": {
-          "description": "Whether to add (\"true\") or remove (\"false\") the light from the \"manual_control\" list. 🔒",
+          "description": "Whether to add (\"true\") or remove (\"false\") all adapted attributes of the light from the \"manual_control\" list, or the name of an attribute for selective addition. 🔒",
           "name": "manual_control"
         }
       }
@@ -250,11 +252,15 @@
           "name": "min_sunset_time"
         },
         "take_over_control": {
-          "description": "Disable Adaptive Lighting if another source calls `light.turn_on` while lights are on and being adapted. Note that this calls `homeassistant.update_entity` every `interval`! 🔒",
+          "description": "Pause adaptation of individual lights and hand over (manual) control to other sources that issue `light.turn_on` calls for lights that are on. 🔒",
           "name": "take_over_control"
         },
+        "take_over_control_mode": {
+          "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_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. Disable this feature if you encounter such issues.",
+          "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"
         },
         "transition": {