opensb-keypad 0.0.1__py3-none-any.whl

opensb/keypad/__init__.py

@@ -0,0 +1,65 @@
+"""The SwitchBot Keypad Touch: passcodes, cards, fingerprints and its own log."""
+
+from opensb.keypad.advertisement import is_keypad, parse_advertisement, parse_bleak_advertisement
+from opensb.keypad.const import SLOT_AUTO, SLOT_COUNT
+from opensb.keypad.device import Keypad
+from opensb.keypad.discovery import DiscoveredKeypad, discover
+from opensb.keypad.enums import (
+    AlarmAction,
+    Backlight,
+    CredentialKind,
+    CredentialStatus,
+    FingerType,
+    LockAction,
+    LockButton,
+    LockoutKind,
+    LogSource,
+    NfcType,
+    PasswordType,
+    Switch,
+    UnlockAction,
+)
+from opensb.keypad.errors import EnrolmentError
+from opensb.keypad.models import (
+    Advertisement,
+    DeviceInfo,
+    Enrolment,
+    ExecutionStatus,
+    LogEntry,
+    NfcPacket,
+    StoredCard,
+    StoredPassword,
+)
+
+__all__ = [
+    "SLOT_AUTO",
+    "SLOT_COUNT",
+    "Advertisement",
+    "AlarmAction",
+    "Backlight",
+    "CredentialKind",
+    "CredentialStatus",
+    "DeviceInfo",
+    "DiscoveredKeypad",
+    "Enrolment",
+    "EnrolmentError",
+    "ExecutionStatus",
+    "FingerType",
+    "Keypad",
+    "LockAction",
+    "LockButton",
+    "LockoutKind",
+    "LogEntry",
+    "LogSource",
+    "NfcPacket",
+    "NfcType",
+    "PasswordType",
+    "StoredCard",
+    "StoredPassword",
+    "Switch",
+    "UnlockAction",
+    "discover",
+    "is_keypad",
+    "parse_advertisement",
+    "parse_bleak_advertisement",
+]

opensb/keypad/advertisement.py

@@ -0,0 +1,57 @@
+"""Decode what the keypad broadcasts. No key needed, no connection made."""
+
+from opensb.ble.const import COMPANY_ID, SERVICE_UUID
+from opensb.ble.errors import ProtocolError
+from opensb.keypad.const import DEVICE_TYPE, DEVICE_TYPE_PAIRING
+from opensb.keypad.models import Advertisement
+
+KEYPAD_DEVICE_TYPES = frozenset({DEVICE_TYPE, DEVICE_TYPE_PAIRING})
+
+
+def is_keypad(service_data: bytes) -> bool:
+    """Whether this 0xFD3D service data came from a Keypad Touch."""
+    return len(service_data) >= 3 and (service_data[0] & 0x7F) in KEYPAD_DEVICE_TYPES
+
+
+def parse_advertisement(service_data: bytes, manufacturer_data: bytes) -> Advertisement:
+    """Decode a Keypad Touch advertisement.
+
+    `service_data` is the 0xFD3D payload, `manufacturer_data` the 0x0969 one. Byte 9
+    carries both the duress alarms and the lockout flags, and the category bits in
+    byte 8 say which set is live.
+    """
+    if not is_keypad(service_data):
+        raise ProtocolError(f"not Keypad Touch service data: {service_data.hex()}")
+    if len(manufacturer_data) < 10:
+        raise ProtocolError(f"keypad manufacturer data too short: {manufacturer_data.hex()}")
+
+    charge, category, alerts = manufacturer_data[7], manufacturer_data[8], manufacturer_data[9]
+    lockouts_live = bool(category & 0x01)
+    duress_live = bool(category & 0x04)
+    lockouts = alerts >> 4
+
+    return Advertisement(
+        battery=service_data[2] & 0x7F,
+        charging=bool(charge & 0x80),
+        tamper_alert=bool(category & 0x02),
+        urgent_password_alert=duress_live and bool(alerts & 0x01),
+        urgent_nfc_alert=duress_live and bool(alerts & 0x02),
+        urgent_finger_alert=duress_live and bool(alerts & 0x04),
+        password_disabled_alert=lockouts_live and bool(lockouts & 0x01),
+        nfc_disabled_alert=lockouts_live and bool(lockouts & 0x02),
+        finger_disabled_alert=lockouts_live and bool(lockouts & 0x04),
+    )
+
+
+def parse_bleak_advertisement(advertisement_data: object) -> Advertisement:
+    """Decode straight from a bleak AdvertisementData.
+
+    Duck-typed, so importing this module never pulls bleak in.
+    """
+    service_data = getattr(advertisement_data, "service_data", {}) or {}
+    manufacturer_data = getattr(advertisement_data, "manufacturer_data", {}) or {}
+    payload = service_data.get(SERVICE_UUID)
+    mfr = manufacturer_data.get(COMPANY_ID)
+    if payload is None or mfr is None:
+        raise ProtocolError("advertisement carries no SwitchBot service or manufacturer data")
+    return parse_advertisement(bytes(payload), bytes(mfr))

