Add clear_usercode utility function (#55)

Author: raman325

test/util/test_lock.py

@@ -4,6 +4,7 @@
 from zwave_js_server.const import ATTR_USERCODE
 from zwave_js_server.exceptions import NotFoundError
 from zwave_js_server.util.lock import (
+    clear_usercode,
     get_code_slots,
     get_usercode,
     get_usercodes,
@@ -93,3 +94,50 @@ async def test_set_usercode(lock_schlage_be469, mock_command, uuid4):
 
     # assert no new command calls
     assert len(ack_commands) == 1
+
+
+async def test_clear_usercode(lock_schlage_be469, mock_command, uuid4):
+    """Test clear_usercode utility function."""
+    node = lock_schlage_be469
+    ack_commands = mock_command(
+        {"command": "node.set_value", "nodeId": node.node_id},
+        {"success": True},
+    )
+
+    # Test valid code
+    await clear_usercode(node, 1)
+    assert len(ack_commands) == 1
+    assert ack_commands[0] == {
+        "command": "node.set_value",
+        "nodeId": 20,
+        "messageId": uuid4,
+        "valueId": {
+            "commandClassName": "User Code",
+            "commandClass": 99,
+            "endpoint": 0,
+            "property": "userIdStatus",
+            "propertyName": "userIdStatus",
+            "propertyKey": 1,
+            "propertyKeyName": "1",
+            "metadata": {
+                "type": "number",
+                "readable": True,
+                "writeable": True,
+                "label": "User ID status (1)",
+                "states": {
+                    "0": "Available",
+                    "1": "Enabled",
+                    "2": "Disabled",
+                },
+            },
+            "value": 1,
+        },
+        "value": 0,
+    }
+
+    # Test invalid code slot
+    with pytest.raises(NotFoundError):
+        await clear_usercode(node, 100)
+
+    # assert no new command calls
+    assert len(ack_commands) == 1

zwave_js_server/const.py

@@ -146,6 +146,14 @@ class DoorLockMode(IntEnum):
     SECURED = 255
 
 
+class CodeSlotStatus(IntEnum):
+    """Enum with all (known/used) Z-Wave code slot statuses."""
+
+    AVAILABLE = 0
+    ENABLED = 1
+    DISABLED = 2
+
+
 # Depending on the Commmand Class being used by the lock, the lock state is
 # different so we need a map to track it
 LOCK_CMD_CLASS_TO_LOCKED_STATE_MAP = {
@@ -161,6 +169,7 @@ class DoorLockMode(IntEnum):
 }
 
 LOCK_USERCODE_PROPERTY = "userCode"
+LOCK_USERCODE_STATUS_PROPERTY = "userIdStatus"
 ATTR_CODE_SLOT = "code_slot"
 ATTR_IN_USE = "in_use"
 ATTR_NAME = "name"

zwave_js_server/util/lock.py

@@ -7,28 +7,30 @@
     ATTR_NAME,
     ATTR_USERCODE,
     LOCK_USERCODE_PROPERTY,
+    LOCK_USERCODE_STATUS_PROPERTY,
+    CodeSlotStatus,
     CommandClass,
 )
 from ..exceptions import NotFoundError
 from ..model.node import Node
 from ..model.value import get_value_id, Value
 
 
-def get_code_slot_value(node: Node, code_slot: int) -> Value:
-    """Get a value."""
+def get_code_slot_value(node: Node, code_slot: int, property_name: str) -> Value:
+    """Get a code slot value."""
     value = node.values.get(
         get_value_id(
             node,
             {
                 "commandClass": CommandClass.USER_CODE,
-                "property": LOCK_USERCODE_PROPERTY,
+                "property": property_name,
                 "propertyKeyName": str(code_slot),
             },
         )
     )
 
     if not value:
-        raise NotFoundError(f"Code slot {code_slot} not found")
+        raise NotFoundError(f"{property_name} for code slot {code_slot} not found")
 
     return value
 
@@ -43,7 +45,10 @@ def _get_code_slots(
     # Loop until we can't find a code slot
     while True:
         try:
-            value = get_code_slot_value(node, code_slot)
+            value = get_code_slot_value(node, code_slot, LOCK_USERCODE_PROPERTY)
+            status_value = get_code_slot_value(
+                node, code_slot, LOCK_USERCODE_STATUS_PROPERTY
+            )
         except NotFoundError:
             return slots
 
@@ -52,7 +57,7 @@ def _get_code_slots(
         slot = {
             ATTR_CODE_SLOT: int(value.property_key),  # type: ignore
             ATTR_NAME: value.metadata.label,
-            ATTR_IN_USE: bool(value.value),
+            ATTR_IN_USE: status_value.value == CodeSlotStatus.ENABLED,
         }
         if include_usercode:
             slot[ATTR_USERCODE] = value.value if value.value else None
@@ -73,16 +78,22 @@ def get_usercodes(node: Node) -> List[Dict[str, Optional[Union[int, bool, str]]]
 
 def get_usercode(node: Node, code_slot: int) -> Optional[str]:
     """Get usercode from slot X on the lock."""
-    value = get_code_slot_value(node, code_slot)
+    value = get_code_slot_value(node, code_slot, LOCK_USERCODE_PROPERTY)
 
     return str(value.value) if value.value else None
 
 
 async def set_usercode(node: Node, code_slot: int, usercode: str) -> None:
     """Set the usercode to index X on the lock."""
-    value = get_code_slot_value(node, code_slot)
+    value = get_code_slot_value(node, code_slot, LOCK_USERCODE_PROPERTY)
 
     if len(str(usercode)) < 4:
         raise ValueError("User code must be at least 4 digits")
 
     await node.async_set_value(value, usercode)
+
+
+async def clear_usercode(node: Node, code_slot: int) -> None:
+    """Clear a code slot on the lock."""
+    value = get_code_slot_value(node, code_slot, LOCK_USERCODE_STATUS_PROPERTY)
+    await node.async_set_value(value, CodeSlotStatus.AVAILABLE.value)