Feat: Add services for managing Schlage door codes

tykeal · tykeal · commit bb141ca95dc2 · 2025-09-05T07:42:14.000-07:00
This commit introduces three new services for the Schlage integration:
- `add_code`: Allows users to add a new access code to a Schlage lock.
- `delete_code`: Enables users to delete an existing access code from a
  Schlage lock.
- `get_codes`: Retrieves all access codes associated with a Schlage
  lock.

Signed-off-by: Andrew Grimberg &lt;tykeal@bardicgrove.org&gt;
diff --git a/homeassistant/components/schlage/__init__.py b/homeassistant/components/schlage/__init__.py
@@ -33,6 +33,7 @@ async def async_setup_entry(hass: HomeAssistant, entry: SchlageConfigEntry) -> b
         hass, entry, username, pyschlage.Schlage(auth)
     )
     entry.runtime_data = coordinator
+
     await coordinator.async_config_entry_first_refresh()
     await hass.config_entries.async_forward_entry_setups(entry, PLATFORMS)
     return True
diff --git a/homeassistant/components/schlage/const.py b/homeassistant/components/schlage/const.py
@@ -7,3 +7,7 @@
 LOGGER = logging.getLogger(__package__)
 MANUFACTURER = "Schlage"
 UPDATE_INTERVAL = timedelta(seconds=30)