opensb/keypad/const.py

@@ -0,0 +1,32 @@
+"""Wire constants specific to the Keypad Touch."""
+
+# service_data[0] & 0x7f. The keypad advertises 0x59 while in pairing mode.
+DEVICE_TYPE = 0x79
+DEVICE_TYPE_PAIRING = 0x59
+
+# Command groups: 0x52 mutates, 0x53 reads.
+GROUP_WRITE = 0x52
+GROUP_READ = 0x53
+
+# Which engine the sub-command addresses. Numbering is per category -- delete is 0x03
+# for a fingerprint and 0x04 for a card -- so this byte cannot be swapped on its own.
+CATEGORY_DEVICE = 0x01
+CATEGORY_PASSWORD = 0x02
+CATEGORY_NFC = 0x03
+CATEGORY_FINGER = 0x04
+
+# Asking for this slot makes the keypad allocate one and name it in the reply.
+SLOT_AUTO = 0xFF
+
+# Slots per credential kind: 90 ordinary + 10 urgent. There is no bulk read, so
+# listing means walking this range.
+SLOT_COUNT = 100
+
+# Bytes of the set-password body carried per chunk.
+PASSWORD_CHUNK = 11
+
+# A log entry's credential id when the keypad could not place the credential.
+LOG_UNKNOWN_CREDENTIAL = 255
+
+# The passcode id the keypad reserves for its own test code.
+LOG_TEST_PASSWORD = 10

opensb/keypad/device.py

