feat: nightlight controls for outlet extenders & purifiers (#114 Phase C)

Adds a dedicated nightlight light entity + nightlight-scene select for
appliances whose only light is the nightlight (H5089 outlet extender, H7124
air purifier):
- GoveeNightLightEntity: on/off via nightlightToggle (NOT the outlet's
  powerSwitch), brightness + RGB from the shared range/colour capabilities
- GoveeNightlightSceneSelectEntity: named nightlightScene modes (Forest/Ocean/
  ... read per-SKU from the capability, since H5089 is 0-based and H7124 1-based)
- New device helpers has_nightlight_light / supports_nightlight_scene, state
  fields nightlight_scene + nightlightToggle (via generic toggles dict)

BREAKING (H5089 outlet extender): its colour/brightness belong to the
nightlight, not the outlet, so the previously conflated main light entity
(whose on/off toggled the outlet's powerSwitch — refines #59) is replaced by
the nightlight light entity, and the separate night-light on/off switch is
removed for devices that get the richer light entity. Real RGB lights with a
nightlightToggle are unaffected (main light kept, nightlight stays a switch).

Adds 20 tests (53 total for #114).

Author: Tom Lasswell

custom_components/govee/const.py

@@ -156,3 +156,4 @@ def descale_centi_temperature(sku: str, value: float) -> float:
 SUFFIX_HEATER_AUTO_STOP: Final = "_heater_auto_stop"
 SUFFIX_PURIFIER_MODE_SELECT: Final = "_purifier_mode_select"
 SUFFIX_PRESET_SCENE_SELECT: Final = "_preset_scene_select"
+SUFFIX_NIGHTLIGHT_SCENE_SELECT: Final = "_nightlight_scene_select"

custom_components/govee/light.py

@@ -45,7 +45,9 @@
     PowerCommand,
     RGBColor,
     SceneCommand,
+    ToggleCommand,
 )
+from .models.device import INSTANCE_NIGHT_LIGHT
 from .platforms.grouped_segment import GoveeGroupedSegmentEntity
 from .platforms.segment import GoveeSegmentEntity
 
@@ -81,6 +83,13 @@ async def async_setup_entry(
         if device.is_light_device and device.supports_power:
             entities.append(GoveeLightEntity(coordinator, device, enable_scenes))
 
+        # Appliances whose only light is the nightlight (e.g. H5089 outlet
+        # extender, H7124 purifier) get a dedicated nightlight light entity —
+        # on/off via nightlightToggle, brightness + colour from the shared
+        # range/colour capabilities (issue #114).
+        if device.has_nightlight_light and not device.is_group:
+            entities.append(GoveeNightLightEntity(coordinator, device))
+
         # Create segment entities for RGBIC devices based on per-device mode
         if device.supports_segments and device.segment_count > 0:
             # Use per-device mode if set, otherwise default to individual
@@ -399,3 +408,160 @@ async def async_added_to_hass(self) -> None:
             scenes = await self.coordinator.async_get_scenes(self._device_id)
             if scenes:
                 self._build_effect_mapping(scenes)
+
+
+class GoveeNightLightEntity(GoveeEntity, LightEntity):
+    """Dedicated light entity for an appliance's nightlight (issue #114).
+
+    Used for appliances whose only light is the nightlight — the H5089 outlet
+    extender and H7124 air purifier. On/off uses the ``nightlightToggle``
+    capability (NOT the device's ``powerSwitch``, which is the outlet/appliance),
+    while brightness and RGB colour come from the shared
+    ``range::brightness`` / ``color_setting::colorRgb`` capabilities that, on
+    these appliances, belong to the nightlight. The named nightlightScene modes
+    are surfaced by a separate select entity.
+    """
+
+    _attr_translation_key = "govee_nightlight"
+    _attr_icon = "mdi:lightbulb-night"
+
+    def __init__(
+        self,
+        coordinator: GoveeCoordinator,
+        device: GoveeDevice,
+    ) -> None:
+        """Initialize the nightlight entity."""
+        super().__init__(coordinator, device)
+        self._attr_unique_id = f"{device.device_id}_nightlight"
+
+        modes: set[ColorMode] = set()
+        if device.supports_rgb:
+            modes.add(ColorMode.RGB)
+        if device.supports_color_temp:
+            modes.add(ColorMode.COLOR_TEMP)
+        if not modes and device.supports_brightness:
+            modes.add(ColorMode.BRIGHTNESS)
+        if not modes:
+            modes.add(ColorMode.ONOFF)
+        self._attr_supported_color_modes = modes
+
+        self._brightness_min, self._brightness_max = device.brightness_range
+
+    def _ha_to_device_brightness(self, ha_brightness: int) -> int:
+        ratio = ha_brightness / HA_BRIGHTNESS_MAX
+        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:
+        device_range = self._brightness_max - self._brightness_min
+        if device_range <= 0:
+            return 0
+        result = int(
+            (device_brightness - self._brightness_min)
+            / device_range
+            * HA_BRIGHTNESS_MAX
+        )
+        return max(0, min(HA_BRIGHTNESS_MAX, result))
+
+    @property
+    def color_mode(self) -> ColorMode:
+        """Return current colour mode (always within supported_color_modes)."""
+        state = self.device_state
+        modes = self.supported_color_modes or {ColorMode.ONOFF}
+        if state and state.color_temp_kelvin is not None and ColorMode.COLOR_TEMP in modes:
+            return ColorMode.COLOR_TEMP
+        if state and state.color is not None and ColorMode.RGB in modes:
+            return ColorMode.RGB
+        if ColorMode.RGB in modes:
+            return ColorMode.RGB
+        if ColorMode.BRIGHTNESS in modes:
+            return ColorMode.BRIGHTNESS
+        if ColorMode.COLOR_TEMP in modes:
+            return ColorMode.COLOR_TEMP
+        return ColorMode(next(iter(modes)))
+
+    @property
+    def is_on(self) -> bool | None:
+        """Return True if the nightlight is on (live nightlightToggle state)."""
+        state = self.device_state
+        if state is None:
+            return None
+        return state.toggles.get(INSTANCE_NIGHT_LIGHT)
+
+    @property
+    def brightness(self) -> int | None:
+        """Return nightlight brightness (0-255)."""
+        state = self.device_state
+        if state is None:
+            return None
+        return self._device_to_ha_brightness(state.brightness)
+
+    @property
+    def rgb_color(self) -> tuple[int, int, int] | None:
+        """Return nightlight RGB colour."""
+        state = self.device_state
+        if state and state.color:
+            return state.color.as_tuple
+        return None
+
+    @property
+    def color_temp_kelvin(self) -> int | None:
+        """Return nightlight colour temperature in Kelvin."""
+        state = self.device_state
+        return state.color_temp_kelvin if state and state.color_temp_kelvin else None
+
+    @property
+    def min_color_temp_kelvin(self) -> int:
+        """Return minimum colour temperature in Kelvin."""
+        temp_range = self._device.color_temp_range
+        return temp_range.min_kelvin if temp_range else 2000
+
+    @property
+    def max_color_temp_kelvin(self) -> int:
+        """Return maximum colour temperature in Kelvin."""
+        temp_range = self._device.color_temp_range
+        return temp_range.max_kelvin if temp_range else 9000
+
+    async def _set_toggle(self, enabled: bool) -> bool:
+        success = await self.coordinator.async_control_device(
+            self._device_id,
+            ToggleCommand(toggle_instance=INSTANCE_NIGHT_LIGHT, enabled=enabled),
+        )
+        if success:
+            state = self.device_state
+            if state is not None:
+                state.toggles[INSTANCE_NIGHT_LIGHT] = enabled
+            self.async_write_ha_state()
+        return success
+
+    async def async_turn_on(self, **kwargs: Any) -> None:
+        """Turn the nightlight on with optional brightness/colour."""
+        if ATTR_BRIGHTNESS in kwargs:
+            device_brightness = self._ha_to_device_brightness(kwargs[ATTR_BRIGHTNESS])
+            await self.coordinator.async_control_device(
+                self._device_id, BrightnessCommand(brightness=device_brightness)
+            )
+
+        if ATTR_RGB_COLOR in kwargs:
+            r, g, b = kwargs[ATTR_RGB_COLOR]
+            await self.coordinator.async_control_device(
+                self._device_id, ColorCommand(color=RGBColor(r=r, g=g, b=b))
+            )
+
+        if ATTR_COLOR_TEMP_KELVIN in kwargs:
+            await self.coordinator.async_control_device(
+                self._device_id, ColorTempCommand(kelvin=kwargs[ATTR_COLOR_TEMP_KELVIN])
+            )
+
+        has_attribute = any(
+            k in kwargs
+            for k in (ATTR_BRIGHTNESS, ATTR_RGB_COLOR, ATTR_COLOR_TEMP_KELVIN)
+        )
+        if not has_attribute or not self.is_on:
+            await self._set_toggle(True)
+
+    async def async_turn_off(self, **kwargs: Any) -> None:
+        """Turn the nightlight off."""
+        await self._set_toggle(False)

custom_components/govee/models/device.py

@@ -66,6 +66,10 @@
 INSTANCE_SCENE = "lightScene"
 INSTANCE_DIY = "diyScene"
 INSTANCE_NIGHT_LIGHT = "nightlightToggle"
+# Named light+colour scenes for an appliance's nightlight (H5089/H7124) — a
+# devices.capabilities.mode whose options carry the localized name + integer id
+# the control payload uses (issue #114).
+INSTANCE_NIGHTLIGHT_SCENE = "nightlightScene"
 INSTANCE_GRADUAL_ON = "gradientToggle"
 INSTANCE_TIMER = "timer"
 INSTANCE_OSCILLATION = "oscillationToggle"
@@ -933,6 +937,12 @@ def is_light_device(self) -> bool:
             or self.is_aroma_diffuser
         ):
             return False
+        # An outlet extender whose colour belongs to a nightlight (it also
+        # exposes nightlightToggle) is represented by a dedicated nightlight
+        # light entity, not a conflated main light on the outlet's powerSwitch
+        # (issue #114, refines #59).
+        if self.is_plug and self.supports_night_light:
+            return False
         if self.is_plug and not (self.supports_rgb or self.supports_color_temp):
             return False
         return (
@@ -941,6 +951,38 @@ def is_light_device(self) -> bool:
             or self.supports_color_temp
         )
 
+    @property
+    def has_nightlight_light(self) -> bool:
+        """Whether the device's nightlight warrants a full light entity (#114).
+
+        True for appliances whose only light is the nightlight (e.g. the H5089
+        outlet extender, H7124 purifier): the nightlight has on/off
+        (nightlightToggle) plus brightness/colour, so it maps onto a light
+        entity. A real light (is_light_device) owns brightness/colour for its
+        main light, so its nightlight stays a simple on/off switch.
+        """
+        if self.is_light_device:
+            return False
+        return self.supports_night_light and (
+            self.supports_brightness or self.supports_rgb or self.supports_color_temp
+        )
+
+    @property
+    def supports_nightlight_scene(self) -> bool:
+        """Check if device exposes a nightlightScene mode capability (#114)."""
+        return any(
+            cap.type == CAPABILITY_MODE and cap.instance == INSTANCE_NIGHTLIGHT_SCENE
+            for cap in self.capabilities
+        )
+
+    def get_nightlight_scene_options(self) -> list[dict[str, Any]]:
+        """Extract nightlightScene options as {"name", "value"} dicts (#114)."""
+        for cap in self.capabilities:
+            if cap.type == CAPABILITY_MODE and cap.instance == INSTANCE_NIGHTLIGHT_SCENE:
+                options: list[dict[str, Any]] = cap.parameters.get("options", [])
+                return options
+        return []
+
     @property
     def brightness_range(self) -> tuple[int, int]:
         """Get brightness range from capability. Default (0, 100)."""

custom_components/govee/models/state.py

@@ -181,6 +181,10 @@ class GoveeDeviceState:
     # named scene. Often "" on poll, so the select is optimistic like HDMI/scene.
     preset_scene: int | None = None
 
+    # Appliance nightlight scene (H5089/H7124, issue #114): integer id of the
+    # active named nightlightScene mode option.
+    nightlight_scene: int | None = None
+
     # DreamView (Movie Mode) state
     dreamview_enabled: bool | None = None  # DreamView on/off
 
@@ -323,6 +327,11 @@ def update_from_api(self, data: dict[str, Any]) -> None:
                     self.hdmi_source = _coerce_int(value)
                 elif instance == "presetScene":
                     self.preset_scene = _coerce_int(value)
+                elif instance == "nightlightScene":
+                    # Appliance nightlight named scene (H5089/H7124, #114).
+                    parsed_ns = _coerce_int(value)
+                    if parsed_ns is not None:
+                        self.nightlight_scene = parsed_ns
 
             elif cap_type == "devices.capabilities.property":
                 # Read-only sensor properties on devices like H5109 and

custom_components/govee/select.py

@@ -25,6 +25,7 @@
     SUFFIX_HDMI_SOURCE_SELECT,
     SUFFIX_HEATER_FAN_SPEED,
     SUFFIX_MUSIC_MODE_SELECT,
+    SUFFIX_NIGHTLIGHT_SCENE_SELECT,
     SUFFIX_PRESET_SCENE_SELECT,
     SUFFIX_PURIFIER_MODE_SELECT,
     SUFFIX_SCENE_SELECT,
@@ -40,6 +41,7 @@
 )
 from .models.device import (
     INSTANCE_HDMI_SOURCE,
+    INSTANCE_NIGHTLIGHT_SCENE,
     INSTANCE_PRESET_SCENE,
     INSTANCE_PURIFIER_MODE,
 )
@@ -216,6 +218,24 @@ async def async_setup_entry(
                     len(preset_scene_options),
                 )
 
+        # Nightlight scene selector for appliances with a nightlight (H5089
+        # outlet extender, H7124 purifier) — issue #114.
+        if device.supports_nightlight_scene:
+            nightlight_scene_options = device.get_nightlight_scene_options()
+            if nightlight_scene_options:
+                entities.append(
+                    GoveeNightlightSceneSelectEntity(
+                        coordinator=coordinator,
+                        device=device,
+                        options=nightlight_scene_options,
+                    )
+                )
+                _LOGGER.debug(
+                    "Created nightlight scene select entity for %s with %d scenes",
+                    device.name,
+                    len(nightlight_scene_options),
+                )
+
     async_add_entities(entities)
     _LOGGER.debug("Set up %d Govee scene select entities", len(entities))
 
@@ -635,6 +655,71 @@ async def async_select_option(self, option: str) -> None:
             )
 
 
