fix: Clamp brightness conversion to prevent values exceeding HA range (#24)

The API can return brightness values outside the device's declared
capability range (e.g., H6104 returns 254 on a 0-100 scale), causing
HA to display brightness as 255%. Clamp _device_to_ha_brightness output
to [0, 255] and _ha_to_device_brightness output to [device_min, device_max].

Also include capability parameters in diagnostics output for easier
remote debugging, and add debug logging for API state transitions
(power/brightness changes) to help diagnose stale-state issues.

Author: Tom Lasswell

custom_components/govee/coordinator.py

@@ -473,6 +473,22 @@ async def _fetch_device_state(
             # Clear them when device is turned off (no longer active).
             existing_state = self._states.get(device_id)
             if existing_state:
+                # Log state transitions from API for debugging stale-state issues
+                if existing_state.power_state != state.power_state:
+                    _LOGGER.debug(
+                        "API state change for %s: power %s -> %s (was source=%s)",
+                        device_id,
+                        existing_state.power_state,
+                        state.power_state,
+                        existing_state.source,
+                    )
+                if existing_state.brightness != state.brightness:
+                    _LOGGER.debug(
+                        "API state change for %s: brightness %s -> %s",
+                        device_id,
+                        existing_state.brightness,
+                        state.brightness,
+                    )
                 # Scenes persist on device across power cycles — always preserve
                 if existing_state.active_scene:
                     state.active_scene = existing_state.active_scene

custom_components/govee/diagnostics.py

@@ -49,6 +49,7 @@ async def async_get_config_entry_diagnostics(
                 {
                     "type": cap.type,
                     "instance": cap.instance,
+                    "parameters": cap.parameters,
                 }
                 for cap in device.capabilities
             ],

custom_components/govee/light.py

@@ -261,20 +261,22 @@ def effect(self) -> str | None:
     def _ha_to_device_brightness(self, ha_brightness: int) -> int:
         """Convert HA brightness (0-255) to device range, respecting min."""
         ratio = ha_brightness / HA_BRIGHTNESS_MAX
-        return int(
+        result = int(
             self._brightness_min + ratio * (self._brightness_max - self._brightness_min)
         )
+        return max(self._brightness_min, min(self._brightness_max, result))
 
     def _device_to_ha_brightness(self, device_brightness: int) -> int:
         """Convert device brightness to HA range (0-255), respecting min."""
         device_range = self._brightness_max - self._brightness_min
         if device_range <= 0:
             return 0
-        return int(
+        result = int(
             (device_brightness - self._brightness_min)
             / device_range
             * HA_BRIGHTNESS_MAX
         )
+        return max(0, min(HA_BRIGHTNESS_MAX, result))
 
     async def async_turn_on(self, **kwargs: Any) -> None:
         """Turn the light on with optional parameters."""

tests/test_light.py

@@ -15,9 +15,12 @@
     SceneCommand,
 )
 from custom_components.govee.models.device import (
+    CAPABILITY_COLOR_SETTING,
     CAPABILITY_ON_OFF,
     CAPABILITY_RANGE,
     INSTANCE_BRIGHTNESS,
+    INSTANCE_COLOR_RGB,
+    INSTANCE_COLOR_TEMP,
     INSTANCE_POWER,
 )
 
@@ -449,3 +452,75 @@ def test_color_mode_always_in_supported_modes(
         mock_device_state.color_temp_kelvin = None
         mock_coordinator.get_state.return_value = mock_device_state
         assert entity.color_mode in entity.supported_color_modes
+
+
+class TestBrightnessConversion:
+    """Test brightness conversion between HA (0-255) and device scales."""
+
+    def test_device_to_ha_normal(self, mock_coordinator, mock_light_device):
+        """Test normal brightness conversion from device (0-100) to HA (0-255)."""
+        entity = GoveeLightEntity(mock_coordinator, mock_light_device, enable_scenes=False)
+        # Device range is (0, 100); device=50 → 50% → 127
+        assert entity._device_to_ha_brightness(50) == 127
+        assert entity._device_to_ha_brightness(100) == 255
+        assert entity._device_to_ha_brightness(0) == 0
+
+    def test_device_to_ha_clamped_when_exceeding_range(
+        self, mock_coordinator, mock_light_device
+    ):
+        """Test brightness is clamped to 255 when device value exceeds declared range.
+
+        Regression test for GitHub issue #24: H6104 returns brightness=254
+        from API despite declaring range (0, 100), causing HA to show 255%.
+        """
+        entity = GoveeLightEntity(mock_coordinator, mock_light_device, enable_scenes=False)
+        # Device claims range (0, 100) but API returns 254 → unclamped would be 647
+        assert entity._device_to_ha_brightness(254) == 255
+
+    def test_device_to_ha_clamped_at_zero(self, mock_coordinator, mock_light_device):
+        """Test brightness is clamped to 0 for negative device values."""
+        entity = GoveeLightEntity(mock_coordinator, mock_light_device, enable_scenes=False)
+        assert entity._device_to_ha_brightness(-10) == 0
+
+    def test_ha_to_device_clamped_to_device_range(
+        self, mock_coordinator, mock_light_device
+    ):
+        """Test HA-to-device conversion is clamped to device range."""
+        entity = GoveeLightEntity(mock_coordinator, mock_light_device, enable_scenes=False)
+        # Device range is (0, 100)
+        assert entity._ha_to_device_brightness(255) == 100
+        assert entity._ha_to_device_brightness(0) == 0
+
+    def test_device_to_ha_with_254_range(self, mock_coordinator):
+        """Test brightness conversion with 0-254 device range."""
+        device = GoveeDevice(
+            device_id="TEST:ID:00:00:00:00:00:00",
+            sku="H6104",
+            name="Test Light",
+            device_type="devices.types.light",
+            capabilities=(
+                GoveeCapability(
+                    type=CAPABILITY_ON_OFF, instance=INSTANCE_POWER, parameters={}
+                ),
+                GoveeCapability(
+                    type=CAPABILITY_RANGE,
+                    instance=INSTANCE_BRIGHTNESS,
+                    parameters={"range": {"min": 0, "max": 254}},
+                ),
+                GoveeCapability(
+                    type=CAPABILITY_COLOR_SETTING,
+                    instance=INSTANCE_COLOR_RGB,
+                    parameters={},
+                ),
+                GoveeCapability(
+                    type=CAPABILITY_COLOR_SETTING,
+                    instance=INSTANCE_COLOR_TEMP,
+                    parameters={"range": {"min": 2000, "max": 9000}},
+                ),
+            ),
+            is_group=False,
+        )
+        entity = GoveeLightEntity(mock_coordinator, device, enable_scenes=False)
+        assert entity._device_to_ha_brightness(254) == 255
+        assert entity._device_to_ha_brightness(127) == 127
+        assert entity._device_to_ha_brightness(0) == 0