+
+SERVICE_ADD_CODE = "add_code"
+SERVICE_DELETE_CODE = "delete_code"
+SERVICE_GET_CODES = "get_codes"
diff --git a/homeassistant/components/schlage/coordinator.py b/homeassistant/components/schlage/coordinator.py
@@ -65,7 +65,7 @@ def __init__(
     async def _async_update_data(self) -> SchlageData:
         """Fetch the latest data from the Schlage API."""
         try:
-            locks = await self.hass.async_add_executor_job(self.api.locks)
+            locks = await self.hass.async_add_executor_job(self.api.locks, True)
         except NotAuthorizedError as ex:
             raise ConfigEntryAuthFailed from ex
         except SchlageError as ex:
diff --git a/homeassistant/components/schlage/icons.json b/homeassistant/components/schlage/icons.json
@@ -0,0 +1,13 @@
+{
+  "services": {
+    "add_code": {
+      "service": "mdi:key-plus"
+    },
+    "delete_code": {
+      "service": "mdi:key-minus"
+    },
+    "get_codes": {
+      "service": "mdi:table-key"
+    }
+  }
+}
diff --git a/homeassistant/components/schlage/lock.py b/homeassistant/components/schlage/lock.py
@@ -4,10 +4,22 @@
 
 from typing import Any
 
+from pyschlage.code import AccessCode
+import voluptuous as vol
+
 from homeassistant.components.lock import LockEntity
-from homeassistant.core import HomeAssistant, callback
+from homeassistant.core import (
+    HomeAssistant,
+    ServiceCall,
+    ServiceResponse,
+    SupportsResponse,
+    callback,
+)
+from homeassistant.exceptions import ServiceValidationError
+from homeassistant.helpers import config_validation as cv, entity_platform
 from homeassistant.helpers.entity_platform import AddConfigEntryEntitiesCallback
 
+from .const import DOMAIN, SERVICE_ADD_CODE, SERVICE_DELETE_CODE, SERVICE_GET_CODES
 from .coordinator import LockData, SchlageConfigEntry, SchlageDataUpdateCoordinator
 from .entity import SchlageEntity
 
@@ -29,6 +41,129 @@ def _add_new_locks(locks: dict[str, LockData]) -> None:
     _add_new_locks(coordinator.data.locks)
     coordinator.new_locks_callbacks.append(_add_new_locks)
 
+    # Custom services
+    def _validate_code_name(codes: dict[str, AccessCode] | None, name: str) -> None:
+        """Validate that the code name doesn't already exist."""
+        if codes and any(code.name == name for code in codes.values()):
+            raise ServiceValidationError(
+                translation_domain=DOMAIN,
+                translation_key="schlage_name_exists",
+            )
+
+    def _validate_code_value(codes: dict[str, AccessCode] | None, code: str) -> None:
+        """Validate that the code value doesn't already exist."""
+        if codes and any(
+            existing_code.code == code for existing_code in codes.values()
+        ):
+            raise ServiceValidationError(
+                translation_domain=DOMAIN,
+                translation_key="schlage_code_exists",
+            )
+
+    async def _add_code(entity: SchlageLockEntity, calls: ServiceCall) -> None:
+        """Add a lock code."""
+        name = calls.data.get("name")
+        code = calls.data.get("code")
+
+        # name is required by voluptuous, the following is just to satisfy type
+        # checker, it should never be None
+        if name is None:
+            raise ServiceValidationError(
+                translation_domain=DOMAIN,
+                translation_key="schlage_name_required",
+            )  # pragma: no cover
+
+        # code is required by voluptuous, the following is just to satisfy type
+        # checker, it should never be None
+        if code is None:
+            raise ServiceValidationError(
+                translation_domain=DOMAIN,
+                translation_key="schlage_code_required",
+            )  # pragma: no cover
+
+        codes = entity._lock.access_codes  # noqa: SLF001
+        _validate_code_name(codes, name)
+        _validate_code_value(codes, code)
+
+        if name and code:
+            access_code = AccessCode(name=name, code=code)
+            await hass.async_add_executor_job(entity._lock.add_access_code, access_code)  # noqa: SLF001
+            await coordinator.async_request_refresh()
+
+    async def _delete_code(entity: SchlageLockEntity, calls: ServiceCall) -> None:
+        """Delete a lock code."""
+        name = calls.data.get("name")
+
+        # name is required by voluptuous, the following is just to satisfy type
+        # checker, it should never be None
+        if name is None:
+            raise ServiceValidationError(
+                translation_domain=DOMAIN,
+                translation_key="schlage_name_required",
+            )  # pragma: no cover
+
+        codes = entity._lock.access_codes  # noqa: SLF001
+        if not codes:
+            return
+
+        code_id_to_delete = next(
+            (
+                code_id
+                for code_id, code_data in codes.items()
+                if code_data.name.lower() == name.lower()
+            ),
+            None,
+        )
+
+        if not code_id_to_delete:
+            return
+
+        if entity._lock.access_codes:  # noqa: SLF001
+            await hass.async_add_executor_job(
+                entity._lock.access_codes[code_id_to_delete].delete  # noqa: SLF001
+            )
+            await coordinator.async_request_refresh()
+
+    async def _get_codes(
+        entity: SchlageLockEntity, calls: ServiceCall
+    ) -> ServiceResponse:
+        """Get lock codes."""
+
+        if entity._lock.access_codes:  # noqa: SLF001
+            return {
+                code: {
+                    "name": entity._lock.access_codes[code].name,  # noqa: SLF001
+                    "code": entity._lock.access_codes[code].code,  # noqa: SLF001
+                }
+                for code in entity._lock.access_codes  # noqa: SLF001
+            }
+        return {}
+
+    platform = entity_platform.async_get_current_platform()
+    platform.async_register_entity_service(
+        name=SERVICE_ADD_CODE,
+        schema={
+            vol.Required("name"): cv.string,
+            vol.Required("code"): cv.matches_regex(r"^\d{4,8}$"),
+        },
+        func=_add_code,
+    )
+
+    platform.async_register_entity_service(
+        name=SERVICE_DELETE_CODE,
+        schema={
+            vol.Required("name"): cv.string,
+        },
+        func=_delete_code,
+    )
+
+    platform.async_register_entity_service(
+        name=SERVICE_GET_CODES,
+        schema=None,
+        func=_get_codes,
+        supports_response=SupportsResponse.ONLY,
+    )
+
 
 class SchlageLockEntity(SchlageEntity, LockEntity):
     """Schlage lock entity."""
diff --git a/homeassistant/components/schlage/services.yaml b/homeassistant/components/schlage/services.yaml
@@ -0,0 +1,50 @@
+get_codes:
+  fields:
+    entity_id:
+      required: true
+      selector:
+        entity:
+          filter:
+            domain: lock
+            integration: schlage
+          multiple: true
+
+add_code:
+  fields:
+    entity_id:
+      required: true
+      selector:
+        entity:
+          filter:
+            domain: lock
+            integration: schlage
+          multiple: true
+    name:
+      required: true
+      example: "Example Person"
+      selector:
+        text:
+          multiline: false
+    code:
+      required: true
+      example: "1111"
+      selector:
+        text:
+          multiline: false
+
+delete_code:
+  fields:
+    entity_id:
+      required: true
+      selector:
+        entity:
+          filter:
+            domain: lock
+            integration: schlage
+          multiple: true
+    name:
+      required: true
+      example: "Example Person"
+      selector:
+        text:
+          multiline: false
diff --git a/homeassistant/components/schlage/strings.json b/homeassistant/components/schlage/strings.json
@@ -31,6 +31,14 @@
         "name": "Keypad disabled"
       }
     },
