store MotionSensitivity enum which makes communication to HA easier

CHANGELOG.md

@@ -1,7 +1,9 @@
 # Changelog
 
-## Ongoing
+## v0.44.12 - 2025-08-24
 
+- PR [323](https://github.com/plugwise/python-plugwise-usb/pull/323): Motion Sensitivity to use named levels (Off/Medium/High) instead of numeric values, add light sensitivity calibration on wake-up for scan devices.
+- PR [322](https://github.com/plugwise/python-plugwise-usb/pull/322): Improve Circle+ load function to align to Circle load function
 - PR [321](https://github.com/plugwise/python-plugwise-usb/pull/321): Catch error reported in Issue [#312](https://github.com/plugwise/plugwise_usb-beta/issues/312)
 - PR [319](https://github.com/plugwise/python-plugwise-usb/pull/319): Replace unclear warning message when a node is not online, also various small improvements suggested by CRAI.
 - PR [312](https://github.com/plugwise/python-plugwise-usb/pull/312): properly propagate configuration changes and initialize to available on first node wakeup

plugwise_usb/api.py

@@ -233,14 +233,14 @@ class MotionConfig:
     Attributes:
         reset_timer: int | None: Motion reset timer in minutes before the motion detection is switched off.
         daylight_mode: bool | None: Motion detection when light level is below threshold.
-        sensitivity_level: int | None: Motion sensitivity level.
+        sensitivity_level: MotionSensitivity | None: Motion sensitivity level.
         dirty: bool: Settings changed, device update pending
 
     """
 
     daylight_mode: bool | None = None
     reset_timer: int | None = None
-    sensitivity_level: int | None = None
+    sensitivity_level: MotionSensitivity | None = None
     dirty: bool = False
 
 
@@ -678,6 +678,13 @@ async def set_motion_sensitivity_level(self, level: MotionSensitivity) -> bool:
 
         """
 
+    async def scan_calibrate_light(self) -> bool:
+        """Request to calibration light sensitivity of Scan device.
+
+        Description:
+            Request to calibration light sensitivity of Scan device.
+        """
+
     async def set_relay_init(self, state: bool) -> bool:
         """Change the initial state of the relay.
 

plugwise_usb/nodes/scan.py

@@ -19,7 +19,7 @@
 )
 from ..connection import StickController
 from ..constants import MAX_UINT_2
-from ..exceptions import MessageError, NodeError, NodeTimeout
+from ..exceptions import MessageError, NodeError
 from ..messages.requests import ScanConfigureRequest, ScanLightCalibrateRequest
 from ..messages.responses import (
     NODE_SWITCH_GROUP_ID,
@@ -86,7 +86,7 @@ def __init__(
 
         self._motion_state = MotionState()
         self._motion_config = MotionConfig()
-
+        self._scan_calibrate_light_scheduled = False
         self._configure_daylight_mode_task: Task[Coroutine[Any, Any, None]] | None = (
             None
         )
@@ -198,7 +198,7 @@ def _reset_timer_from_cache(self) -> int | None:
             return int(reset_timer)
         return None
 
-    def _sensitivity_level_from_cache(self) -> int | None:
+    def _sensitivity_level_from_cache(self) -> MotionSensitivity | None:
         """Load sensitivity level from cache."""
         if (
             sensitivity_level := self._get_cache(
@@ -274,7 +274,7 @@ def reset_timer(self) -> int:
         return DEFAULT_RESET_TIMER
 
     @property
-    def sensitivity_level(self) -> int:
+    def sensitivity_level(self) -> MotionSensitivity:
         """Sensitivity level of motion sensor."""
         if self._motion_config.sensitivity_level is not None:
             return self._motion_config.sensitivity_level
@@ -326,13 +326,13 @@ async def set_motion_reset_timer(self, minutes: int) -> bool:
         await self._scan_configure_update()
         return True
 
-    async def set_motion_sensitivity_level(self, level: int) -> bool:
+    async def set_motion_sensitivity_level(self, level: MotionSensitivity) -> bool:
         """Configure the motion sensitivity level."""
         _LOGGER.debug(
             "set_motion_sensitivity_level | Device %s | %s -> %s",
             self.name,
-            self._motion_config.sensitivity_level,
-            level,
+            self.sensitivity_level.name,
+            level.name,
         )
         if self._motion_config.sensitivity_level == level:
             return False
@@ -426,6 +426,8 @@ async def _run_awake_tasks(self) -> None:
         await super()._run_awake_tasks()
         if self._motion_config.dirty:
             await self._configure_scan_task()
+        if self._scan_calibrate_light_scheduled:
+            await self._scan_calibrate_light()
         await self.publish_feature_update_to_subscribers(
             NodeFeature.MOTION_CONFIG,
             self._motion_config,
@@ -446,9 +448,9 @@ async def scan_configure(self) -> bool:
         request = ScanConfigureRequest(
             self._send,
             self._mac_in_bytes,
-            self._motion_config.reset_timer,
-            self._motion_config.sensitivity_level,
-            self._motion_config.daylight_mode,
+            self.reset_timer,
+            self.sensitivity_level.value,
+            self.daylight_mode,
         )
         if (response := await request.send()) is None:
             _LOGGER.warning(
@@ -473,17 +475,13 @@ async def scan_configure(self) -> bool:
 
     async def _scan_configure_update(self) -> None:
         """Push scan configuration update to cache."""
-        self._set_cache(
-            CACHE_SCAN_CONFIG_RESET_TIMER, str(self._motion_config.reset_timer)
-        )
+        self._set_cache(CACHE_SCAN_CONFIG_RESET_TIMER, self.reset_timer)
         self._set_cache(
             CACHE_SCAN_CONFIG_SENSITIVITY,
-            str(MotionSensitivity(self._motion_config.sensitivity_level).name),
+            self._motion_config.sensitivity_level.name,
         )
-        self._set_cache(
-            CACHE_SCAN_CONFIG_DAYLIGHT_MODE, str(self._motion_config.daylight_mode)
-        )
-        self._set_cache(CACHE_SCAN_CONFIG_DIRTY, str(self._motion_config.dirty))
+        self._set_cache(CACHE_SCAN_CONFIG_DAYLIGHT_MODE, self.daylight_mode)
+        self._set_cache(CACHE_SCAN_CONFIG_DIRTY, self.dirty)
         await gather(
             self.publish_feature_update_to_subscribers(
                 NodeFeature.MOTION_CONFIG,
@@ -493,18 +491,36 @@ async def _scan_configure_update(self) -> None:
         )
 
     async def scan_calibrate_light(self) -> bool:
+        """Schedule light sensitivity calibration of Scan device.
+
+        Returns True when scheduling was newly activated;
+                False if it was already scheduled.
+        """
+        if self._scan_calibrate_light_scheduled:
+            return False
+        self._scan_calibrate_light_scheduled = True
+        return True
+
+    async def _scan_calibrate_light(self) -> bool:
         """Request to calibration light sensitivity of Scan device."""
         request = ScanLightCalibrateRequest(self._send, self._mac_in_bytes)
-        if (response := await request.send()) is not None:
-            if (
-                response.node_ack_type
-                == NodeAckResponseType.SCAN_LIGHT_CALIBRATION_ACCEPTED
-            ):
-                return True
+        response = await request.send()
+        if response is None:
+            _LOGGER.warning(
+                "No response from %s to light calibration request",
+                self.name,
+            )
             return False
-        raise NodeTimeout(
-            f"No response from Scan device {self.mac} "
-            + "to light calibration request."
+        if (
+            response.node_ack_type
+            == NodeAckResponseType.SCAN_LIGHT_CALIBRATION_ACCEPTED
+        ):
+            self._scan_calibrate_light_scheduled = False
+            return True
+        _LOGGER.warning(
+            "Unexpected ack type %s for light calibration on %s",
+            response.node_ack_type,
+            self.name,
         )
 
     async def get_state(self, features: tuple[NodeFeature]) -> dict[NodeFeature, Any]:

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name            = "plugwise_usb"
-version         = "0.44.12a1"
+version         = "0.44.12"
 license         = "MIT"
 keywords        = ["home", "automation", "plugwise", "module", "usb"]
 classifiers     = [

tests/test_usb.py

@@ -1494,7 +1494,7 @@ async def test_creating_request_messages(self) -> None:
             self.dummy_fn,
             b"1111222233334444",
             5,  # Delay in minutes when signal is send when no motion is detected
-            30,  # Sensitivity of Motion sensor (High, Medium, Off)
+            pw_api.MotionSensitivity.MEDIUM,  # Sensitivity of Motion sensor (High, Medium, Off)
             False,  # Daylight override to only report motion when lightlevel is below calibrated level
         )
         assert (
@@ -1834,7 +1834,7 @@ async def load_callback(event: pw_api.NodeEvent, mac: str) -> None:  # type: ign
             await test_node.set_motion_daylight_mode(True)
 
         with pytest.raises(pw_exceptions.NodeError):
-            await test_node.set_motion_sensitivity_level(20)
+            await test_node.set_motion_sensitivity_level(pw_api.MotionSensitivity.HIGH)
 
         with pytest.raises(pw_exceptions.NodeError):
             await test_node.set_motion_reset_timer(5)
@@ -1865,7 +1865,7 @@ async def load_callback(event: pw_api.NodeEvent, mac: str) -> None:  # type: ign
             await test_node.set_motion_daylight_mode(True)
 
         with pytest.raises(pw_exceptions.FeatureError):
-            await test_node.set_motion_sensitivity_level(20)
+            await test_node.set_motion_sensitivity_level(pw_api.MotionSensitivity.HIGH)
 
         with pytest.raises(pw_exceptions.FeatureError):
             await test_node.set_motion_reset_timer(5)
@@ -1892,7 +1892,7 @@ async def load_callback(event: pw_api.NodeEvent, mac: str) -> None:  # type: ign
         with pytest.raises(NotImplementedError):
             await test_node.set_motion_daylight_mode(True)
         with pytest.raises(NotImplementedError):
-            await test_node.set_motion_sensitivity_level(20)
+            await test_node.set_motion_sensitivity_level(pw_api.MotionSensitivity.HIGH)
         with pytest.raises(NotImplementedError):
             await test_node.set_motion_reset_timer(5)
 
@@ -2240,12 +2240,18 @@ async def load_callback(event: pw_api.NodeEvent, mac: str) -> None:  # type: ign
         assert test_scan.motion_config.daylight_mode
 
         # test motion sensitivity level
-        assert test_scan.sensitivity_level == 30
-        assert test_scan.motion_config.sensitivity_level == 30
-        assert not await test_scan.set_motion_sensitivity_level(30)
+        assert test_scan.sensitivity_level == pw_api.MotionSensitivity.MEDIUM
+        assert (
+            test_scan.motion_config.sensitivity_level == pw_api.MotionSensitivity.MEDIUM
+        )
+        assert not await test_scan.set_motion_sensitivity_level(
+            pw_api.MotionSensitivity.MEDIUM
+        )
 
         assert not test_scan.motion_config.dirty
-        assert await test_scan.set_motion_sensitivity_level(20)
+        assert await test_scan.set_motion_sensitivity_level(
+            pw_api.MotionSensitivity.HIGH
+        )
         assert test_scan.motion_config.dirty
         awake_response4 = pw_responses.NodeAwakeResponse()
         awake_response4.deserialize(
@@ -2257,8 +2263,10 @@ async def load_callback(event: pw_api.NodeEvent, mac: str) -> None:  # type: ign
         await test_scan._awake_response(awake_response4)  # pylint: disable=protected-access
         await asyncio.sleep(0.001)  # Ensure time for task to be executed
         assert not test_scan.motion_config.dirty
-        assert test_scan.sensitivity_level == 20
-        assert test_scan.motion_config.sensitivity_level == 20
+        assert test_scan.sensitivity_level == pw_api.MotionSensitivity.HIGH
+        assert (
+            test_scan.motion_config.sensitivity_level == pw_api.MotionSensitivity.HIGH
+        )
 
         # scan with cache enabled
         mock_stick_controller.send_response = None