opensb-core 0.0.1__tar.gz

opensb_core-0.0.1/.gitignore

@@ -0,0 +1,27 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+venv
+
+# Tooling caches
+.coverage
+coverage.xml
+htmlcov/
+.pytest_cache/
+.pyrefly_cache/
+.ruff_cache/
+
+# Never commit a communication key: it reads every stored passcode back out.
+# Broad on purpose -- the fetch tools name these keypad_key.json, lock_key.json, keypad.json.
+*key*.json
+*.pem
+.env
+*.env
+secrets/

opensb_core-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yorsh Siarhei
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

opensb_core-0.0.1/PKG-INFO

@@ -0,0 +1,26 @@
+Metadata-Version: 2.5
+Name: opensb-core
+Version: 0.0.1
+Summary: Shared BLE transport, encryption envelope and session for SwitchBot devices
+Author-email: Yorsh Siarhei <yorsh.srg@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ble,bluetooth,switchbot
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Home Automation
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Requires-Dist: cryptography>=42
+Requires-Dist: pydantic>=2.7
+Provides-Extra: ble
+Requires-Dist: bleak>=0.22; extra == 'ble'
+Description-Content-Type: text/markdown
+
+# opensb-core
+
+Shared BLE transport, encryption envelope and session for SwitchBot devices.
+
+See the [opensb](https://pypi.org/project/opensb/) distribution for the command line,
+and `opensb-keypad` / `opensb-lockpro` for device support.

opensb_core-0.0.1/README.md

@@ -0,0 +1,6 @@
+# opensb-core
+
+Shared BLE transport, encryption envelope and session for SwitchBot devices.
+
+See the [opensb](https://pypi.org/project/opensb/) distribution for the command line,
+and `opensb-keypad` / `opensb-lockpro` for device support.

opensb_core-0.0.1/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "opensb-core"
+dynamic = ["version"]
+description = "Shared BLE transport, encryption envelope and session for SwitchBot devices"
+readme = "README.md"
+requires-python = ">=3.14"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Yorsh Siarhei", email = "yorsh.srg@gmail.com" }]
+keywords = ["switchbot", "ble", "bluetooth"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Home Automation",
+    "Typing :: Typed",
+]
+dependencies = ["cryptography>=42", "pydantic>=2.7"]
+
+[project.optional-dependencies]
+ble = ["bleak>=0.22"]
+
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+source = "vcs"
+raw-options = { root = "../..", fallback_version = "0.0.0" }
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/opensb"]

opensb_core-0.0.1/src/opensb/ble/__init__.py

@@ -0,0 +1,52 @@
+"""Transport, encryption and session handling, shared by every SwitchBot device.
+
+Device support lives in its own distribution -- `opensb-keypad`, `opensb-lockpro` --
+over this core.
+"""
+
+from opensb.ble.const import (
+    COMPANY_ID,
+    GATT_NOTIFY,
+    GATT_SERVICE,
+    GATT_WRITE,
+    SERVICE_UUID,
+)
+from opensb.ble.discovery import Seen, scan
+from opensb.ble.enums import AesMode, ReplyStatus
+from opensb.ble.errors import (
+    NotConnectedError,
+    OpenSBError,
+    ProtocolError,
+    ReplyError,
+    StaleSessionError,
+)
+from opensb.ble.models import CommunicationKey, Window
+from opensb.ble.replies import check
+from opensb.ble.session import Session
+from opensb.ble.transport import BleakTransport, Transport
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "COMPANY_ID",
+    "GATT_NOTIFY",
+    "GATT_SERVICE",
+    "GATT_WRITE",
+    "SERVICE_UUID",
+    "AesMode",
+    "BleakTransport",
+    "CommunicationKey",
+    "NotConnectedError",
+    "OpenSBError",
+    "ProtocolError",
+    "ReplyError",
+    "ReplyStatus",
+    "Seen",
+    "Session",
+    "StaleSessionError",
+    "Transport",
+    "Window",
+    "__version__",
+    "check",
+    "scan",
+]

opensb_core-0.0.1/src/opensb/ble/const.py

@@ -0,0 +1,19 @@
+"""Wire constants shared by every SwitchBot device on this transport."""
+
+# Vendor GATT service, the same across the range.
+GATT_SERVICE = "cba20d00-224d-11e6-9fb8-0002a5d5c51b"
+GATT_WRITE = "cba20002-224d-11e6-9fb8-0002a5d5c51b"
+GATT_NOTIFY = "cba20003-224d-11e6-9fb8-0002a5d5c51b"
+
+# Advertisement identifiers.
+COMPANY_ID = 0x0969
+SERVICE_UUID = "0000fd3d-0000-1000-8000-00805f9b34fb"
+
+# Every framed command starts with these two bytes.
+FRAME_MAGIC = 0x57
+FRAME_EXT = 0x0F
+
+# Reply statuses meaning the key or the negotiated IV went stale: re-handshake, and
+# re-fetch the key if that does not help. Status 5 looks like one of these but is
+# UNSUPPORTED, which no handshake fixes.
+STALE_SESSION_STATUSES = frozenset({4, 9, 13})

opensb_core-0.0.1/src/opensb/ble/crypto.py

@@ -0,0 +1,91 @@
+"""The encryption envelope every keypad command travels in.
+
+The keypad negotiates a cipher and an IV once per session, then each command is
+written as a four-byte plaintext header followed by the encrypted remainder of the
+command. Replies come back the same way.
+"""
+
+from typing import Any
+
+from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+from opensb.ble.enums import AesMode
+from opensb.ble.errors import ProtocolError
+
+KEY_LENGTH = 16
+IV_LENGTH = {AesMode.CTR: 16, AesMode.GCM: 12}
+
+
+def handshake_frame(key_id: int) -> bytes:
+    """The plaintext frame that opens a session; its reply carries the IV."""
+    return bytes([0x57, 0x00, 0x00, 0x00, 0x0F, 0x21, 0x03, key_id & 0xFF])
+
+
+def parse_handshake_reply(reply: bytes) -> tuple[AesMode, bytes]:
+    """Read the negotiated (mode, iv) out of a handshake reply."""
+    if len(reply) < 4:
+        raise ProtocolError(f"handshake reply too short: {reply.hex()}")
+    if reply[0] != 1:
+        raise ProtocolError(f"handshake not acknowledged: {reply.hex()}")
+    try:
+        mode = AesMode(reply[2])
+    except ValueError as err:
+        raise ProtocolError(f"unknown cipher mode {reply[2]} in {reply.hex()}") from err
+    iv = reply[4:] if mode is AesMode.CTR else reply[4:-4]
+    if len(iv) != IV_LENGTH[mode]:
+        raise ProtocolError(f"IV is {len(iv)} bytes, expected {IV_LENGTH[mode]} for {mode.name}")
+    return mode, iv
+
+
+def _cipher(key: bytes, iv: bytes, mode: AesMode) -> Cipher[Any]:
+    algorithm: modes.Mode = modes.CTR(iv) if mode is AesMode.CTR else modes.GCM(iv)
+    return Cipher(algorithms.AES(key), algorithm)
+
+
+def _check(key: bytes, iv: bytes, mode: AesMode) -> None:
+    if len(key) != KEY_LENGTH:
+        raise ProtocolError(f"communication key must be {KEY_LENGTH} bytes, got {len(key)}")
+    if len(iv) != IV_LENGTH[mode]:
+        raise ProtocolError(f"{mode.name} IV must be {IV_LENGTH[mode]} bytes, got {len(iv)}")
+
+
+def encrypt(command: bytes, key: bytes, iv: bytes, key_id: int, mode: AesMode) -> bytes:
+    """Wrap a plaintext command into the frame written to the device.
+
+        command[0] | key_id | nonce[0:2] | AES(command[1:])
+
+    Byte 0 stays in the clear. The nonce echo heads the IV under CTR and the auth tag
+    under GCM.
+    """
+    _check(key, iv, mode)
+    if not command:
+        raise ProtocolError("command is empty")
+    encryptor = _cipher(key, iv, mode).encryptor()
+    ciphertext: bytes = encryptor.update(command[1:]) + encryptor.finalize()
+    nonce = encryptor.tag[:2] if mode is AesMode.GCM else iv[:2]
+    return bytes([command[0], key_id & 0xFF, nonce[0], nonce[1]]) + ciphertext
+
+
+def decrypt(reply: bytes, key: bytes, iv: bytes, mode: AesMode) -> bytes:
+    """Decode a notification into `status || plaintext payload`.
+
+    The device sends two bytes of the GCM tag, too few to verify, so a dummy tag lets
+    the decryptor run without finalising.
+    """
+    _check(key, iv, mode)
+    if len(reply) < 4:
+        raise ProtocolError(f"reply too short: {reply.hex()}")
+    status, ciphertext = reply[0], reply[4:]
+    if not ciphertext:
+        return bytes([status])
+    if mode is AesMode.GCM:
+        decryptor = Cipher(algorithms.AES(key), modes.GCM(iv, b"\x00" * 16)).decryptor()
+        return bytes([status]) + decryptor.update(ciphertext)
+    decryptor = _cipher(key, iv, mode).decryptor()
+    return bytes([status]) + decryptor.update(ciphertext) + decryptor.finalize()
+
+
+def next_gcm_iv(iv: bytes) -> bytes:
+    """The IV for the next command under GCM, which steps once per frame."""
+    if len(iv) != IV_LENGTH[AesMode.GCM]:
+        raise ProtocolError(f"GCM IV must be {IV_LENGTH[AesMode.GCM]} bytes, got {len(iv)}")
+    return ((int.from_bytes(iv, "big") + 1) % (1 << 96)).to_bytes(12, "big")

opensb_core-0.0.1/src/opensb/ble/discovery.py

@@ -0,0 +1,41 @@
+"""Listening for advertisements. What one means is the device package's business."""
+
+import asyncio
+
+from opensb.ble.errors import OpenSBError
+from opensb.ble.models import Frozen
+from pydantic import Field
+
+DEFAULT_DISCOVERY_SECONDS = 10.0
+
+
+class Seen(Frozen):
+    """One advertiser, as it came off the air."""
+
+    address: str = Field(description="BLE address")
+    name: str | None = Field(default=None, description="Advertised local name")
+    rssi: int = Field(description="Signal strength of the last advertisement seen")
+    advertisement: object = Field(description="The bleak AdvertisementData, unparsed")
+
+
+async def scan(seconds: float = DEFAULT_DISCOVERY_SECONDS) -> list[Seen]:
+    """Every advertiser in range, latest reading per address, strongest first."""
+    try:
+        from bleak import BleakScanner
+    except ImportError as err:  # pragma: no cover - depends on the install extras
+        raise OpenSBError("bleak is not installed; install opensb-core[ble] to scan") from err
+
+    found: dict[str, Seen] = {}
+
+    def on_advertisement(device: object, data: object) -> None:
+        address = getattr(device, "address", "")
+        found[address] = Seen(
+            address=address,
+            name=getattr(data, "local_name", None) or getattr(device, "name", None),
+            rssi=getattr(data, "rssi", 0),
+            advertisement=data,
+        )
+
+    async with BleakScanner(on_advertisement):
+        await asyncio.sleep(seconds)
+    return sorted(found.values(), key=lambda seen: -seen.rssi)

opensb_core-0.0.1/src/opensb/ble/enums.py

@@ -0,0 +1,28 @@
+"""Enumerations shared by every device on this transport."""
+
+from enum import IntEnum
+
+
+class AesMode(IntEnum):
+    """Cipher the device announces in byte 2 of the handshake reply."""
+
+    CTR = 0
+    GCM = 1
+
+
+class ReplyStatus(IntEnum):
+    """Byte 0 of a decrypted reply."""
+
+    NULL = 0
+    OK = 1
+    ERROR = 2
+    BUSY = 3
+    UNSUPPORTED = 5
+    BTL = 6
+    ENCRYPTED = 7
+    UNENCRYPTED = 8
+    PASSWORD_INVALID = 9
+
+
+# BTL answers a command that succeeded, so it counts as success alongside OK.
+SUCCESS_STATUSES = frozenset({ReplyStatus.OK, ReplyStatus.BTL})

opensb_core-0.0.1/src/opensb/ble/errors.py

@@ -0,0 +1,34 @@
+"""Exceptions raised by the library."""
+
+from opensb.ble.enums import ReplyStatus
+
+
+class OpenSBError(Exception):
+    """Base class for every error this library raises."""
+
+
+class ProtocolError(OpenSBError):
+    """A frame did not have the shape the protocol requires."""
+
+
+class ReplyError(OpenSBError):
+    """The device answered with a non-success status."""
+
+    def __init__(self, status: int, reply: bytes, context: str = "") -> None:
+        self.status = status
+        self.reply = reply
+        self.context = context
+        try:
+            name = ReplyStatus(status).name
+        except ValueError:
+            name = f"UNKNOWN({status})"
+        where = f"{context}: " if context else ""
+        super().__init__(f"{where}device answered {name} [{reply.hex()}]")
+
+
+class StaleSessionError(ReplyError):
+    """The key or the negotiated IV was rejected; handshake again, or re-fetch the key."""
+
+
+class NotConnectedError(OpenSBError):
+    """A command was issued outside a connected session."""

opensb_core-0.0.1/src/opensb/ble/models.py

@@ -0,0 +1,57 @@
+"""Values shared by every device on this transport."""
+
+import time
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+
+class Frozen(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+
+class CommunicationKey(Frozen):
+    """The per-device credential that opens the encrypted channel.
+
+    Supplied by the caller; this library neither obtains nor stores it. Also accepts
+    the shape SwitchBot's key endpoint returns -- `key_id` as a hex string, the key
+    under `encryption_key` -- so a payload can go straight to `model_validate`.
+    """
+
+    mac: str = Field(description="Keypad BLE address the key belongs to")
+    key_id: int = Field(description="Key identifier, sent in byte 1 of every frame")
+    key: bytes = Field(description="16-byte AES key")
+
+    @model_validator(mode="before")
+    @classmethod
+    def _accept_wire_shape(cls, payload: object) -> object:
+        if not isinstance(payload, dict):
+            return payload
+        fields = dict(payload)
+        if "encryption_key" in fields:
+            fields.setdefault("key", fields.pop("encryption_key"))
+        if isinstance(fields.get("key"), str):
+            fields["key"] = bytes.fromhex(fields["key"])
+        if isinstance(fields.get("key_id"), str):
+            fields["key_id"] = int(fields["key_id"], 16)
+        return fields
+
+    @model_validator(mode="after")
+    def _check_lengths(self) -> CommunicationKey:
+        if len(self.key) != 16:
+            raise ValueError(f"communication key must be 16 bytes, got {len(self.key)}")
+        if not 0 <= self.key_id <= 0xFF:
+            raise ValueError(f"key id must fit in one byte, got {self.key_id}")
+        return self
+
+
+class Window(Frozen):
+    """A credential validity window, in unix seconds."""
+
+    starts_at: int = Field(description="First moment the credential works")
+    ends_at: int = Field(description="Last moment the credential works")
+
+    @classmethod
+    def for_minutes(cls, minutes: int, starts_at: int | None = None) -> Window:
+        """A window of `minutes` starting now, or at `starts_at`."""
+        start = int(time.time()) if starts_at is None else starts_at
+        return cls(starts_at=start, ends_at=start + minutes * 60)

opensb_core-0.0.1/src/opensb/ble/replies.py

@@ -0,0 +1,17 @@
+"""Judging the status byte a device puts in front of every reply."""
+
+from opensb.ble.const import STALE_SESSION_STATUSES
+from opensb.ble.enums import SUCCESS_STATUSES
+from opensb.ble.errors import ProtocolError, ReplyError, StaleSessionError
+
+
+def check(reply: bytes, context: str, minimum: int = 1) -> bytes:
+    """Raise unless the keypad accepted the command and answered at length."""
+    if not reply:
+        raise ProtocolError(f"{context}: empty reply")
+    if reply[0] not in SUCCESS_STATUSES:
+        error = StaleSessionError if reply[0] in STALE_SESSION_STATUSES else ReplyError
+        raise error(reply[0], reply, context)
+    if len(reply) < minimum:
+        raise ProtocolError(f"{context}: reply too short [{reply.hex()}]")
+    return reply

opensb_core-0.0.1/src/opensb/ble/session.py

@@ -0,0 +1,77 @@
+"""The encrypted session on top of a transport.
+
+The cipher and IV are negotiated once and kept for the life of the session, and
+renegotiated when the device says they went stale.
+"""
+
+from opensb.ble import crypto
+from opensb.ble.const import STALE_SESSION_STATUSES
+from opensb.ble.enums import AesMode
+from opensb.ble.errors import StaleSessionError
+from opensb.ble.models import CommunicationKey
+from opensb.ble.replies import check
+from opensb.ble.transport import Transport
+
+
+class Session:
+    """One encrypted conversation with a device."""
+
+    def __init__(self, transport: Transport, key: CommunicationKey) -> None:
+        self.transport = transport
+        self.key = key
+        self._mode: AesMode | None = None
+        self._iv: bytes | None = None
+
+    async def handshake(self) -> tuple[AesMode, bytes]:
+        """Negotiate the cipher and IV, replacing whatever was in force."""
+        reply = await self.transport.request(crypto.handshake_frame(self.key.key_id))
+        self._mode, self._iv = crypto.parse_handshake_reply(reply)
+        return self._mode, self._iv
+
+    async def _ensure(self) -> tuple[AesMode, bytes]:
+        if self._mode is None or self._iv is None:
+            return await self.handshake()
+        return self._mode, self._iv
+
+    def invalidate(self) -> None:
+        """Forget the negotiated session, so the next command handshakes again."""
+        self._mode = self._iv = None
+
+    async def send(self, command: bytes) -> bytes:
+        """Send one command and return its decrypted reply.
+
+        A stale-session status is retried once against a fresh handshake.
+        """
+        try:
+            return await self._send_once(command)
+        except StaleSessionError:
+            self.invalidate()
+            return await self._send_once(command)
+
+    async def _send_once(self, command: bytes) -> bytes:
+        """One encrypted round trip.
+
+        Only a stale-session status is judged here; every other status means
+        something command-specific, so it is left to the parser.
+        """
+        mode, iv = await self._ensure()
+        frame = crypto.encrypt(command, self.key.key, iv, self.key.key_id, mode)
+        reply = crypto.decrypt(await self.transport.request(frame), self.key.key, iv, mode)
+        if reply and reply[0] in STALE_SESSION_STATUSES:
+            raise StaleSessionError(reply[0], reply, f"command {command.hex()}")
+        return reply
+
+    async def send_chunked(self, commands: list[bytes]) -> bytes:
+        """Send a multi-frame command as one sequence and return the last reply.
+
+        The chunks share a handshake so the keypad reads them as one write.
+        """
+        mode, iv = await self._ensure()
+        reply = b""
+        for index, command in enumerate(commands):
+            frame = crypto.encrypt(command, self.key.key, iv, self.key.key_id, mode)
+            reply = crypto.decrypt(await self.transport.request(frame), self.key.key, iv, mode)
+            check(reply, f"chunk {index + 1} of {len(commands)}")
+            if mode is AesMode.GCM:
+                iv = crypto.next_gcm_iv(iv)
+        return reply

opensb_core-0.0.1/src/opensb/ble/transport.py

@@ -0,0 +1,102 @@
+"""Getting frames to the keypad and notifications back.
+
+The protocol layers above take a Transport, so they can be driven by bleak, by an
+ESP bridge, or by a recorded fixture in a test.
+"""
+
+import asyncio
+from typing import Any, Protocol
+
+from opensb.ble.const import GATT_NOTIFY, GATT_WRITE
+from opensb.ble.errors import NotConnectedError, OpenSBError
+
+DEFAULT_REQUEST_TIMEOUT = 8.0
+DEFAULT_SCAN_TIMEOUT = 15.0
+
+
+class Transport(Protocol):
+    """A connection that can carry one request at a time and answer it."""
+
+    @property
+    def is_connected(self) -> bool: ...
+
+    async def connect(self) -> None: ...
+
+    async def disconnect(self) -> None: ...
+
+    async def request(self, frame: bytes) -> bytes:
+        """Write one frame and return the notification it produces."""
+        ...
+
+
+class BleakTransport:
+    """A GATT connection to the keypad, over bleak.
+
+    The keypad sleeps between uses and does not advertise continuously, so it is
+    looked up by a scan on every connect rather than addressed directly.
+    """
+
+    def __init__(
+        self,
+        address: str,
+        *,
+        adapter: str | None = None,
+        scan_timeout: float = DEFAULT_SCAN_TIMEOUT,
+        request_timeout: float = DEFAULT_REQUEST_TIMEOUT,
+    ) -> None:
+        self.address = address
+        self.adapter = adapter
+        self.scan_timeout = scan_timeout
+        self.request_timeout = request_timeout
+        self._client: Any = None
+        self._replies: asyncio.Queue[bytes] = asyncio.Queue()
+
+    @property
+    def is_connected(self) -> bool:
+        return bool(self._client) and bool(getattr(self._client, "is_connected", False))
+
+    async def connect(self) -> None:
+        if self.is_connected:
+            return
+        try:
+            from bleak import BleakClient, BleakScanner
+        except ImportError as err:  # pragma: no cover - depends on the install extras
+            raise OpenSBError(
+                "bleak is not installed; install opensb-core[ble] to talk to a device"
+            ) from err
+
+        kwargs: dict[str, Any] = {"adapter": self.adapter} if self.adapter else {}
+        device = await BleakScanner.find_device_by_address(
+            self.address, timeout=self.scan_timeout, **kwargs
+        )
+        if device is None:
+            raise OpenSBError(
+                f"{self.address} did not answer a {self.scan_timeout:.0f}s scan; "
+                "the keypad sleeps, so press a key to wake it and retry"
+            )
+        client = BleakClient(device, **kwargs)
+        await client.connect()
+        self._replies = asyncio.Queue()
+        await client.start_notify(GATT_NOTIFY, self._on_notify)
+        self._client = client
+
+    def _on_notify(self, _characteristic: object, data: bytearray) -> None:
+        self._replies.put_nowait(bytes(data))
+
+    async def disconnect(self) -> None:
+        client, self._client = self._client, None
+        if client is not None:
+            await client.disconnect()
+
+    async def request(self, frame: bytes) -> bytes:
+        if not self.is_connected:
+            raise NotConnectedError("no BLE connection to the keypad")
+        while not self._replies.empty():  # drop anything left over from an earlier command
+            self._replies.get_nowait()
+        await self._client.write_gatt_char(GATT_WRITE, frame, response=False)
+        try:
+            return await asyncio.wait_for(self._replies.get(), timeout=self.request_timeout)
+        except TimeoutError as err:
+            raise OpenSBError(
+                f"the keypad did not answer within {self.request_timeout:.0f}s"
+            ) from err