+    "switch": {
+      "beeper": {
+        "name": "Keypress Beep"
+      },
+      "lock_and_leave": {
+        "name": "1-Touch Locking"
+      }
+    },
     "select": {
       "auto_lock_time": {
         "name": "Auto-lock time",
@@ -45,19 +53,67 @@
           "300": "5 minutes"
         }
       }
-    },
-    "switch": {
-      "beeper": {
-        "name": "Keypress Beep"
-      },
-      "lock_and_leave": {
-        "name": "1-Touch Locking"
-      }
     }
   },
   "exceptions": {
     "schlage_refresh_failed": {
       "message": "Failed to refresh Schlage data"
+    },
+    "schlage_code_exists": {
+      "message": "PIN code already exists"
+    },
+    "schlage_code_required": {
+      "message": "PIN code is required"
+    },
+    "schlage_name_exists": {
+      "message": "PIN name already exists"
+    },
+    "schlage_name_required": {
+      "message": "PIN name is required"
+    }
+  },
+  "services": {
+    "add_code": {
+      "name": "Add PIN code",
+      "description": "Add a PIN code to a lock.",
+      "fields": {
+        "entity_id": {
+          "name": "Lock",
+          "description": "The lock to add the PIN code to."
+        },
+        "name": {
+          "name": "PIN Name",
+          "description": "Name for PIN code. Must be unique to lock."
+        },
+        "code": {
+          "name": "PIN code",
+          "description": "The PIN code to add. Must be unique to lock and be between 4 and 8 digits long."
+        }
+      }
+    },
+    "delete_code": {
+      "name": "Delete PIN code",
+      "description": "Delete a PIN code from a lock.",
+      "fields": {
+        "entity_id": {
+          "name": "Lock",
+          "description": "The lock to delete the PIN code from."
+        },
+        "name": {
+          "name": "PIN Name",
+          "description": "Name of PIN code to delete."
+        }
+      }
+    },
+    "get_codes": {
+      "name": "Get PIN codes",
+      "description": "Retrieve all PIN codes from the lock",
+      "fields": {
+        "entity_id": {
+          "name": "Lock",
+          "description": "The lock to retrieve PIN codes from."
+        }
+      }
     }
   }
 }
diff --git a/tests/components/schlage/test_lock.py b/tests/components/schlage/test_lock.py

Original file line number	Diff line number	Diff line change
`@@ -33,6 +33,7 @@ async def async_setup_entry(hass: HomeAssistant, entry: SchlageConfigEntry) -> b`
`33`	`33`	`hass, entry, username, pyschlage.Schlage(auth)`
`34`	`34`	`)`
`35`	`35`	`entry.runtime_data = coordinator`
	`36`	`+`
`36`	`37`	`await coordinator.async_config_entry_first_refresh()`
`37`	`38`	`await hass.config_entries.async_forward_entry_setups(entry, PLATFORMS)`
`38`	`39`	`return True`