@@ -0,0 +1,336 @@
+"""The keypad as an object: connect, then ask it things."""
+
+import asyncio
+import inspect
+import time
+from collections.abc import AsyncIterator, Awaitable, Callable
+
+from opensb.ble.errors import ProtocolError
+from opensb.ble.models import CommunicationKey, Window
+from opensb.ble.session import Session
+from opensb.ble.transport import BleakTransport, Transport
+from opensb.keypad import frames, replies
+from opensb.keypad.const import SLOT_AUTO, SLOT_COUNT
+from opensb.keypad.enums import (
+    Backlight,
+    CredentialKind,
+    CredentialStatus,
+    FingerType,
+    LockButton,
+    NfcType,
+    PasswordType,
+    Switch,
+)
+from opensb.keypad.errors import EnrolmentError
+from opensb.keypad.models import (
+    DeviceInfo,
+    Enrolment,
+    ExecutionStatus,
+    LogEntry,
+    StoredCard,
+    StoredPassword,
+)
+
+# Credential kinds the keypad expects a validity window for.
+TIMED_PASSWORD_TYPES = frozenset({PasswordType.TIME_LIMIT, PasswordType.ONCE})
+
+# How long to let the user present a card, polled once a second.
+CARD_WAIT_SECONDS = 30
+
+# How long to leave the keypad alone while it reads a finger. It wants four presses.
+FINGER_COLLECT_SECONDS = 40
+
+ReadyCallback = Callable[[int], None] | Callable[[int], Awaitable[None]]
+
+
+async def _call(callback: ReadyCallback | None, slot: int) -> None:
+    if callback is None:
+        return
+    result = callback(slot)
+    if inspect.isawaitable(result):
+        await result
+
+
+class Keypad:
+    """A SwitchBot Keypad Touch, over its encrypted local channel."""
+
+    def __init__(self, transport: Transport, key: CommunicationKey) -> None:
+        self.transport = transport
+        self.key = key
+        self.session = Session(transport, key)
+
+    @classmethod
+    def over_ble(
+        cls,
+        key: CommunicationKey,
+        *,
+        adapter: str | None = None,
+        scan_timeout: float | None = None,
+    ) -> Keypad:
+        """A keypad reached over BLE at the address its key names."""
+        kwargs = {"scan_timeout": scan_timeout} if scan_timeout is not None else {}
+        return cls(BleakTransport(key.mac, adapter=adapter, **kwargs), key)
+
+    async def __aenter__(self) -> Keypad:
+        await self.connect()
+        return self
+
+    async def __aexit__(self, *_exc: object) -> None:
+        await self.disconnect()
+
+    async def connect(self) -> None:
+        await self.transport.connect()
+        self.session.invalidate()
+
+    async def disconnect(self) -> None:
+        self.session.invalidate()
+        await self.transport.disconnect()
+
+    # --- the device itself ---
+
+    async def info(self) -> DeviceInfo:
+        """Battery, versions and every setting, in one read."""
+        return replies.parse_device_info(await self.session.send(frames.device_info()))
+
+    async def status(self) -> ExecutionStatus:
+        """What each credential engine is doing right now."""
+        return replies.parse_execution_status(await self.session.send(frames.execution_status()))
+
+    async def quick_unlock(self) -> bool:
+        """Whether a code alone opens the lock, without the confirm key."""
+        return replies.parse_quick_unlock(await self.session.send(frames.get_quick_unlock()))
+
+    async def set_quick_unlock(self, enabled: bool) -> None:
+        await self.session.send(frames.set_quick_unlock(enabled))
+
+    async def set_keyboard_disabled(self, disabled: bool) -> None:
+        """Turn the whole keypad off, so no credential opens the lock."""
+        await self.session.send(frames.set_keyboard_disabled(disabled))
+
+    async def set_removal_alarm(self, enabled: bool) -> None:
+        await self.session.send(frames.set_removal_alarm(enabled))
+
+    async def silence_removal_alarm(self) -> None:
+        """Stop a sounding tamper alarm, leaving it armed."""
+        await self.session.send(frames.silence_removal_alarm())
+
+    async def set_backlight(self, mode: Backlight, level: int = 0) -> None:
+        await self.session.send(frames.set_light_and_sound(backlight=mode, level=level))
+
+    async def set_sound(self, enabled: bool) -> None:
+        await self.session.send(
+            frames.set_light_and_sound(sound=Switch.ON if enabled else Switch.OFF)
+        )
+
+    async def set_lock_button(self, state: LockButton, seconds: int = 0) -> None:
+        await self.session.send(frames.set_lock_button(state, seconds))
+
+    async def clear_time_penalty(self, kind: CredentialKind) -> None:
+        """Unblock an engine locked out after too many failed attempts."""
+        await self.session.send(frames.clear_time_penalty(kind))
+
+    async def clear_urgent_alarm(self, kind: CredentialKind) -> None:
+        """Acknowledge the alarm a duress credential raised."""
+        await self.session.send(frames.clear_urgent_alarm(kind))
+
+    # --- passcodes ---
+
+    async def add_passcode(
+        self,
+        code: str,
+        password_type: PasswordType = PasswordType.PERMANENT,
+        *,
+        window: Window | None = None,
+        slot: int = SLOT_AUTO,
+    ) -> int:
+        """Store a passcode and return the slot it went into.
+
+        A TIME_LIMIT or ONCE code needs a window, written straight after the code.
+        """
+        if password_type in TIMED_PASSWORD_TYPES and window is None:
+            raise ProtocolError(f"a {password_type.name} passcode needs a validity window")
+        reply = await self.session.send_chunked(frames.set_password(code, password_type, slot))
+        assigned = replies.parse_set_password(reply)
+        if window is not None:
+            await self.session.send(
+                frames.set_password_validity(assigned, window.starts_at, window.ends_at)
+            )
+        return assigned
+
+    async def read_passcode(self, slot: int) -> StoredPassword | None:
+        """The passcode stored in `slot`, or None if it is empty."""
+        return replies.parse_stored_password(
+            await self.session.send(frames.read_password(slot)), slot
+        )
+
+    async def list_passcodes(self, slots: int = SLOT_COUNT) -> AsyncIterator[StoredPassword]:
+        """Walk the slots and yield every passcode found.
+
+        There is no bulk read, so a full sweep of the 100 slots takes about a minute.
+        """
+        for slot in range(slots):
+            stored = await self.read_passcode(slot)
+            if stored is not None:
+                yield stored
+
+    async def delete_passcode(self, slot: int) -> None:
+        await self.session.send(frames.delete_password(slot))
+
+    # --- NFC cards ---
+
+    async def read_card(self, slot: int) -> StoredCard | None:
+        """The card stored in `slot`, reassembled from its packets, or None."""
+        if not replies.parse_nfc_exists(await self.session.send(frames.nfc_exists(slot))):
+            return None
+        data, packet = b"", 0
+        while True:
+            page = replies.parse_nfc_packet(
+                await self.session.send(frames.read_nfc_data(slot, packet))
+            )
+            data += page.payload
+            if page.is_last:
+                return StoredCard(slot=slot, data=data)
+            packet += 1
+
+    async def list_cards(self, slots: int = SLOT_COUNT) -> AsyncIterator[StoredCard]:
+        """Walk the slots and yield every card found."""
+        for slot in range(slots):
+            card = await self.read_card(slot)
+            if card is not None:
+                yield card
+
+    async def delete_card(self, slot: int) -> None:
+        await self.session.send(frames.delete_nfc(slot))
+
+    async def enrol_card(
+        self,
+        nfc_type: NfcType = NfcType.PERMANENT,
+        *,
+        window: Window | None = None,
+        force: bool = False,
+        wait_seconds: int = CARD_WAIT_SECONDS,
+        on_ready: ReadyCallback | None = None,
+    ) -> Enrolment:
+        """Reserve a slot, wait for a card to be presented, and commit it.
+
+        `on_ready` is called with the reserved slot once the reader is armed.
+
+        `force=True` makes the keypad write its own data over the card, destroying
+        what it held -- never point it at a transit pass or bank card.
+
+        A failed enrolment leaves an all-zero stub in its reserved slot, so the slot
+        is released here before the error is raised.
+        """
+        if nfc_type is NfcType.TIME_LIMIT and window is None:
+            raise ProtocolError("a TIME_LIMIT card needs a validity window")
+        stale = (await self.status()).nfc
+        slot = replies.parse_start_nfc_enrolment(
+            await self.session.send(frames.start_nfc_enrolment(nfc_type, force))
+        )
+        await _call(on_ready, slot)
+        outcome = await self._await_card(stale, wait_seconds)
+        if outcome is not CredentialStatus.SUCCESS:
+            await self.delete_card(slot)
+            raise EnrolmentError(outcome, f"card enrolment ended as {outcome.name}")
+        if window is not None:
+            await self.session.send(frames.set_nfc_validity(slot, window.starts_at, window.ends_at))
+        replies.parse_confirm_nfc(await self.session.send(frames.confirm_nfc(slot)))
+        return Enrolment(slot=slot, credential_type=nfc_type)
+
+    async def _await_card(self, stale: CredentialStatus, wait_seconds: int) -> CredentialStatus:
+        """Poll until the card engine reports this attempt's verdict.
+
+        A status that was already non-idle is waited out rather than read as an
+        answer: the engine keeps reporting the previous attempt's result for a while,
+        and taking that at face value announces a verdict for a card nobody presented.
+        """
+        settling = stale is not CredentialStatus.IDLE
+        for _ in range(wait_seconds):
+            current = (await self.status()).nfc
+            if settling:
+                settling = current is not CredentialStatus.IDLE
+            elif current is not CredentialStatus.IDLE:
+                return current
+            await asyncio.sleep(1)
+        if settling:
+            raise EnrolmentError(
+                stale,
+                f"the keypad is still reporting {stale.name} from an earlier attempt and "
+                "never went idle; power-cycle it or run one enrolment from the app",
+            )
+        return CredentialStatus.TIMEOUT
+
+    # --- fingerprints ---
+
+    async def delete_fingerprint(self, slot: int) -> None:
+        """Erase a fingerprint slot.
+
+        Acknowledged whether or not a print was there, and unverifiable afterwards:
+        the slot query is an echo.
+        """
+        await self.session.send(frames.delete_finger(slot))
+
+    async def enrol_fingerprint(
+        self,
+        finger_type: FingerType = FingerType.PERMANENT,
+        *,
+        window: Window | None = None,
+        enhance: bool = False,
+        collect_seconds: int = FINGER_COLLECT_SECONDS,
+        on_ready: ReadyCallback | None = None,
+    ) -> Enrolment:
+        """Reserve a slot, let the reader collect presses, and commit the print.
+
+        The link is dropped for `collect_seconds` and retaken for the verdict. While a
+        client holds it the keypad stays in verification mode, matching each press
+        against the stored prints instead of collecting them; enough of those trip the
+        lockout that `clear_time_penalty` clears.
+
+        `on_ready` is called with the reserved slot once the link is down.
+
+        `enhance=True` takes a second slot for a finger already enrolled. Both open
+        the lock, so deleting that finger means deleting both, and nothing on the
+        keypad pairs them -- the caller must.
+        """
+        if finger_type is FingerType.TIME_LIMIT and window is None:
+            raise ProtocolError("a TIME_LIMIT fingerprint needs a validity window")
+
+        current = (await self.status()).fingerprint
+        if current is not CredentialStatus.IDLE:
+            await self.session.send(frames.cancel_finger_enrolment())
+        slot = replies.parse_start_finger_enrolment(
+            await self.session.send(frames.start_finger_enrolment(finger_type, enhance))
+        )
+
+        await self.disconnect()
+        await _call(on_ready, slot)
+        await asyncio.sleep(collect_seconds)
+        await self.connect()
+
+        outcome = await self.status()
+        if outcome.fingerprint is not CredentialStatus.SUCCESS:
+            await self.session.send(frames.cancel_finger_enrolment())
+            raise EnrolmentError(
+                outcome.fingerprint,
+                f"fingerprint enrolment ended as {outcome.fingerprint.name} after "
+                f"{outcome.fingerprint_step} press(es)",
+            )
+        if window is not None:
+            await self.session.send(
+                frames.set_finger_validity(slot, window.starts_at, window.ends_at)
+            )
+        replies.parse_confirm_finger(await self.session.send(frames.confirm_finger(slot)))
+        return Enrolment(
+            slot=slot, credential_type=finger_type, presses=outcome.fingerprint_step + 1
+        )
+
+    # --- event log ---
+
+    async def read_log(self, since: int | None = None, limit: int = 50) -> AsyncIterator[LogEntry]:
+        """Walk the keypad's own log, newest first, back from `since`."""
+        await self.session.send(frames.set_log_cursor(int(time.time()) if since is None else since))
+        for _ in range(limit):
+            entry = replies.parse_log_entry(await self.session.send(frames.read_log()))
+            if entry is None:
+                return
+            yield entry

