Improve Z-Wave JS masked PIN and all-zeros handling (#859)

Author: raman325

custom_components/lock_code_manager/coordinator.py

@@ -64,15 +64,7 @@ def lock(self) -> BaseLock:
 
     @callback
     def push_update(self, updates: dict[int, int | str]) -> None:
-        """
-        Push one or more slot updates and notify listening entities.
-
-        Args:
-            updates: Dict mapping slot numbers to usercode values.
-                     Single: {1: "1234"}
-                     Bulk: {1: "1234", 2: "5678", 3: ""}
-
-        """
+        """Push one or more slot updates and notify listening entities."""
         if not updates:
             return
 

custom_components/lock_code_manager/providers/zwave_js.py

@@ -12,6 +12,7 @@
 from zwave_js_server.const import CommandClass
 from zwave_js_server.const.command_class.lock import (
     ATTR_CODE_SLOT,
+    ATTR_IN_USE,
     ATTR_USERCODE,
     LOCK_USERCODE_PROPERTY,
     LOCK_USERCODE_STATUS_PROPERTY,
@@ -137,24 +138,30 @@ def _get_client_state(self) -> tuple[bool, str]:
 
         return True, ""
 
+    def code_slot_in_use(self, code_slot: int) -> bool | None:
+        """Return whether a code slot is in use."""
+        try:
+            return get_usercode(self.node, code_slot)[ATTR_IN_USE]
+        except (KeyError, ValueError):
+            return None
+
     def _resolve_pin_if_masked(self, value: str, code_slot: int) -> str | None:
         """Resolve a PIN value, looking up expected PIN if masked.
 
         Some locks return masked values (all asterisks) instead of the actual PIN.
         This method returns the value as-is if not masked, or looks up the expected
         PIN from LCM entities if masked.
 
-        Args:
-            value: The PIN value (may be masked like "****")
-            code_slot: The code slot number
+        """
+        slot_in_use = self.code_slot_in_use(code_slot)
 
-        Returns:
-            The PIN value if not masked, or expected PIN if masked and resolvable
-            None if masked but resolution fails
+        if value == "0" * len(value) and slot_in_use is False:
+            # Some locks return all zeros instead of a blank value when cleared - treat
+            # as unmasked cleared value
+            return ""
 
-        """
         # If not masked, return as-is
-        if not value or value != "*" * len(value):
+        if not value or not (value == "*" * len(value) and slot_in_use):
             return value
 
         # Masked - look up expected PIN from LCM entities
@@ -188,15 +195,19 @@ def _resolve_pin_if_masked(self, value: str, code_slot: int) -> str | None:
         if not active_state or not pin_state:
             return None
 
-        if active_state.state == STATE_ON and pin_state.state.isnumeric():
+        if active_state.state == STATE_ON:
             _LOGGER.debug(
                 "PIN is masked for lock %s code slot %s, assuming value from PIN entity %s",
                 self.lock.entity_id,
                 code_slot,
                 pin_entity_id,
             )
             return pin_state.state
-        return None
+
+        # Fall back to returning masked value if active state is not ON (e.g. slot not
+        # enabled) - we don't care what the value is, just that there is one so that
+        # the sync logic treats this slot as having a PIN set on the lock
+        return value
 
     @callback
     def subscribe_push_updates(self) -> None:

custom_components/lock_code_manager/websocket.py

@@ -300,7 +300,7 @@ async def get_config_entry_data(
     - dashboard-strategy.ts: Fetches data for dashboard view generation
     - view-strategy.ts: Fetches config entry and entities for view rendering
 
-    Returns:
+    Sends:
         config_entry: The config entry JSON fragment (entry_id, title, etc.)
         entities: List of entity registry entries for this config entry
         locks: List of lock objects with entity_id and friendly name

docs/development/adding-a-provider.md

@@ -109,14 +109,12 @@ Return current usercodes from the lock:
 
 ```python
 def get_usercodes(self) -> dict[int, int | str]:
-    """Get dictionary of code slots and usercodes.
-
-    Returns:
-        Dict mapping slot number to usercode.
-        Empty string "" for cleared/unused slots.
+    """
+    Get dictionary of code slots and usercodes.
 
     Raises:
         LockDisconnected: If lock cannot be communicated with.
+
     """
     try:
         # Get usercodes from your integration
@@ -140,13 +138,12 @@ Set a usercode on a slot:
 def set_usercode(
     self, code_slot: int, usercode: int | str, name: str | None = None
 ) -> bool:
-    """Set a usercode on a code slot.
-
-    Returns:
-        True if value changed, False if already set to this value.
+    """
+    Set a usercode on a code slot.
 
     Raises:
         LockDisconnected: If lock cannot be communicated with.
+
     """
     try:
         device = self._get_device()
@@ -170,13 +167,12 @@ Clear a usercode from a slot:
 
 ```python
 def clear_usercode(self, code_slot: int) -> bool:
-    """Clear a usercode from a code slot.
-
-    Returns:
-        True if value changed, False if already cleared.
+    """
+    Clear a usercode from a code slot.
 
     Raises:
         LockDisconnected: If lock cannot be communicated with.
+
     """
     try:
         device = self._get_device()

docs/development/provider-state-management.md

@@ -203,14 +203,12 @@ Return current usercode state. This may read from a cache or query the device.
 
 ```python
 def get_usercodes(self) -> dict[int, int | str]:
-    """Return dictionary mapping slot numbers to usercodes.
-
-    Returns:
-        Dict with slot number as key, usercode as value.
-        Use empty string "" for cleared/unused slots.
+    """
+    Return dictionary mapping slot numbers to usercodes.
 
     Raises:
         LockDisconnected: If lock cannot be communicated with.
+
     """
     return {
         1: "1234",   # Slot 1 has code
@@ -234,17 +232,9 @@ def set_usercode(
 ) -> bool:
     """Set a usercode on a code slot.
 
-    Args:
-        code_slot: The slot number to set.
-        usercode: The PIN code to set.
-        name: Optional name for the slot (some locks support this).
-
-    Returns:
-        True if the value was changed, False if already set to this value.
-        If you can't determine whether a change occurred, return True.
-
     Raises:
         LockDisconnected: If the lock cannot be communicated with.
+
     """
     # Check if already set to this value (optional optimization)
     if self._cache.get(code_slot) == str(usercode):
@@ -261,17 +251,12 @@ Clear a usercode from a specific slot.
 
 ```python
 def clear_usercode(self, code_slot: int) -> bool:
-    """Clear a usercode from a code slot.
-
-    Args:
-        code_slot: The slot number to clear.
-
-    Returns:
-        True if the value was changed, False if already cleared.
-        If you can't determine whether a change occurred, return True.
+    """
+    Clear a usercode from a code slot.
 
     Raises:
         LockDisconnected: If the lock cannot be communicated with.
+
     """
     if code_slot not in self._cache or self._cache[code_slot] == "":
         return False
@@ -300,16 +285,15 @@ Re-fetch codes directly from the device, bypassing any cache. Required if `hard_
 
 ```python
 def hard_refresh_codes(self) -> dict[int, int | str]:
-    """Force refresh from device and return all codes.
+    """
+    Force refresh from device and return all codes.
 
     This should bypass any caching layer and query the
     physical device directly.
 
-    Returns:
-        Dict with slot number as key, usercode as value.
-
     Raises:
         LockDisconnected: If lock cannot be communicated with.
+
     """
     self._cache = self._device.fetch_all_codes()
     return self.get_usercodes()