+class GoveeNightlightSceneSelectEntity(GoveeEntity, SelectEntity):
+    """Govee nightlight scene select entity (issue #114).
+
+    Dropdown of the named ``nightlightScene`` modes (e.g. Forest, Ocean) on
+    appliances with a nightlight — the H5089 outlet extender and H7124 air
+    purifier.
+    """
+
+    _attr_translation_key = "govee_nightlight_scene_select"
+    _attr_icon = "mdi:weather-night"
+
+    def __init__(
+        self,
+        coordinator: GoveeCoordinator,
+        device: GoveeDevice,
+        options: list[dict[str, Any]],
+    ) -> None:
+        """Initialize the nightlight scene select entity."""
+        super().__init__(coordinator, device)
+
+        self._option_map: dict[str, int] = {}
+        option_names: list[str] = []
+        for opt in options:
+            name = opt.get("name", "")
+            value = opt.get("value")
+            if name and value is not None:
+                self._option_map[name] = value
+                option_names.append(name)
+
+        self._attr_options = option_names
+        self._attr_unique_id = (
+            f"{device.device_id}{SUFFIX_NIGHTLIGHT_SCENE_SELECT}"
+        )
+
+    @property
+    def current_option(self) -> str | None:
+        """Return the active nightlight scene name from state."""
+        state = self.coordinator.get_state(self._device_id)
+        if state and state.nightlight_scene is not None:
+            for name, value in self._option_map.items():
+                if value == state.nightlight_scene:
+                    return name
+        return self._attr_options[0] if self._attr_options else None
+
+    async def async_select_option(self, option: str) -> None:
+        """Handle nightlight scene selection."""
+        value = self._option_map.get(option)
+        if value is None:
+            _LOGGER.warning("Unknown nightlight scene option: %s", option)
+            return
+
+        success = await self.coordinator.async_control_device(
+            self._device_id,
+            ModeCommand(mode_instance=INSTANCE_NIGHTLIGHT_SCENE, value=value),
+        )
+        if success:
+            self.async_write_ha_state()
+            _LOGGER.debug(
+                "Set nightlight scene '%s' (value=%d) on %s",
+                option,
+                value,
+                self._device.name,
+            )
+
+
 class GoveeMusicModeSelectEntity(GoveeEntity, SelectEntity):
     """Govee music mode select entity.