opensb/keypad/discovery.py

@@ -0,0 +1,35 @@
+"""Finding Keypad Touch devices among whatever is on the air."""
+
+from opensb.ble.discovery import DEFAULT_DISCOVERY_SECONDS, scan
+from opensb.ble.errors import ProtocolError
+from opensb.ble.models import Frozen
+from opensb.keypad.advertisement import parse_bleak_advertisement
+from opensb.keypad.models import Advertisement
+from pydantic import Field
+
+
+class DiscoveredKeypad(Frozen):
+    """A keypad seen on the air."""
+
+    address: str = Field(description="BLE address to connect to")
+    name: str | None = Field(default=None, description="Advertised local name")
+    rssi: int = Field(description="Signal strength of the last advertisement seen")
+    state: Advertisement = Field(description="What that advertisement said")
+
+
+async def discover(seconds: float = DEFAULT_DISCOVERY_SECONDS) -> list[DiscoveredKeypad]:
+    """Scan for Keypad Touch devices in range.
+
+    The keypad advertises only in bursts, so a unit that has been idle may need a
+    keypress before it shows up.
+    """
+    keypads = []
+    for seen in await scan(seconds):
+        try:
+            state = parse_bleak_advertisement(seen.advertisement)
+        except ProtocolError:
+            continue  # anything that is not a keypad
+        keypads.append(
+            DiscoveredKeypad(address=seen.address, name=seen.name, rssi=seen.rssi, state=state)
+        )
+    return keypads

