Debounce individual colors callback (#800)

* initial commit

* debouncer when not all color values were changed

* add timestamp

* await after_update in final debounce

* test debouncer

* debouncer

Author: farmio

changelog.md

@@ -5,6 +5,7 @@
 ### Devices
 
 - Light: Only send to global switch or brightness address if individual colors are also configured
+- Light: Debounce individual colors callback to mitigate color flicker in visualizations
 
 ## 0.18.12 Add always callback to NumericValue and RawValue 2021-11-01
 

test/devices_tests/light_test.py

@@ -1414,6 +1414,98 @@ async def test_process_individual_color_rgbw(self):
         await light.process(telegram)
         assert light.current_color == (None, 42)
 
+    async def test_process_individual_color_debouncer(self, time_travel):
+        """Test the debouncer for individual color lights."""
+        xknx = XKNX()
+        rgb_callback = AsyncMock()
+        rgbw_callback = AsyncMock()
+
+        rgb_light = Light(
+            xknx,
+            "TestRGBLight",
+            group_address_switch_red="1/1/1",
+            group_address_switch_red_state="1/1/2",
+            group_address_brightness_red="1/1/3",
+            group_address_brightness_red_state="1/1/4",
+            group_address_switch_green="1/1/5",
+            group_address_switch_green_state="1/1/6",
+            group_address_brightness_green="1/1/7",
+            group_address_brightness_green_state="1/1/8",
+            group_address_switch_blue="1/1/9",
+            group_address_switch_blue_state="1/1/10",
+            group_address_brightness_blue="1/1/11",
+            group_address_brightness_blue_state="1/1/12",
+            device_updated_cb=rgb_callback,
+        )
+        rgbw_light = Light(
+            xknx,
+            "TestRGBWLight",
+            group_address_switch="1/1/0",
+            group_address_brightness_red="1/1/3",
+            group_address_brightness_red_state="1/1/4",
+            group_address_brightness_green="1/1/7",
+            group_address_brightness_green_state="1/1/8",
+            group_address_brightness_blue="1/1/11",
+            group_address_brightness_blue_state="1/1/12",
+            group_address_brightness_white="1/1/15",
+            group_address_brightness_white_state="1/1/16",
+            device_updated_cb=rgbw_callback,
+        )
+
+        assert rgb_light.current_color == (None, None)
+        assert rgbw_light.current_color == (None, None)
+
+        red = Telegram(
+            destination_address=GroupAddress("1/1/4"),
+            payload=GroupValueWrite(DPTArray(42)),
+        )
+        green = Telegram(
+            destination_address=GroupAddress("1/1/8"),
+            payload=GroupValueWrite(DPTArray(43)),
+        )
+        blue = Telegram(
+            destination_address=GroupAddress("1/1/12"),
+            payload=GroupValueWrite(DPTArray(44)),
+        )
+        white = Telegram(
+            destination_address=GroupAddress("1/1/16"),
+            payload=GroupValueWrite(DPTArray(50)),
+        )
+
+        await xknx.devices.process(red)
+        rgb_callback.assert_not_called()
+        rgbw_callback.assert_not_called()
+        await xknx.devices.process(green)
+        rgb_callback.assert_not_called()
+        rgbw_callback.assert_not_called()
+        await xknx.devices.process(blue)
+        rgb_callback.assert_called_once()
+        rgbw_callback.assert_not_called()
+        await xknx.devices.process(white)
+        rgbw_callback.assert_called_once()
+
+        assert rgb_light.current_color == ((42, 43, 44), None)
+        assert rgbw_light.current_color == ((42, 43, 44), 50)
+
+        rgb_callback.reset_mock()
+        rgbw_callback.reset_mock()
+        # second time with only 2 telegrams
+        await xknx.devices.process(red)
+        rgb_callback.assert_not_called()
+        rgbw_callback.assert_not_called()
+        await xknx.devices.process(green)
+        rgb_callback.assert_not_called()
+        rgbw_callback.assert_not_called()
+        await time_travel(Light.DEBOUNCE_TIMEOUT / 2)
+        rgb_callback.assert_not_called()
+        rgbw_callback.assert_not_called()
+        await time_travel(Light.DEBOUNCE_TIMEOUT / 2)
+        rgb_callback.assert_called_once()
+        rgbw_callback.assert_called_once()
+
+        assert rgb_light.current_color == ((42, 43, 44), None)
+        assert rgbw_light.current_color == ((42, 43, 44), 50)
+
     async def test_process_hs_color(self):
         """Test process / reading telegrams from telegram queue. Test if color is processed."""
         xknx = XKNX()

xknx/devices/light.py

@@ -12,7 +12,9 @@
 """
 from __future__ import annotations
 
+import asyncio
 from enum import Enum
+from itertools import chain
 import logging
 from typing import TYPE_CHECKING, Any, Awaitable, Callable, Iterator, Tuple, cast
 
@@ -114,6 +116,7 @@ def __eq__(self, other: object) -> bool:
 class Light(Device):
     """Class for managing a light."""
 
+    DEBOUNCE_TIMEOUT = 0.2
     DEFAULT_MIN_KELVIN = 2700  # 370 mireds
     DEFAULT_MAX_KELVIN = 6000  # 166 mireds
 
@@ -266,7 +269,7 @@ def __init__(
             group_address_brightness_red,
             group_address_brightness_red_state,
             sync_state=sync_state,
-            after_update_cb=self.after_update,
+            after_update_cb=self._individual_color_callback_debounce,
         )
 
         self.green = _SwitchAndBrightness(
@@ -278,7 +281,7 @@ def __init__(
             group_address_brightness_green,
             group_address_brightness_green_state,
             sync_state=sync_state,
-            after_update_cb=self.after_update,
+            after_update_cb=self._individual_color_callback_debounce,
         )
 
         self.blue = _SwitchAndBrightness(
@@ -290,7 +293,7 @@ def __init__(
             group_address_brightness_blue,
             group_address_brightness_blue_state,
             sync_state=sync_state,
-            after_update_cb=self.after_update,
+            after_update_cb=self._individual_color_callback_debounce,
         )
 
         self.white = _SwitchAndBrightness(
@@ -302,14 +305,26 @@ def __init__(
             group_address_brightness_white,
             group_address_brightness_white_state,
             sync_state=sync_state,
-            after_update_cb=self.after_update,
+            after_update_cb=self._individual_color_callback_debounce,
         )
 
         self.min_kelvin = min_kelvin
         self.max_kelvin = max_kelvin
+        self._individual_color_debounce_task_name = (
+            f"{id(self)}_individual_color_debounce"
+        )
+        self._individual_color_debounce_telegram_counter: int
+        self._reset_individual_color_debounce_telegrams()
 
     def _iter_remote_values(self) -> Iterator[RemoteValue[Any, Any]]:
         """Iterate the devices RemoteValue classes."""
+        return chain(
+            self._iter_instant_remote_values(),
+            self._iter_debounce_remote_values(),
+        )
+
+    def _iter_instant_remote_values(self) -> Iterator[RemoteValue[Any, Any]]:
+        """Iterate the devices RemoteValue classes calling after_update_cb immediately."""
         yield self.switch
         yield self.brightness
         yield self.color
@@ -319,6 +334,9 @@ def _iter_remote_values(self) -> Iterator[RemoteValue[Any, Any]]:
         yield self.xyy_color
         yield self.tunable_white
         yield self.color_temperature
+
+    def _iter_debounce_remote_values(self) -> Iterator[RemoteValue[Any, Any]]:
+        """Iterate the devices RemoteValue classes debouncing after_update_cb."""
         for color in self._iter_individual_colors():
             yield color.switch
             yield color.brightness
@@ -327,6 +345,36 @@ def _iter_individual_colors(self) -> Iterator[_SwitchAndBrightness]:
         """Iterate the devices individual colors."""
         yield from (self.red, self.green, self.blue, self.white)
 
+    def _reset_individual_color_debounce_telegrams(self) -> None:
+        """Reset individual color debounce telegram counter."""
+        self._individual_color_debounce_telegram_counter = sum(
+            (
+                self.red.switch.initialized or self.red.brightness.initialized,
+                self.green.switch.initialized or self.green.brightness.initialized,
+                self.blue.switch.initialized or self.blue.brightness.initialized,
+                self.white.switch.initialized or self.white.brightness.initialized,
+            )
+        )
+
+    async def _individual_color_callback_debounce(self) -> None:
+        """Run callback after all individual colors were updated or timeout passed."""
+
+        async def debouncer() -> None:
+            await asyncio.sleep(Light.DEBOUNCE_TIMEOUT)
+            self._reset_individual_color_debounce_telegrams()
+            await asyncio.shield(self.after_update())
+
+        self._individual_color_debounce_telegram_counter -= 1
+        if self._individual_color_debounce_telegram_counter > 0:
+            # task registry cancels existing task
+            self.xknx.task_registry.register(
+                self._individual_color_debounce_task_name, debouncer()
+            ).start()
+            return
+        self.xknx.task_registry.unregister(self._individual_color_debounce_task_name)
+        self._reset_individual_color_debounce_telegrams()
+        await self.after_update()
+
     @property
     def supports_brightness(self) -> bool:
         """Return if light supports brightness."""
@@ -549,8 +597,10 @@ async def set_color_temperature(self, color_temperature: int) -> None:
 
     async def process_group_write(self, telegram: "Telegram") -> None:
         """Process incoming and outgoing GROUP WRITE telegram."""
-        for remote_value in self._iter_remote_values():
+        for remote_value in self._iter_instant_remote_values():
             await remote_value.process(telegram)
+        for remote_value in self._iter_debounce_remote_values():
+            await remote_value.process(telegram, always_callback=True)
 
     def __str__(self) -> str:
         """Return object as readable string."""