Merge pull request #330 from plugwise/mdi_sense

Add sense hysteresis based switch action

Author: dirixmjm

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.45.0 - 2025-09-03
+
+- PR [330](https://github.com/plugwise/python-plugwise-usb/pull/330): Add sense hysteresis based switch action
+
 ## 0.44.14 - 2025-08-31
 
 - PR [329](https://github.com/plugwise/python-plugwise-usb/pull/329): Improve EnergyLogs caching: store only data from MAX_LOG_HOURS (24)

plugwise_usb/api.py

@@ -55,6 +55,7 @@ class NodeFeature(str, Enum):
     RELAY_LOCK = "relay_lock"
     SWITCH = "switch"
     SENSE = "sense"
+    SENSE_HYSTERESIS = "sense_hysteresis"
     TEMPERATURE = "temperature"
 
 
@@ -86,6 +87,7 @@ class NodeType(Enum):
     NodeFeature.MOTION_CONFIG,
     NodeFeature.TEMPERATURE,
     NodeFeature.SENSE,
+    NodeFeature.SENSE_HYSTERESIS,
     NodeFeature.SWITCH,
 )
 
@@ -260,12 +262,48 @@ class EnergyStatistics:
     day_production_reset: datetime | None = None
 
 
+@dataclass(frozen=True)
+class SenseHysteresisConfig:
+    """Configuration of sense hysteresis switch.
+
+    Description: Configuration settings for sense hysteresis.
+                 When value is scheduled to be changed the returned value is the optimistic value
+
+    Attributes:
+        humidity_enabled: bool | None: enable humidity hysteresis
+        humidity_upper_bound: float | None: upper humidity switching threshold (%RH)
+        humidity_lower_bound: float | None: lower humidity switching threshold (%RH)
+        humidity_direction: bool | None: True = switch ON when humidity rises; False = switch OFF when humidity rises
+        temperature_enabled: bool | None: enable temperature hysteresis
+        temperature_upper_bound: float | None: upper temperature switching threshold (°C)
+        temperature_lower_bound: float | None: lower temperature switching threshold (°C)
+        temperature_direction: bool | None: True = switch ON when temperature rises; False = switch OFF when temperature rises
+        dirty: bool: Settings changed, device update pending
+
+    Notes:
+            Disabled sentinel values are hardware-specific (temperature=17099 for -1°C, humidity=2621 for -1%) and are handled in the node layer; the public API exposes floats in SI units.
+
+    """
+
+    humidity_enabled: bool | None = None
+    humidity_upper_bound: float | None = None
+    humidity_lower_bound: float | None = None
+    humidity_direction: bool | None = None
+    temperature_enabled: bool | None = None
+    temperature_upper_bound: float | None = None
+    temperature_lower_bound: float | None = None
+    temperature_direction: bool | None = None
+    dirty: bool = False
+
+
 @dataclass
 class SenseStatistics:
     """Sense statistics collection."""
 
     temperature: float | None = None
     humidity: float | None = None
+    temperature_hysteresis_state: bool | None = None
+    humidity_hysteresis_state: bool | None = None
 
 
 class PlugwiseNode(Protocol):

plugwise_usb/messages/requests.py

@@ -1404,6 +1404,57 @@ async def send(self) -> NodeAckResponse | None:
         )
 
 
+class SenseConfigureHysteresisRequest(PlugwiseRequest):
+    """Configure a Sense Hysteresis Switching Setting.
+
+    temp_hum : configure temperature True or humidity False
+    lower_bound : lower bound of the hysteresis
+    upper_bound : upper bound of the hysteresis
+    direction   : Switch active high or active low
+
+    Response message: NodeAckResponse
+    """
+
+    _identifier = b"0104"
+    _reply_identifier = b"0100"
+
+    # pylint: disable=too-many-arguments
+    def __init__(  # noqa: PLR0913
+        self,
+        send_fn: Callable[[PlugwiseRequest, bool], Awaitable[PlugwiseResponse | None]],
+        mac: bytes,
+        temp_hum: bool,
+        lower_bound: int,
+        upper_bound: int,
+        direction: bool,
+    ):
+        """Initialize SenseConfigureHysteresisRequest message object."""
+        super().__init__(send_fn, mac)
+        temp_hum_value = Int(1 if temp_hum else 0, length=2)
+        lower_bound_value = Int(lower_bound, length=4)
+        upper_bound_value = Int(upper_bound, length=4)
+        direction_value_1 = Int(1 if direction else 0, length=2)
+        direction_value_2 = Int(0 if direction else 1, length=2)
+        self._args += [
+            temp_hum_value,
+            lower_bound_value,
+            direction_value_1,
+            upper_bound_value,
+            direction_value_2,
+        ]
+
+    async def send(self) -> NodeAckResponse | None:
+        """Send request."""
+        result = await self._send_request()
+        if isinstance(result, NodeAckResponse):
+            return result
+        if result is None:
+            return None
+        raise MessageError(
+            f"Invalid response message. Received {result.__class__.__name__}, expected NodeAckResponse"
+        )
+
+
 class ScanLightCalibrateRequest(PlugwiseRequest):
     """Calibrate light sensitivity.
 

plugwise_usb/nodes/helpers/firmware.py

@@ -159,6 +159,7 @@ class SupportedVersions(NamedTuple):
     NodeFeature.CIRCLEPLUS: 2.0,
     NodeFeature.INFO: 2.0,
     NodeFeature.SENSE: 2.0,
+    NodeFeature.SENSE_HYSTERESIS: 2.0,
     NodeFeature.TEMPERATURE: 2.0,
     NodeFeature.HUMIDITY: 2.0,
     NodeFeature.ENERGY: 2.0,

plugwise_usb/nodes/scan.py

@@ -430,21 +430,13 @@ async def _run_awake_tasks(self) -> None:
             await self._scan_calibrate_light()
         await self.publish_feature_update_to_subscribers(
             NodeFeature.MOTION_CONFIG,
-            self._motion_config,
+            self.motion_config,
         )
 
     async def _configure_scan_task(self) -> bool:
         """Configure Scan device settings. Returns True if successful."""
         if not self._motion_config.dirty:
             return True
-        if not await self.scan_configure():
-            _LOGGER.debug("Motion Configuration for %s failed", self._mac_in_str)
-            return False
-        return True
-
-    async def scan_configure(self) -> bool:
-        """Configure Scan device settings. Returns True if successful."""
-        # Default to medium
         request = ScanConfigureRequest(
             self._send,
             self._mac_in_bytes,
@@ -485,7 +477,7 @@ async def _scan_configure_update(self) -> None:
         await gather(
             self.publish_feature_update_to_subscribers(
                 NodeFeature.MOTION_CONFIG,
-                self._motion_config,
+                self.motion_config,
             ),
             self.save_cache(),
         )
@@ -542,7 +534,7 @@ async def get_state(self, features: tuple[NodeFeature]) -> dict[NodeFeature, Any
                 case NodeFeature.MOTION:
                     states[NodeFeature.MOTION] = self._motion_state
                 case NodeFeature.MOTION_CONFIG:
-                    states[NodeFeature.MOTION_CONFIG] = self._motion_config
+                    states[NodeFeature.MOTION_CONFIG] = self.motion_config
                 case _:
                     state_result = await super().get_state((feature,))
                     if feature in state_result: