feat: multi-SKU feature support — sensors, outlets, fan modes, dehumidifier (#114)

Phase A (read-only sensors + dehumidifier setpoint):
- Air-quality index sensor via property::airQuality (H5106/H7124/H7126)
- Filter remaining-life % sensor via property::filterLifeTime (H7124/H7126)
- H7152 dehumidifier: read the real setpoint from range::humidity (was
  showing 0% because it read the Auto modeValue, which the H7152 pins to 80);
  set humidity via RangeCommand. H7150 (Auto-modeValue setpoint) path unchanged
  — gated on GoveeDevice.auto_mode_value_is_setpoint()
- H7152 dehumidifier: expose the Medium gear mode (gearMode Low/Medium/High)

Phase B (new controls):
- H5089 per-outlet switches via socketToggle{N} (live state on poll)
- H1310/H1370 separate Main/Background light toggles via main/backgroundLight
  Toggle (optimistic + RestoreEntity; API returns '' on poll)
- H7124 fan presets: derive Sleep/Auto/Turbo from the work_mode capability
  instead of the hardcoded [Normal, Auto] (backward compatible)

Adds GoveeDeviceState fields (air_quality, filter_life, configured_humidity,
toggles) + parsing, device-model helpers, translations, and 33 tests.
Deferred to follow-ups: nightlight brightness/colour/scene controls,
dynamic_scene::snapshot, PM2.5 (not in the Developer API).

Author: Tom Lasswell

custom_components/govee/const.py

@@ -145,6 +145,9 @@ def descale_centi_temperature(sku: str, value: float) -> float:
 SUFFIX_REFRESH_SCENES: Final = "_refresh_scenes"
 SUFFIX_NIGHT_LIGHT: Final = "_night_light"
 SUFFIX_LIGHT_ZONE: Final = "_light_zone_"
+SUFFIX_SOCKET: Final = "_socket_"
+SUFFIX_MAIN_LIGHT: Final = "_main_light"
+SUFFIX_BACKGROUND_LIGHT: Final = "_background_light"
 SUFFIX_MUSIC_MODE: Final = "_music_mode"
 SUFFIX_MUSIC_SENSITIVITY: Final = "_music_sensitivity"
 SUFFIX_DREAMVIEW: Final = "_dreamview"

custom_components/govee/fan.py

@@ -133,10 +133,28 @@ def __init__(
         # Build supported features based on device capabilities
         features = FanEntityFeature.TURN_ON | FanEntityFeature.TURN_OFF
 
+        # Map preset name -> work_mode value for non-gear, non-Auto top-level
+        # work modes (e.g. H7124's Sleep/Turbo, H7126's Custom). Normal
+        # (gearMode) and Auto are always offered for backward compatibility.
+        self._preset_work_modes: dict[str, int] = {}
         if device.supports_work_mode:
             features |= FanEntityFeature.SET_SPEED
             features |= FanEntityFeature.PRESET_MODE
-            self._attr_preset_modes = FAN_PRESET_MODES
+            extra_presets: list[str] = []
+            for opt in device.get_fan_speed_options():
+                wm = opt.get("work_mode")
+                name = str(opt.get("name", ""))
+                if wm is None or wm in (WORK_MODE_GEAR, WORK_MODE_AUTO) or not name:
+                    continue
+                if name not in self._preset_work_modes:
+                    self._preset_work_modes[name] = int(wm)
+                    extra_presets.append(name)
+            self._attr_preset_modes = FAN_PRESET_MODES + extra_presets
+
+        # Reverse lookup work_mode value -> preset name (issue #114).
+        self._work_mode_to_preset: dict[int, str] = {
+            wm: name for name, wm in self._preset_work_modes.items()
+        }
 
         if device.supports_oscillation:
             features |= FanEntityFeature.OSCILLATE
@@ -178,13 +196,17 @@ def preset_mode(self) -> str | None:
         Maps work_mode to preset:
         - 1 (gearMode) -> Normal
         - 3 (Auto) -> Auto
+        - other top-level work modes (Sleep/Turbo/Custom) -> their own preset
+          (issue #114)
         """
         state = self.device_state
         if state is None or state.work_mode is None:
             return None
 
         if state.work_mode == WORK_MODE_AUTO:
             return PRESET_MODE_AUTO
+        if state.work_mode in self._work_mode_to_preset:
+            return self._work_mode_to_preset[state.work_mode]
         return PRESET_MODE_NORMAL
 
     @property
@@ -247,6 +269,11 @@ async def async_set_preset_mode(self, preset_mode: str) -> None:
         if preset_mode == PRESET_MODE_AUTO:
             work_mode = WORK_MODE_AUTO
             mode_value = 0  # Not used in auto mode
+        elif preset_mode in self._preset_work_modes:
+            # Sleep / Turbo / Custom etc. — top-level work mode, no speed value
+            # (issue #114).
+            work_mode = self._preset_work_modes[preset_mode]
+            mode_value = 0
         else:
             # Normal mode - use current speed or default to medium
             work_mode = WORK_MODE_GEAR

custom_components/govee/humidifier.py

@@ -28,7 +28,8 @@
 
 from .coordinator import GoveeCoordinator
 from .entity import GoveeEntity
-from .models import GoveeDevice, PowerCommand, WorkModeCommand
+from .models import GoveeDevice, PowerCommand, RangeCommand, WorkModeCommand
+from .models.device import INSTANCE_HUMIDITY
 
 _LOGGER = logging.getLogger(__name__)
 
@@ -37,16 +38,21 @@
 # Canonical mode names surfaced to Home Assistant. The set of modes offered
 # by a given device is intersected with these at entity-construction time.
 MODE_LOW = "low"
+MODE_MEDIUM = "medium"
 MODE_HIGH = "high"
 MODE_AUTO = "auto"
 MODE_DRYER = "dryer"
 
+# gearMode sub-option names map onto these canonical HA modes.
+_GEAR_MODES = (MODE_LOW, MODE_MEDIUM, MODE_HIGH)
+
 # Map canonical HA mode name -> (govee_mode_name, fallback_mode_value).
 # govee_mode_name is matched case-insensitively against the device's
 # work_mode and gear options. fallback_mode_value is used when the device's
 # capability doesn't specify a value (e.g. Dryer always sends 0).
 _MODE_ALIASES: dict[str, tuple[str, int]] = {
     MODE_LOW: ("low", 1),
+    MODE_MEDIUM: ("medium", 2),
     MODE_HIGH: ("high", 3),
     MODE_AUTO: ("auto", 0),
     MODE_DRYER: ("dryer", 0),
@@ -100,6 +106,12 @@ def __init__(
         self._attr_min_humidity = min_h
         self._attr_max_humidity = max_h
 
+        # H7150 carries the target in the Auto modeValue; H7152 pins Auto to a
+        # fixed point and carries the setpoint in a separate range::humidity
+        # capability instead. Pick the right read/write path per device (#114).
+        self._auto_modevalue_is_setpoint = device.auto_mode_value_is_setpoint()
+        self._has_humidity_range = device.supports_humidity_range
+
         # Build per-device maps from the capability so the entity honours
         # whatever the device actually advertises (values may vary by SKU).
         self._mode_to_work_mode: dict[str, int] = {}
@@ -113,7 +125,7 @@ def __init__(
             if value is None:
                 continue
             for ha_mode, (alias, _default) in _MODE_ALIASES.items():
-                if name == alias and ha_mode not in (MODE_LOW, MODE_HIGH):
+                if name == alias and ha_mode not in _GEAR_MODES:
                     self._mode_to_work_mode[ha_mode] = int(value)
                     self._work_mode_to_mode[int(value)] = ha_mode
 
@@ -134,7 +146,7 @@ def __init__(
                 value = gear.get("value")
                 if value is None:
                     continue
-                if name in (MODE_LOW, MODE_HIGH):
+                if name in _GEAR_MODES:
                     self._mode_to_work_mode[name] = gear_work_mode
                     self._mode_to_mode_value[name] = int(value)
                     self._gear_mode_values[name] = int(value)
@@ -145,7 +157,7 @@ def __init__(
                 self._mode_to_mode_value.setdefault(ha_mode, _MODE_ALIASES[ha_mode][1])
 
         # Final mode list, ordered for a consistent UI.
-        ordered = [MODE_LOW, MODE_HIGH, MODE_AUTO, MODE_DRYER]
+        ordered = [MODE_LOW, MODE_MEDIUM, MODE_HIGH, MODE_AUTO, MODE_DRYER]
         self._attr_available_modes = [
             m for m in ordered if m in self._mode_to_work_mode
         ]
@@ -178,18 +190,26 @@ def mode(self) -> str | None:
 
     @property
     def target_humidity(self) -> int | None:
-        """Return the target humidity percentage (Auto mode only)."""
+        """Return the target humidity percentage.
+
+        For H7150-style devices the setpoint lives in the Auto-mode modeValue
+        and is only meaningful while in Auto. For H7152-style devices it lives
+        in the persistent ``range::humidity`` capability and applies regardless
+        of mode (issue #114).
+        """
         state = self.device_state
         if state is None:
             return None
-        auto_work_mode = self._mode_to_work_mode.get(MODE_AUTO)
-        if (
-            auto_work_mode is not None
-            and state.work_mode == auto_work_mode
-            and state.mode_value is not None
-        ):
-            return int(state.mode_value)
-        return None
+        if self._auto_modevalue_is_setpoint:
+            auto_work_mode = self._mode_to_work_mode.get(MODE_AUTO)
+            if (
+                auto_work_mode is not None
+                and state.work_mode == auto_work_mode
+                and state.mode_value is not None
+            ):
+                return int(state.mode_value)
+            return None
+        return state.configured_humidity
 
     # --------------------------------------------------------------------- #
     # Commands
@@ -232,14 +252,27 @@ async def async_set_mode(self, mode: str) -> None:
         )
 
     async def async_set_humidity(self, humidity: int) -> None:
-        """Set the target humidity — switches the device into Auto mode."""
+        """Set the target humidity.
+
+        H7150-style devices set it via the Auto-mode modeValue (WorkModeCommand);
+        H7152-style devices set it via the dedicated ``range::humidity``
+        capability (RangeCommand) — issue #114.
+        """
+        clamped = max(self._attr_min_humidity, min(self._attr_max_humidity, humidity))
+
+        if not self._auto_modevalue_is_setpoint and self._has_humidity_range:
+            await self.coordinator.async_control_device(
+                self._device_id,
+                RangeCommand(range_instance=INSTANCE_HUMIDITY, value=int(clamped)),
+            )
+            return
+
         auto_work_mode = self._mode_to_work_mode.get(MODE_AUTO)
         if auto_work_mode is None:
             raise ValueError(
                 f"{self._device.sku} does not support target-humidity (Auto) mode"
             )
 
-        clamped = max(self._attr_min_humidity, min(self._attr_max_humidity, humidity))
         await self.coordinator.async_control_device(
             self._device_id,
             WorkModeCommand(work_mode=auto_work_mode, mode_value=int(clamped)),

custom_components/govee/models/device.py

@@ -108,6 +108,16 @@
 INSTANCE_SENSOR_TEMPERATURE = "sensorTemperature"
 INSTANCE_SENSOR_HUMIDITY = "sensorHumidity"
 
+# Air-quality index + filter remaining-life, exposed as read-only sensors on
+# air-quality monitors (H5106) and air purifiers (H7124/H7126) — issue #114.
+INSTANCE_AIR_QUALITY = "airQuality"
+INSTANCE_FILTER_LIFE = "filterLifeTime"
+
+# Separate main/background light toggles on ceiling-fan lights (H1310/H1370).
+# Distinct from the numeric ``light{N}Toggle`` zone toggles — issue #114.
+INSTANCE_MAIN_LIGHT_TOGGLE = "mainLightToggle"
+INSTANCE_BACKGROUND_LIGHT_TOGGLE = "backgroundLightToggle"
+
 # Device type for stand-alone temperature/humidity sensors.
 DEVICE_TYPE_THERMOMETER = "devices.types.thermometer"
 
@@ -336,6 +346,43 @@ def light_toggle_instances(self) -> list[str]:
                 matches.append((int(m.group(1)), cap.instance))
         return [instance for _, instance in sorted(matches)]
 
+    @property
+    def socket_toggle_instances(self) -> list[str]:
+        """Independently switchable outlets on multi-socket plugs (issue #114).
+
+        Outlet extenders like the H5089 expose each physical socket as a
+        ``socketToggle{N}`` ``devices.capabilities.toggle``. Unlike the
+        main/background light toggles, the API returns a live 0/1 value for
+        these on poll, so the switch reads real state. Returns instance names
+        sorted by socket number, e.g. ``["socketToggle1", "socketToggle2"]``.
+        """
+        pattern = re.compile(r"socketToggle(\d+)")
+        matches: list[tuple[int, str]] = []
+        for cap in self.capabilities:
+            if cap.type != CAPABILITY_TOGGLE:
+                continue
+            m = pattern.fullmatch(cap.instance)
+            if m:
+                matches.append((int(m.group(1)), cap.instance))
+        return [instance for _, instance in sorted(matches)]
+
+    @property
+    def supports_main_light_toggle(self) -> bool:
+        """Check if device exposes a separate main-light toggle (H1310/H1370)."""
+        return any(
+            cap.type == CAPABILITY_TOGGLE and cap.instance == INSTANCE_MAIN_LIGHT_TOGGLE
+            for cap in self.capabilities
+        )
+
+    @property
+    def supports_background_light_toggle(self) -> bool:
+        """Check if device exposes a separate background-light toggle (#114)."""
+        return any(
+            cap.type == CAPABILITY_TOGGLE
+            and cap.instance == INSTANCE_BACKGROUND_LIGHT_TOGGLE
+            for cap in self.capabilities
+        )
+
     @property
     def supports_scenes(self) -> bool:
         """Check if device supports dynamic scenes."""
@@ -459,6 +506,28 @@ def supports_humidity_sensor(self) -> bool:
             for cap in self.capabilities
         )
 
+    @property
+    def supports_air_quality(self) -> bool:
+        """Check if device exposes an airQuality property (H5106, H7124/H7126).
+
+        Read-only index surfaced as an HA sensor — issue #114.
+        """
+        return any(
+            cap.type == CAPABILITY_PROPERTY and cap.instance == INSTANCE_AIR_QUALITY
+            for cap in self.capabilities
+        )
+
+    @property
+    def supports_filter_life(self) -> bool:
+        """Check if device exposes a filterLifeTime property (air purifiers).
+
+        Read-only remaining-life percentage surfaced as an HA sensor — #114.
+        """
+        return any(
+            cap.type == CAPABILITY_PROPERTY and cap.instance == INSTANCE_FILTER_LIFE
+            for cap in self.capabilities
+        )
+
     @property
     def is_thermometer(self) -> bool:
         """Check if device is a stand-alone thermometer/hygrometer."""
@@ -478,6 +547,38 @@ def get_humidity_range(self) -> tuple[int, int]:
                 )
         return (30, 80)
 
+    @property
+    def supports_humidity_range(self) -> bool:
+        """Check if device exposes a range::humidity setpoint capability (#114)."""
+        return any(
+            cap.type == CAPABILITY_RANGE and cap.instance == INSTANCE_HUMIDITY
+            for cap in self.capabilities
+        )
+
+    def auto_mode_value_is_setpoint(self) -> bool:
+        """Whether the Auto work-mode's modeValue carries the humidity setpoint.
+
+        The H7150 advertises Auto ``modeValue`` as a real range (e.g. 30–80) —
+        the target humidity lives there. The H7152 pins Auto ``modeValue`` to a
+        single point (80/80) and carries the real setpoint in the separate
+        ``range::humidity`` capability instead, so for it the modeValue is NOT
+        the setpoint (issue #114). Returns False when there is no Auto modeValue
+        range to read.
+        """
+        for cap in self.capabilities:
+            if cap.type != CAPABILITY_WORK_MODE or cap.instance != INSTANCE_WORK_MODE:
+                continue
+            for f in cap.parameters.get("fields", []):
+                if f.get("fieldName") != "modeValue":
+                    continue
+                for opt in f.get("options", []):
+                    if str(opt.get("name", "")).strip().lower() == "auto":
+                        rng = opt.get("range") or {}
+                        mn, mx = rng.get("min"), rng.get("max")
+                        if mn is not None and mx is not None:
+                            return bool(mn != mx)
+        return False
+
     def get_humidifier_work_mode_options(self) -> list[dict[str, Any]]:
         """Extract top-level work mode options for humidifier/dehumidifier.