opensb/keypad/enums.py

@@ -0,0 +1,139 @@
+"""Enumerations specific to the Keypad Touch."""
+
+from enum import IntEnum
+
+
+class PasswordType(IntEnum):
+    """Kind of passcode stored in a slot.
+
+    TIME_LIMIT and ONCE need a validity window written after the code itself.
+    URGENT is a duress code: it opens the lock and raises the urgent-password alarm.
+    INTERVAL and TEST are catalogued but their firmware behaviour is unknown.
+    """
+
+    PERMANENT = 0
+    TIME_LIMIT = 1
+    ONCE = 2
+    URGENT = 3
+    INTERVAL = 4
+    TEST = 5
+
+
+class NfcType(IntEnum):
+    """Kind of NFC card credential.
+
+    Its own scale: URGENT is 2 here and 3 for a passcode, so the two are not
+    interchangeable.
+    """
+
+    PERMANENT = 0
+    TIME_LIMIT = 1
+    URGENT = 2
+
+
+class FingerType(IntEnum):
+    """Kind of fingerprint credential; shares the card scale, not the passcode one."""
+
+    PERMANENT = 0
+    TIME_LIMIT = 1
+    URGENT = 2
+
+
+class CredentialStatus(IntEnum):
+    """Progress of an in-flight enrolment, from the execution-status poll."""
+
+    IDLE = 0
+    SUCCESS = 1
+    ERROR = 2
+    ALREADY_EXISTS = 3
+    TIMEOUT = 4
+    UNSUPPORTED_CARD = 5
+
+
+class CredentialKind(IntEnum):
+    """Which engine an alarm or a lockout belongs to."""
+
+    PASSWORD = 1
+    NFC = 2
+    FINGERPRINT = 4
+
+
+class LockButton(IntEnum):
+    """What the keypad's lock button does. TIMED carries a window in seconds."""
+
+    DISABLED = 1
+    ENABLED = 2
+    TIMED = 3
+
+
+class Backlight(IntEnum):
+    """Backlight mode."""
+
+    OFF = 1
+    AUTO = 2
+    ALWAYS_ON = 3
+
+
+class Switch(IntEnum):
+    """A two-valued setting, plus a KEEP that leaves the field untouched."""
+
+    KEEP = 0
+    OFF = 1
+    ON = 2
+
+
+class LogSource(IntEnum):
+    """What raised a log entry.
+
+    The keypad's own axis, which does not match the lock's. FACE and DOORBELL belong
+    to siblings of this device.
+    """
+
+    PASSWORD = 1
+    NFC = 2
+    FINGERPRINT = 3
+    LOCK = 4
+    ALARM = 5
+    FACE = 6
+    DOORBELL = 7
+
+
+# Sources that report a credential being presented, and so carry a credential id.
+CREDENTIAL_SOURCES = frozenset(
+    {LogSource.PASSWORD, LogSource.NFC, LogSource.FINGERPRINT, LogSource.FACE}
+)
+
+
+class UnlockAction(IntEnum):
+    """Outcome of a credential being presented, for a CREDENTIAL_SOURCES entry."""
+
+    SUCCESS = 0
+    ERROR = 1
+    NOT_RECOGNISED = 2
+    EXPIRED = 3
+
+
+class LockAction(IntEnum):
+    """Outcome of the keypad's own lock button, for a LogSource.LOCK entry."""
+
+    SUCCESS = 0
+    ERROR = 1
+
+
+class AlarmAction(IntEnum):
+    """What a LogSource.ALARM entry is reporting."""
+
+    LOW_BATTERY = 0
+    LOCKOUT = 1
+    REMOVED = 2
+
+
+class LockoutKind(IntEnum):
+    """Which engine was locked out, carried in an AlarmAction.LOCKOUT entry's value.
+
+    Numbered 1-3, unlike CredentialKind's bitmask.
+    """
+
+    PASSWORD = 1
+    NFC = 2
+    FINGERPRINT = 3

opensb/keypad/errors.py

@@ -0,0 +1,12 @@
+"""Exceptions specific to the Keypad Touch."""
+
+from opensb.ble.errors import OpenSBError
+from opensb.keypad.enums import CredentialStatus
+
+
+class EnrolmentError(OpenSBError):
+    """An interactive enrolment did not produce a credential."""
+
+    def __init__(self, status: CredentialStatus, message: str = "") -> None:
+        self.status = status
+        super().__init__(message or f"enrolment ended as {status.name}")