fix: Resolve RGBIC segment race condition on area-targeted turn_off (#16)

Add asyncio.sleep(0) at the start of segment async_turn_off() to yield
to the event loop, ensuring the main entity's PowerCommand sets the
_pending_power_off flag before any segment checks it.

Author: Tom Lasswell

custom_components/govee/manifest.json

@@ -16,6 +16,6 @@
     "cryptography>=41.0.0"
   ],
   "ssdp": [],
-  "version": "2026.2.10",
+  "version": "2026.2.11",
   "zeroconf": []
 }

custom_components/govee/platforms/grouped_segment.py

@@ -5,6 +5,7 @@
 
 from __future__ import annotations
 
+import asyncio
 import logging
 from typing import Any
 
@@ -131,6 +132,11 @@ async def async_turn_off(self, **kwargs: Any) -> None:
         is already off — prevents race conditions in area-targeted turn_off
         that cause firmware glitches on RGBIC devices (issue #16).
         """
+        # Yield to the event loop so that a concurrent PowerCommand (from the
+        # main light entity in an area-targeted turn_off) gets a chance to set
+        # the _pending_power_off flag before we check it.
+        await asyncio.sleep(0)
+
         device_state = self.coordinator.get_state(self._device_id)
         device_already_off = device_state is not None and not device_state.power_state
         power_off_pending = self.coordinator.is_power_off_pending(self._device_id)

custom_components/govee/platforms/segment.py

@@ -6,6 +6,7 @@
 
 from __future__ import annotations
 
+import asyncio
 import logging
 from typing import Any
 
@@ -131,6 +132,11 @@ async def async_turn_off(self, **kwargs: Any) -> None:
         is already off — prevents race conditions in area-targeted turn_off
         that cause firmware glitches on RGBIC devices (issue #16).
         """
+        # Yield to the event loop so that a concurrent PowerCommand (from the
+        # main light entity in an area-targeted turn_off) gets a chance to set
+        # the _pending_power_off flag before we check it.
+        await asyncio.sleep(0)
+
         device_state = self.coordinator.get_state(self._device_id)
         device_already_off = device_state is not None and not device_state.power_state
         power_off_pending = self.coordinator.is_power_off_pending(self._device_id)

tests/test_grouped_segment.py

@@ -6,12 +6,14 @@
 
 from __future__ import annotations
 
+import asyncio
 from unittest.mock import AsyncMock, MagicMock, patch
 
 import pytest
 
 from custom_components.govee.models import (
     GoveeDeviceState,
+    PowerCommand,
     RGBColor,
     SegmentColorCommand,
 )
@@ -181,3 +183,93 @@ async def test_different_segment_counts(self):
         for segment_count in [1, 4, 8, 16]:
             entity = _make_grouped_segment_entity(segment_count=segment_count)
             assert entity._segment_indices == tuple(range(segment_count))
+
+    @pytest.mark.asyncio
+    async def test_turn_off_yields_before_flag_check(self):
+        """asyncio.sleep(0) is called before checking the power-off flag."""
+        entity = _make_grouped_segment_entity(power_state=True, power_off_pending=False)
+
+        call_order: list[str] = []
+        original_sleep = asyncio.sleep
+
+        async def tracking_sleep(delay: float, *args: object) -> None:
+            if delay == 0:
+                call_order.append("sleep_0")
+            await original_sleep(delay)
+
+        entity.coordinator.is_power_off_pending = MagicMock(
+            side_effect=lambda _: (call_order.append("flag_check"), False)[1]
+        )
+
+        with patch("asyncio.sleep", side_effect=tracking_sleep):
+            await entity.async_turn_off()
+
+        assert call_order == ["sleep_0", "flag_check"]
+
+    @pytest.mark.asyncio
+    async def test_concurrent_turn_off_with_main_entity(self):
+        """Concurrent area turn_off: grouped segment defers to main entity's PowerCommand.
+
+        Simulates asyncio.gather(main_turn_off, grouped_segment_turn_off) and verifies
+        the grouped segment skips its SegmentColorCommand because the main entity sets
+        the power-off flag first.
+        """
+        coordinator = MagicMock()
+        coordinator.last_update_success = True
+
+        state = GoveeDeviceState.create_empty("AA:BB:CC:DD:EE:FF:00:11")
+        state.power_state = True
+        coordinator.get_state = MagicMock(return_value=state)
+
+        # Track commands sent and implement real pending-power-off logic
+        pending_power_off: set[str] = set()
+        commands_sent: list[object] = []
+
+        # Use an event so the mock API call holds the flag until the
+        # segment has had a chance to check it (mirrors real API latency).
+        api_done = asyncio.Event()
+
+        async def mock_control(device_id: str, command: object) -> bool:
+            is_power_off = isinstance(command, PowerCommand) and not command.power_on
+            if is_power_off:
+                pending_power_off.add(device_id)
+            commands_sent.append(command)
+            if is_power_off:
+                await api_done.wait()
+                pending_power_off.discard(device_id)
+            return True
+
+        coordinator.async_control_device = mock_control
+        coordinator.is_power_off_pending = lambda did: did in pending_power_off
+
+        # Build grouped segment entity
+        with patch.object(GoveeGroupedSegmentEntity, "__init__", lambda self, *a, **kw: None):
+            entity = GoveeGroupedSegmentEntity.__new__(GoveeGroupedSegmentEntity)
+        entity.coordinator = coordinator
+        entity._device_id = "AA:BB:CC:DD:EE:FF:00:11"
+        entity._segment_indices = tuple(range(8))
+        entity._is_on = True
+        entity._brightness = 255
+        entity._rgb_color = (255, 255, 255)
+        entity.async_write_ha_state = MagicMock()
+
+        # Simulate main entity turn_off (sends PowerCommand directly)
+        async def main_turn_off() -> None:
+            await coordinator.async_control_device(
+                "AA:BB:CC:DD:EE:FF:00:11",
+                PowerCommand(power_on=False),
+            )
+
+        async def run_both() -> None:
+            await asyncio.gather(main_turn_off(), entity.async_turn_off())
+
+        # Let both coroutines run, then release the API mock
+        task = asyncio.create_task(run_both())
+        await asyncio.sleep(0)  # let gather start both coroutines
+        await asyncio.sleep(0)  # let segment's sleep(0) yield
+        api_done.set()
+        await task
+
+        # Only PowerCommand should have been sent, not SegmentColorCommand
+        assert len(commands_sent) == 1
+        assert isinstance(commands_sent[0], PowerCommand)

tests/test_segment.py

@@ -7,12 +7,14 @@
 
 from __future__ import annotations
 
+import asyncio
 from unittest.mock import AsyncMock, MagicMock, patch
 
 import pytest
 
 from custom_components.govee.models import (
     GoveeDeviceState,
+    PowerCommand,
     RGBColor,
     SegmentColorCommand,
 )
@@ -138,3 +140,93 @@ async def test_turn_off_when_no_state_exists(self):
 
         # When state is None, device_already_off is False, so command should be sent
         entity.coordinator.async_control_device.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_turn_off_yields_before_flag_check(self):
+        """asyncio.sleep(0) is called before checking the power-off flag."""
+        entity = _make_segment_entity(power_state=True, power_off_pending=False)
+
+        call_order: list[str] = []
+        original_sleep = asyncio.sleep
+
+        async def tracking_sleep(delay: float, *args: object) -> None:
+            if delay == 0:
+                call_order.append("sleep_0")
+            await original_sleep(delay)
+
+        entity.coordinator.is_power_off_pending = MagicMock(
+            side_effect=lambda _: (call_order.append("flag_check"), False)[1]
+        )
+
+        with patch("asyncio.sleep", side_effect=tracking_sleep):
+            await entity.async_turn_off()
+
+        assert call_order == ["sleep_0", "flag_check"]
+
+    @pytest.mark.asyncio
+    async def test_concurrent_turn_off_with_main_entity(self):
+        """Concurrent area turn_off: segment defers to main entity's PowerCommand.
+
+        Simulates asyncio.gather(main_turn_off, segment_turn_off) and verifies
+        the segment skips its SegmentColorCommand because the main entity sets
+        the power-off flag first.
+        """
+        coordinator = MagicMock()
+        coordinator.last_update_success = True
+
+        state = GoveeDeviceState.create_empty("AA:BB:CC:DD:EE:FF:00:11")
+        state.power_state = True
+        coordinator.get_state = MagicMock(return_value=state)
+
+        # Track commands sent and implement real pending-power-off logic
+        pending_power_off: set[str] = set()
+        commands_sent: list[object] = []
+
+        # Use an event so the mock API call holds the flag until the
+        # segment has had a chance to check it (mirrors real API latency).
+        api_done = asyncio.Event()
+
+        async def mock_control(device_id: str, command: object) -> bool:
+            is_power_off = isinstance(command, PowerCommand) and not command.power_on
+            if is_power_off:
+                pending_power_off.add(device_id)
+            commands_sent.append(command)
+            if is_power_off:
+                await api_done.wait()
+                pending_power_off.discard(device_id)
+            return True
+
+        coordinator.async_control_device = mock_control
+        coordinator.is_power_off_pending = lambda did: did in pending_power_off
+
+        # Build segment entity
+        with patch.object(GoveeSegmentEntity, "__init__", lambda self, *a, **kw: None):
+            segment = GoveeSegmentEntity.__new__(GoveeSegmentEntity)
+        segment.coordinator = coordinator
+        segment._device_id = "AA:BB:CC:DD:EE:FF:00:11"
+        segment._segment_index = 0
+        segment._is_on = True
+        segment._brightness = 255
+        segment._rgb_color = (255, 255, 255)
+        segment.async_write_ha_state = MagicMock()
+
+        # Simulate main entity turn_off (sends PowerCommand directly)
+        async def main_turn_off() -> None:
+            await coordinator.async_control_device(
+                "AA:BB:CC:DD:EE:FF:00:11",
+                PowerCommand(power_on=False),
+            )
+
+        async def run_both() -> None:
+            await asyncio.gather(main_turn_off(), segment.async_turn_off())
+
+        # Let both coroutines run, then release the API mock
+        task = asyncio.create_task(run_both())
+        await asyncio.sleep(0)  # let gather start both coroutines
+        await asyncio.sleep(0)  # let segment's sleep(0) yield
+        api_done.set()
+        await task
+
+        # Only PowerCommand should have been sent, not SegmentColorCommand
+        assert len(commands_sent) == 1
+        assert isinstance(commands_sent[0], PowerCommand)