opensb 0.0.1__tar.gz

opensb-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-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-0.0.1/PKG-INFO

@@ -0,0 +1,35 @@
+Metadata-Version: 2.5
+Name: opensb
+Version: 0.0.1
+Summary: Command line for SwitchBot devices over BLE, with no cloud and no state on disk
+Author-email: Yorsh Siarhei <yorsh.srg@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ble,bluetooth,cli,home-assistant,switchbot
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Home Automation
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Requires-Dist: opensb-core[ble]
+Requires-Dist: rich>=13
+Requires-Dist: typer>=0.12
+Provides-Extra: all
+Requires-Dist: opensb-keypad; extra == 'all'
+Requires-Dist: opensb-lockpro; extra == 'all'
+Provides-Extra: keypad
+Requires-Dist: opensb-keypad; extra == 'keypad'
+Provides-Extra: lockpro
+Requires-Dist: opensb-lockpro; extra == 'lockpro'
+Description-Content-Type: text/markdown
+
+# opensb
+
+Command line for SwitchBot devices over BLE.
+
+    python3 -m pip install 'opensb[keypad,lockpro]'
+
+Device support is a separate distribution each, so a group appears in the CLI only
+when its package is installed.

opensb-0.0.1/README.md

@@ -0,0 +1,8 @@
+# opensb
+
+Command line for SwitchBot devices over BLE.
+
+    python3 -m pip install 'opensb[keypad,lockpro]'
+
+Device support is a separate distribution each, so a group appears in the CLI only
+when its package is installed.

opensb-0.0.1/pyproject.toml

@@ -0,0 +1,38 @@
+[project]
+name = "opensb"
+dynamic = ["version"]
+description = "Command line for SwitchBot devices over BLE, with no cloud and no state on disk"
+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", "cli", "home-assistant"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Home Automation",
+    "Typing :: Typed",
+]
+dependencies = ["opensb-core[ble]", "typer>=0.12", "rich>=13"]
+
+[project.optional-dependencies]
+keypad = ["opensb-keypad"]
+lockpro = ["opensb-lockpro"]
+all = ["opensb[keypad,lockpro]"]
+
+[project.scripts]
+opensb = "opensb.cli.main:main"
+
+[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-0.0.1/src/opensb/cli/__init__.py

@@ -0,0 +1 @@
+"""The `opensb` command line."""

opensb-0.0.1/src/opensb/cli/common.py

@@ -0,0 +1,183 @@
+"""Plumbing every command group shares: the target, the runner, the renderer."""
+
+import asyncio
+import json
+import os
+import time
+from collections.abc import Awaitable, Generator, Mapping
+from contextlib import contextmanager
+from datetime import date, datetime
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from opensb.ble.errors import OpenSBError
+from opensb.ble.models import CommunicationKey
+from pydantic import BaseModel, ConfigDict, Field, ValidationError
+from rich.console import Console
+from rich.table import Table
+from rich.text import Text
+
+console = Console()
+error_console = Console(stderr=True, style="bold red")
+
+KEY_FILE_ENV = "OPENSB_KEY_FILE"
+
+KeyFile = Annotated[
+    Path | None,
+    typer.Option(
+        "--key-file",
+        help=f"Communication key JSON, or set {KEY_FILE_ENV}.",
+        show_default=False,
+    ),
+]
+Mac = Annotated[
+    str | None, typer.Option("--mac", help="Address to talk to, overriding the key file's.")
+]
+Adapter = Annotated[str | None, typer.Option("--adapter", help="Bluetooth adapter to use.")]
+Minutes = Annotated[int, typer.Option("--minutes", help="Validity window, in minutes.")]
+
+
+class Target(BaseModel):
+    """Where to find the device. Built per invocation and carried on the typer context."""
+
+    model_config = ConfigDict(frozen=True)
+
+    key_file: Path | None = Field(default=None, description="Key JSON the caller pointed at")
+    mac: str | None = Field(default=None, description="Address overriding the key file's")
+    adapter: str | None = Field(default=None, description="Bluetooth adapter to use")
+
+    def key(self) -> CommunicationKey:
+        """Read the key the caller pointed at."""
+        from_env = os.environ.get(KEY_FILE_ENV)
+        path = self.key_file or (Path(from_env) if from_env else None)
+        if path is None:
+            raise OpenSBError(
+                f"no key given: pass --key-file, or set {KEY_FILE_ENV}.\n"
+                "The communication key is minted per device by SwitchBot against your "
+                "account; this tool does not fetch it."
+            )
+        try:
+            payload = json.loads(path.read_text())
+        except FileNotFoundError as err:
+            raise OpenSBError(f"no key file at {path}") from err
+        except json.JSONDecodeError as err:
+            raise OpenSBError(f"{path} is not valid JSON: {err}") from err
+        try:
+            key = CommunicationKey.model_validate(payload)
+        except (ValidationError, ValueError) as err:
+            raise OpenSBError(f"{path} is not a key file: {err}") from err
+        return key.model_copy(update={"mac": self.mac}) if self.mac else key
+
+
+def target(context: typer.Context) -> Target:
+    """The invocation's target, as the root callback built it."""
+    assert isinstance(context.obj, Target)
+    return context.obj
+
+
+def run[T](coroutine: Awaitable[T]) -> T:
+    """Run a command, turning our errors into a clean exit rather than a traceback."""
+    try:
+        return asyncio.run(coroutine)
+    except OpenSBError as err:
+        error_console.print(str(err))
+        raise typer.Exit(1) from None
+    except KeyboardInterrupt:
+        error_console.print("interrupted")
+        raise typer.Exit(130) from None
+
+
+@contextmanager
+def progress(message: str) -> Generator[None]:
+    """A spinner, but only for a human watching a terminal."""
+    if not console.is_terminal:
+        yield
+        return
+    with console.status(message):
+        yield
+
+
+class Rows:
+    """Tabular output that suits whoever is reading it.
+
+    Aligned and borderless on a terminal; tab separated with no padding, markup or
+    headings when piped, so each line is one record for `grep` and `cut`.
+    """
+
+    def __init__(self, *columns: str, headers: bool = True) -> None:
+        self.columns = columns
+        self.headers = headers
+        self._rows: list[tuple[str, ...]] = []
+        self._sections: set[int] = set()
+
+    def add(self, *cells: str) -> None:
+        self._rows.append(cells)
+
+    def section(self) -> None:
+        """A blank rule before the next row. Terminal only."""
+        self._sections.add(len(self._rows))
+
+    def __bool__(self) -> bool:
+        return bool(self._rows)
+
+    def render(self) -> None:
+        if not console.is_terminal:
+            for row in self._rows:
+                print("\t".join(Text.from_markup(cell).plain for cell in row))
+            return
+        table = Table(box=None, pad_edge=False, show_header=self.headers, header_style="dim")
+        for column in self.columns:
+            table.add_column(column, overflow="fold")
+        for index, row in enumerate(self._rows):
+            if index in self._sections:
+                table.add_section()
+            table.add_row(*row)
+        console.print(table)
+
+
+def day(unix_seconds: int) -> str:
+    """The entry's date, as a heading. Today and yesterday are named."""
+    today = date.today()
+    when_ = datetime.fromtimestamp(unix_seconds).date()
+    if when_ == today:
+        return "today"
+    if (today - when_).days == 1:
+        return "yesterday"
+    return when_.strftime("%A %d %B" if when_.year == today.year else "%d %B %Y")
+
+
+def when(unix_seconds: int) -> str:
+    if not unix_seconds:
+        return "-"
+    return time.strftime("%Y-%m-%d %H:%M:%S", time.localtime(unix_seconds))
+
+
+def name(value: object, *vocabularies: Mapping[str, object]) -> str:
+    """Render a value the way it is typed in.
+
+    A vocabulary maps the words a command accepts onto enum members; the word wins
+    where there is one, so `--type temporary` reads back as `temporary`.
+    """
+    for vocabulary in vocabularies:
+        for word, member in vocabulary.items():
+            if member is value:
+                return word
+    label = getattr(value, "name", None)
+    return label.lower().replace("_", " ") if label else str(value)
+
+
+def choice[T](table: Mapping[str, T], value: str, hint: str) -> T:
+    try:
+        return table[value]
+    except KeyError:
+        raise typer.BadParameter(
+            f"expected one of {', '.join(sorted(table))}", param_hint=hint
+        ) from None
+
+
+def switch(state: str) -> bool:
+    """Read a two-position setting, in the same 1 and 0 the tool prints back."""
+    if state not in ("1", "0"):
+        raise typer.BadParameter("expected 1 or 0", param_hint="state")
+    return state == "1"

opensb-0.0.1/src/opensb/cli/keypad.py

@@ -0,0 +1,533 @@
+"""`opensb keypad` -- passcodes, cards, fingerprints and the keypad's own log."""
+
+import time
+from collections.abc import Awaitable, Callable
+from typing import Annotated
+
+import typer
+from opensb.ble.models import Window
+from opensb.cli.common import (
+    Minutes,
+    Rows,
+    Target,
+    choice,
+    console,
+    day,
+    name,
+    progress,
+    run,
+    switch,
+    target,
+    when,
+)
+from opensb.keypad import discovery
+from opensb.keypad.device import FINGER_COLLECT_SECONDS, Keypad
+from opensb.keypad.enums import (
+    Backlight,
+    CredentialKind,
+    FingerType,
+    LockButton,
+    NfcType,
+    PasswordType,
+)
+
+# Passcodes and cards are numbered on separate scales -- "emergency" is 3 for a code
+# and 2 for a card -- so the tables stay apart.
+PASSWORD_TYPES = {
+    "permanent": PasswordType.PERMANENT,
+    "temporary": PasswordType.TIME_LIMIT,
+    "onetime": PasswordType.ONCE,
+    "emergency": PasswordType.URGENT,
+}
+NFC_TYPES = {
+    "permanent": NfcType.PERMANENT,
+    "temporary": NfcType.TIME_LIMIT,
+    "emergency": NfcType.URGENT,
+}
+FINGER_TYPES = {
+    "permanent": FingerType.PERMANENT,
+    "temporary": FingerType.TIME_LIMIT,
+    "emergency": FingerType.URGENT,
+}
+CREDENTIAL_KINDS = {
+    "password": CredentialKind.PASSWORD,
+    "card": CredentialKind.NFC,
+    "finger": CredentialKind.FINGERPRINT,
+}
+BACKLIGHT_MODES = {"off": Backlight.OFF, "auto": Backlight.AUTO, "on": Backlight.ALWAYS_ON}
+LOCK_BUTTON_STATES = {
+    "off": LockButton.DISABLED,
+    "on": LockButton.ENABLED,
+    "timed": LockButton.TIMED,
+}
+
+FORCE_WARNING = (
+    "--force makes the keypad write its own data ONTO the card, destroying whatever it "
+    "held. Only use a blank or expendable card -- never a transit pass, bank card or "
+    "office badge."
+)
+
+app = typer.Typer(help=__doc__, no_args_is_help=True)
+code_app = typer.Typer(help="Passcodes stored in the keypad.", no_args_is_help=True)
+card_app = typer.Typer(help="NFC cards enrolled on the keypad.", no_args_is_help=True)
+finger_app = typer.Typer(help="Fingerprints on the keypad.", no_args_is_help=True)
+settings_app = typer.Typer(help="Device settings.", no_args_is_help=True)
+app.add_typer(code_app, name="code")
+app.add_typer(card_app, name="card")
+app.add_typer(finger_app, name="finger")
+app.add_typer(settings_app, name="settings")
+
+
+def with_keypad[T](target_: Target, action: Callable[[Keypad], Awaitable[T]]) -> T:
+    """Connect to the keypad `target_` names, run `action`, disconnect."""
+
+    async def go() -> T:
+        async with Keypad.over_ble(target_.key(), adapter=target_.adapter) as keypad:
+            return await action(keypad)
+
+    return run(go())
+
+
+# --- discovery and keys ---
+
+
+@app.command()
+def scan(
+    seconds: Annotated[float, typer.Option(help="How long to listen.")] = 10.0,
+) -> None:
+    """List Keypad Touch devices in range, with what they broadcast."""
+    keypads = run(discovery.discover(seconds))
+    if not keypads:
+        console.print("no keypad seen -- press a key on it to wake it, then scan again")
+        return
+    rows = Rows("address", "name", "rssi", "battery", "alerts")
+    for keypad in keypads:
+        alerts = [
+            field
+            for field, flagged in keypad.state.model_dump().items()
+            if field.endswith("_alert") and flagged
+        ]
+        rows.add(
+            keypad.address,
+            keypad.name or "",
+            str(keypad.rssi),
+            f"{keypad.state.battery}%",
+            ", ".join(alerts) or "-",
+        )
+    rows.render()
+
+
+# --- the device ---
+
+
+@app.command()
+def info(context: typer.Context) -> None:
+    """Battery, versions and every device setting."""
+
+    async def action(keypad: Keypad) -> None:
+        device = await keypad.info()
+        quick = await keypad.quick_unlock()
+        rows = Rows("setting", "value", headers=False)
+        rows.add("battery", f"{device.battery}%")
+        rows.add("versions", f"ble {device.ble_version}, hardware {device.hardware_version}")
+        rows.add("fingerprint reader", f"{device.has_fingerprint:d}")
+        # The window is reported whatever the state, so it is shown whenever it is set.
+        window = f" ({device.lock_button_seconds}s)" if device.lock_button_seconds else ""
+        rows.add("lock button", f"{name(device.lock_button, LOCK_BUTTON_STATES)}{window}")
+        rows.add("keypad", f"{not device.keyboard_disabled:d}")
+        rows.add("removal alarm", f"{device.removal_alarm:d}")
+        rows.add(
+            "backlight",
+            f"{name(device.backlight, BACKLIGHT_MODES)}, level {device.backlight_level}",
+        )
+        rows.add("sound", f"{device.sound:d}")
+        rows.add("time penalty", str(device.time_penalty))
+        rows.add("quick unlock", f"{quick:d}")
+        rows.render()
+
+    with_keypad(target(context), action)
+
+
+@app.command()
+def status(context: typer.Context) -> None:
+    """What each credential engine is doing right now."""
+
+    async def action(keypad: Keypad) -> None:
+        state = await keypad.status()
+        rows = Rows("engine", "status", "detail", headers=False)
+        rows.add("passcode", name(state.password), "")
+        rows.add("card", name(state.nfc), "")
+        rows.add(
+            "fingerprint",
+            name(state.fingerprint),
+            f"{state.fingerprint_step} press(es), verdicts {state.fingerprint_step_results}",
+        )
+        rows.add("face", str(state.face), f"error {state.face_error}")
+        rows.render()
+
+    with_keypad(target(context), action)
+
+
+@app.command("log")
+def read_log(
+    context: typer.Context,
+    limit: Annotated[int, typer.Option(help="How many entries to read.")] = 20,
+    since: Annotated[
+        int | None, typer.Option(help="Read entries older than this unix time.")
+    ] = None,
+    raw: Annotated[
+        bool, typer.Option("--raw", help="Show the source, action and value bytes too.")
+    ] = False,
+) -> None:
+    """Walk the keypad's own event log, newest first."""
+
+    async def action(keypad: Keypad) -> None:
+        # A piped line has to stand on its own, so the date goes into the row there.
+        grouped = console.is_terminal
+        clock, stamp = "%H:%M:%S", "%Y-%m-%d %H:%M:%S"
+        columns = ["time", "event"] + (["src", "act", "val"] if raw else [])
+        rows = Rows(*columns)
+        shown = None
+
+        async for entry in keypad.read_log(since, limit):
+            if grouped and (heading := day(entry.at)) != shown:
+                rows.section()
+                rows.add(f"[bold]{heading}[/bold]", "")
+                shown = heading
+            summary = entry.summary
+            cells = [
+                time.strftime(clock if grouped else stamp, time.localtime(entry.at)),
+                f"[red]{summary}[/red]" if entry.is_error else summary,
+            ]
+            if raw:
+                cells += [str(int(entry.source)), str(entry.action), str(entry.value)]
+            rows.add(*cells)
+        rows.render() if rows else console.print("the log is empty")
+
+    with_keypad(target(context), action)
+
+
+# --- passcodes ---
+
+
+@code_app.command("list")
+def code_list(
+    context: typer.Context,
+    slots: Annotated[int, typer.Option(help="How many slots to walk.")] = 100,
+) -> None:
+    """List every stored passcode. Read-only, and about a minute for a full sweep."""
+
+    async def action(keypad: Keypad) -> None:
+        rows = Rows("slot", "code", "type", "from", "until")
+        with progress(f"walking {slots} slots…"):
+            async for stored in keypad.list_passcodes(slots):
+                rows.add(
+                    str(stored.slot),
+                    stored.code,
+                    name(stored.password_type, PASSWORD_TYPES),
+                    when(stored.starts_at),
+                    when(stored.ends_at),
+                )
+        rows.render() if rows else console.print("no passcodes stored")
+
+    with_keypad(target(context), action)
+
+
+@code_app.command("get")
+def code_get(
+    context: typer.Context, slot: Annotated[int, typer.Argument(help="Slot to read.")]
+) -> None:
+    """Read one passcode slot."""
+
+    async def action(keypad: Keypad) -> None:
+        stored = await keypad.read_passcode(slot)
+        if stored is None:
+            console.print(f"slot {slot} is empty")
+            return
+        kind = name(stored.password_type, PASSWORD_TYPES)
+        console.print(
+            f"slot {slot}: [bold]{stored.code}[/bold] ({kind}), "
+            f"{when(stored.starts_at)} → {when(stored.ends_at)}"
+        )
+
+    with_keypad(target(context), action)
+
+
+@code_app.command("add")
+def code_add(
+    context: typer.Context,
+    code: Annotated[str, typer.Argument(help="The digits, e.g. 445566.")],
+    kind: Annotated[
+        str, typer.Option("--type", help="permanent|temporary|onetime|emergency")
+    ] = "permanent",
+    minutes: Minutes = 60,
+    slot: Annotated[int, typer.Option(help="Slot to write; the keypad picks by default.")] = 0xFF,
+) -> None:
+    """Store a passcode.
+
+    temporary and onetime take a window of --minutes from now; emergency is a duress
+    code that opens the lock and raises the alarm.
+    """
+    password_type = choice(PASSWORD_TYPES, kind, "--type")
+    timed = password_type in (PasswordType.TIME_LIMIT, PasswordType.ONCE)
+    window = Window.for_minutes(minutes) if timed else None
+
+    async def action(keypad: Keypad) -> None:
+        assigned = await keypad.add_passcode(code, password_type, window=window, slot=slot)
+        detail = f", valid until {when(window.ends_at)}" if window else ""
+        kind = name(password_type, PASSWORD_TYPES)
+        console.print(f"stored in slot [bold]{assigned}[/bold] as {kind}{detail}")
+
+    with_keypad(target(context), action)
+
+
+@code_app.command("delete")
+def code_delete(
+    context: typer.Context,
+    slots: Annotated[list[int], typer.Argument(help="Slots to erase.")],
+) -> None:
+    """Erase passcode slots, reporting what was in each."""
+
+    async def action(keypad: Keypad) -> None:
+        for slot in slots:
+            before = await keypad.read_passcode(slot)
+            if before is None:
+                console.print(f"slot {slot}: already empty")
+                continue
+            await keypad.delete_passcode(slot)
+            after = await keypad.read_passcode(slot)
+            state = "empty" if after is None else f"[red]still holds {after.code}[/red]"
+            console.print(f"slot {slot}: erased {before.code} → {state}")
+
+    with_keypad(target(context), action)
+
+
+# --- cards ---
+
+
+@card_app.command("list")
+def card_list(
+    context: typer.Context,
+    slots: Annotated[int, typer.Option(help="How many slots to walk.")] = 100,
+) -> None:
+    """List every enrolled card. Read-only."""
+
+    async def action(keypad: Keypad) -> None:
+        rows = Rows("slot", "type", "data")
+        with progress(f"walking {slots} slots…"):
+            async for card in keypad.list_cards(slots):
+                label = "reserved, empty" if card.is_placeholder else str(card.card_type)
+                rows.add(str(card.slot), label, card.data.hex())
+        rows.render() if rows else console.print("no cards enrolled")
+
+    with_keypad(target(context), action)
+
+
+@card_app.command("add")
+def card_add(
+    context: typer.Context,
+    kind: Annotated[
+        str, typer.Option("--type", help="permanent|temporary|emergency")
+    ] = "permanent",
+    minutes: Minutes = 60,
+    force: Annotated[bool, typer.Option("--force", help=FORCE_WARNING)] = False,
+    wait: Annotated[int, typer.Option(help="Seconds to wait for the card.")] = 30,
+) -> None:
+    """Enrol an NFC card.
+
+    The keypad takes only SwitchBot's own cards; anything else is refused.
+    """
+    nfc_type = choice(NFC_TYPES, kind, "--type")
+    window = Window.for_minutes(minutes) if nfc_type is NfcType.TIME_LIMIT else None
+    if force:
+        console.print(f"[bold red]{FORCE_WARNING}[/bold red]")
+        typer.confirm("Overwrite the card you are about to present?", abort=True)
+
+    async def action(keypad: Keypad) -> None:
+        def ready(slot: int) -> None:
+            console.print(f"reserved slot {slot} — [bold]hold the card to the keypad now[/bold]")
+
+        enrolment = await keypad.enrol_card(
+            nfc_type, window=window, force=force, wait_seconds=wait, on_ready=ready
+        )
+        console.print(f"card committed to slot [bold]{enrolment.slot}[/bold]")
+
+    with_keypad(target(context), action)
+
+
+@card_app.command("delete")
+def card_delete(
+    context: typer.Context, slots: Annotated[list[int], typer.Argument(help="Slots to erase.")]
+) -> None:
+    """Erase card slots."""
+
+    async def action(keypad: Keypad) -> None:
+        for slot in slots:
+            if await keypad.read_card(slot) is None:
+                console.print(f"card slot {slot}: already empty")
+                continue
+            await keypad.delete_card(slot)
+            still = await keypad.read_card(slot)
+            console.print(
+                f"card slot {slot}: erased → "
+                + ("empty" if still is None else "[red]still present[/red]")
+            )
+
+    with_keypad(target(context), action)
+
+
+# --- fingerprints ---
+
+
+@finger_app.command("add")
+def finger_add(
+    context: typer.Context,
+    kind: Annotated[
+        str, typer.Option("--type", help="permanent|temporary|emergency")
+    ] = "permanent",
+    minutes: Minutes = 60,
+    enhance: Annotated[
+        bool, typer.Option("--enhance", help="Second print for a finger already enrolled.")
+    ] = False,
+    collect: Annotated[
+        int, typer.Option(help="Seconds to leave the keypad alone while it reads.")
+    ] = FINGER_COLLECT_SECONDS,
+) -> None:
+    """Enrol a fingerprint -- several presses of the same finger.
+
+    The tool disconnects while the reader works; the keypad will not scan otherwise.
+    """
+    finger_type = choice(FINGER_TYPES, kind, "--type")
+    window = Window.for_minutes(minutes) if finger_type is FingerType.TIME_LIMIT else None
+
+    async def action(keypad: Keypad) -> None:
+        def ready(slot: int) -> None:
+            console.print(
+                f"reserved slot {slot} — [bold]press the same finger now[/bold], "
+                f"lifting between reads"
+            )
+            console.print(f"  (disconnected on purpose; reading the result in {collect}s)")
+
+        enrolment = await keypad.enrol_fingerprint(
+            finger_type,
+            window=window,
+            enhance=enhance,
+            collect_seconds=collect,
+            on_ready=ready,
+        )
+        console.print(
+            f"collected {enrolment.presses} press(es), committed to slot "
+            f"[bold]{enrolment.slot}[/bold]"
+        )
+        if enhance:
+            console.print(
+                "[yellow]Write this slot down next to the original: an enhanced finger "
+                "occupies two slots, deleting it means deleting both, and nothing on the "
+                "keypad can pair them for you.[/yellow]"
+            )
+
+    with_keypad(target(context), action)
+
+
+@finger_app.command("delete")
+def finger_delete(
+    context: typer.Context, slots: Annotated[list[int], typer.Argument(help="Slots to erase.")]
+) -> None:
+    """Erase fingerprint slots. A delete cannot be confirmed: the slot query is an echo."""
+
+    async def action(keypad: Keypad) -> None:
+        for slot in slots:
+            await keypad.delete_fingerprint(slot)
+            console.print(f"fingerprint slot {slot}: delete acknowledged")
+
+    with_keypad(target(context), action)
+
+
+# --- settings ---
+
+
+@settings_app.command("keyboard")
+def settings_keyboard(
+    context: typer.Context,
+    state: Annotated[str, typer.Argument(help="1|0")],
+) -> None:
+    """Enable or disable the keypad entirely."""
+    enabled = switch(state)
+    with_keypad(target(context), lambda keypad: keypad.set_keyboard_disabled(not enabled))
+    console.print(f"keypad {enabled:d}")
+
+
+@settings_app.command("alarm")
+def settings_alarm(
+    context: typer.Context,
+    state: Annotated[str, typer.Argument(help="1|0, or silence")],
+) -> None:
+    """Arm, disarm or silence the tamper alarm."""
+    if state == "silence":
+        with_keypad(target(context), lambda keypad: keypad.silence_removal_alarm())
+        console.print("removal alarm silenced, still armed")
+        return
+    enabled = switch(state)
+    with_keypad(target(context), lambda keypad: keypad.set_removal_alarm(enabled))
+    console.print(f"removal alarm {enabled:d}")
+
+
+@settings_app.command("backlight")
+def settings_backlight(
+    context: typer.Context,
+    mode: Annotated[str, typer.Argument(help="off|auto|on")],
+    level: Annotated[int, typer.Option(help="Brightness, 1-5.")] = 0,
+) -> None:
+    """Set the backlight mode and brightness."""
+    backlight = choice(BACKLIGHT_MODES, mode, "mode")
+    with_keypad(target(context), lambda keypad: keypad.set_backlight(backlight, level))
+    console.print(f"backlight {mode}" + (f", level {level}" if level else ""))
+
+
+@settings_app.command("sound")
+def settings_sound(
+    context: typer.Context, state: Annotated[str, typer.Argument(help="1|0")]
+) -> None:
+    """Turn the keypress beep on or off."""
+    enabled = switch(state)
+    with_keypad(target(context), lambda keypad: keypad.set_sound(enabled))
+    console.print(f"sound {enabled:d}")
+
+
+@settings_app.command("lock-button")
+def settings_lock_button(
+    context: typer.Context,
+    state: Annotated[str, typer.Argument(help="on|off|timed")],
+    seconds: Annotated[int, typer.Option(help="Window for `timed`, in seconds.")] = 0,
+) -> None:
+    """Enable, disable or time-limit the keypad's lock button."""
+    button = choice(LOCK_BUTTON_STATES, state, "state")
+    with_keypad(target(context), lambda keypad: keypad.set_lock_button(button, seconds))
+    console.print(f"lock button {state}" + (f", window {seconds}s" if seconds else ""))
+
+
+@settings_app.command("quick-unlock")
+def settings_quick_unlock(
+    context: typer.Context, state: Annotated[str, typer.Argument(help="1|0")]
+) -> None:
+    """Open on the code alone, without the confirm key."""
+    enabled = switch(state)
+    with_keypad(target(context), lambda keypad: keypad.set_quick_unlock(enabled))
+    console.print(f"quick unlock {enabled:d}")
+
+
+@settings_app.command("clear")
+def settings_clear(
+    context: typer.Context,
+    what: Annotated[str, typer.Argument(help="penalty|alarm")],
+    kind: Annotated[str, typer.Argument(help="password|card|finger")],
+) -> None:
+    """Clear a lockout after failed attempts, or acknowledge a duress alarm."""
+    credential = choice(CREDENTIAL_KINDS, kind, "kind")
+    if what == "penalty":
+        with_keypad(target(context), lambda keypad: keypad.clear_time_penalty(credential))
+    elif what == "alarm":
+        with_keypad(target(context), lambda keypad: keypad.clear_urgent_alarm(credential))
+    else:
+        raise typer.BadParameter("expected penalty or alarm", param_hint="what")
+    console.print(f"{what} cleared for {kind}")

opensb-0.0.1/src/opensb/cli/lockpro.py

@@ -0,0 +1,318 @@
+"""`opensb lockpro` -- lock, unlock, status, settings, calibration and the lock's own log."""
+
+import time
+from collections.abc import Awaitable, Callable
+from typing import Annotated
+
+import typer
+from opensb.cli.common import Rows, Target, choice, console, day, name, run, switch, target
+from opensb.lockpro import discovery
+from opensb.lockpro.device import Lock
+from opensb.lockpro.enums import KeyAction, KeyTrigger, LatchType, LockAlert
+from opensb.lockpro.models import BatteryBay, TimedSetting
+
+KEY_ACTIONS = {"lock": KeyAction.LOCK, "unlock": KeyAction.UNLOCK, "toggle": KeyAction.TOGGLE}
+KEY_TRIGGERS = {"single": KeyTrigger.SINGLE, "double": KeyTrigger.DOUBLE}
+ALERTS = {"door": LockAlert.DOOR_LEFT_OPEN, "unlocked": LockAlert.NOT_LOCKED}
+LATCH_TYPES = {"normal": LatchType.NORMAL, "night": LatchType.NIGHT_LATCH}
+
+app = typer.Typer(help=__doc__, no_args_is_help=True)
+# No `no_args_is_help`: a bare `settings` prints what the lock reports.
+settings_app = typer.Typer(help="Lock settings.")
+app.add_typer(settings_app, name="settings")
+
+
+def with_lock[T](target_: Target, action: Callable[[Lock], Awaitable[T]]) -> T:
+    """Connect to the lock `target_` names, run `action`, disconnect."""
+
+    async def go() -> T:
+        async with Lock.over_ble(target_.key(), adapter=target_.adapter) as lock:
+            return await action(lock)
+
+    return run(go())
+
+
+@app.command()
+def scan(seconds: Annotated[float, typer.Option(help="How long to listen.")] = 10.0) -> None:
+    """List Lock Pro devices in range, with what they broadcast."""
+    locks = run(discovery.discover(seconds))
+    if not locks:
+        console.print("no lock seen")
+        return
+    rows = Rows("address", "name", "rssi", "battery", "status")
+    for lock in locks:
+        rows.add(
+            lock.address,
+            lock.name or "",
+            str(lock.rssi),
+            f"{lock.state.battery}%",
+            name(lock.state.status),
+        )
+    rows.render()
+
+
+@app.command()
+def status(context: typer.Context) -> None:
+    """Where the bolt is, and the battery."""
+
+    async def action(lock: Lock) -> None:
+        info = await lock.info()
+        power = await lock.battery()
+        rows = Rows("setting", "value", headers=False)
+        rows.add("status", name(info.status))
+        rows.add("calibrated", f"{info.calibrated:d}")
+        rows.add("door open", f"{info.door_open:d}")
+        rows.add("door left open alarm", f"{info.door_not_closed_alert:d}")
+        rows.add("left unlocked alarm", f"{info.not_locked_alert:d}")
+        rows.add("battery", f"{power.battery}%")
+        rows.add("firmware", f"{power.firmware}")
+        rows.render()
+
+    with_lock(target(context), action)
+
+
+@app.command("lock")
+def lock_it(context: typer.Context) -> None:
+    """Throw the bolt."""
+    info = with_lock(target(context), lambda lock: lock.lock())
+    console.print(f"lock\t{name(info.status)}")
+
+
+@app.command("unlock")
+def unlock_it(
+    context: typer.Context,
+    latch: Annotated[
+        bool, typer.Option("--latch/--no-latch", help="Also pull the latch, opening the door.")
+    ] = True,
+) -> None:
+    """Withdraw the bolt."""
+    info = with_lock(target(context), lambda lock: lock.unlock(unlatch=latch))
+    console.print(f"unlock\t{name(info.status)}")
+
+
+@app.command("log")
+def read_log(
+    context: typer.Context,
+    limit: Annotated[int, typer.Option(help="How many entries to read.")] = 20,
+    since: Annotated[int | None, typer.Option(help="Entries older than this unix time.")] = None,
+) -> None:
+    """Walk the lock's event log, newest first."""
+
+    async def action(lock: Lock) -> None:
+        grouped = console.is_terminal
+        clock, stamp = "%H:%M:%S", "%Y-%m-%d %H:%M:%S"
+        rows = Rows("time", "source", "action", "value")
+        shown = None
+        async for entry in lock.read_log(since, limit):
+            if grouped and (heading := day(entry.at)) != shown:
+                rows.section()
+                rows.add(f"[bold]{heading}[/bold]", "")
+                shown = heading
+            rows.add(
+                time.strftime(clock if grouped else stamp, time.localtime(entry.at)),
+                name(entry.source),
+                str(entry.action),
+                str(entry.value),
+            )
+        rows.render() if rows else console.print("the log is empty")
+
+    with_lock(target(context), action)
+
+
+@app.command("emergency")
+def emergency(
+    context: typer.Context,
+    reverse: Annotated[
+        bool, typer.Option("--reverse", help="Turn the other way, if the bolt went wrong.")
+    ] = False,
+) -> None:
+    """Drive the motor until it stalls. Clears the calibration.
+
+    The only control that works on a jammed lock. Afterwards the lock does not know
+    its travel, so run `calibrate`, and do not trust the status it reports until you
+    have.
+    """
+    with_lock(target(context), lambda lock: lock.emergency_unlock(reverse))
+    console.print("motor driven to a stall; the lock is now uncalibrated -- run `calibrate`")
+
+
+@app.command("calibrate")
+def calibrate(
+    context: typer.Context,
+    latch: Annotated[
+        str | None,
+        typer.Option(help="normal|night. Only send this if the lock reported the type."),
+    ] = None,
+) -> None:
+    """Teach the lock its travel again, step by step.
+
+    Every step runs on one connection. Sent separately they are all accepted while
+    nothing is recorded, and the lock stays uncalibrated.
+    """
+    latch_type = choice(LATCH_TYPES, latch, "latch") if latch is not None else None
+
+    def step(message: str) -> None:
+        console.print(message)
+        typer.confirm("done?", abort=True)
+
+    async def action(lock: Lock) -> None:
+        await lock.enter_calibration()
+        step("the motor is released -- turn the knob to LOCKED, with the door shut")
+        await lock.set_lock_position()
+        step("now turn the knob to UNLOCKED")
+        await lock.set_unlock_position()
+        step("now open the door")
+        await lock.set_door_open_position()
+        if latch_type is not None:
+            await lock.set_latch_type(latch_type)
+        console.print("testing the unlock position")
+        await lock.test_unlock()
+        console.print("testing the lock position")
+        await lock.test_lock()
+        await lock.finish_calibration()
+        info = await lock.info()
+        console.print(f"calibrated\t{info.calibrated:d}")
+
+    with_lock(target(context), action)
+
+
+@settings_app.callback(invoke_without_command=True)
+def settings_show(context: typer.Context) -> None:
+    """Everything the lock reports about how it is configured."""
+    if context.invoked_subcommand is not None:
+        return
+
+    async def action(lock: Lock) -> None:
+        current = await lock.settings()
+        rows = Rows("setting", "value", headers=False)
+        rows.add("light", f"{current.flags.light:d}")
+        rows.add("sound", f"{current.flags.sound:d}")
+        rows.add("manual unlock linkage", f"{current.flags.linkage:d}")
+        rows.add("lock go", f"{current.flags.lock_go:d}")
+        rows.add("button", f"{current.flags.key_enabled:d}")
+        rows.add("button press", name(current.flags.key_trigger, KEY_TRIGGERS))
+        rows.add("button action", name(current.flags.key_action, KEY_ACTIONS))
+        rows.add("settings byte", f"0x{current.flags.raw:02x}")
+        rows.add("auto lock", _timed(current.auto_lock))
+        rows.add("auto lock paused", f"{current.auto_lock_paused:d}")
+        rows.add("force lock", _timed(current.force_lock))
+        rows.add("latch keep time", f"{current.latch_keep_time}s")
+        rows.add("door left open alarm", _timed(current.door_left_open_alert))
+        rows.add("left unlocked alarm", _timed(current.not_locked_alert))
+        rows.add("left battery", _bay(current.battery_bays.left))
+        rows.add("right battery", _bay(current.battery_bays.right))
+        rows.render()
+
+    with_lock(target(context), action)
+
+
+def _timed(setting: TimedSetting) -> str:
+    """A timed setting as the tool takes it back: the flag, then its delay."""
+    return f"{setting.enabled:d}" + (f", {setting.seconds}s" if setting.enabled else "")
+
+
+def _bay(bay: BatteryBay) -> str:
+    return f"{bay.battery}%" if bay.inserted else "empty"
+
+
+@settings_app.command("light")
+def settings_light(
+    context: typer.Context, state: Annotated[str, typer.Argument(help="1|0")]
+) -> None:
+    """The indicator light on the lock body."""
+    enabled = switch(state)
+    with_lock(target(context), lambda lock: lock.set_light(enabled))
+    console.print(f"light {enabled:d}")
+
+
+@settings_app.command("sound")
+def settings_sound(
+    context: typer.Context, state: Annotated[str, typer.Argument(help="1|0")]
+) -> None:
+    """Beeps and voice prompts."""
+    enabled = switch(state)
+    with_lock(target(context), lambda lock: lock.set_sound(enabled))
+    console.print(f"sound {enabled:d}")
+
+
+@settings_app.command("linkage")
+def settings_linkage(
+    context: typer.Context, state: Annotated[str, typer.Argument(help="1|0")]
+) -> None:
+    """Report a by-hand unlock to whatever is linked to the lock."""
+    enabled = switch(state)
+    with_lock(target(context), lambda lock: lock.set_manual_unlock_linkage(enabled))
+    console.print(f"manual unlock linkage {enabled:d}")
+
+
+@settings_app.command("button")
+def settings_button(
+    context: typer.Context,
+    state: Annotated[str, typer.Argument(help="1|0")],
+    action: Annotated[str, typer.Option(help="lock|unlock|toggle")] = "toggle",
+    press: Annotated[str, typer.Option(help="single|double")] = "single",
+) -> None:
+    """What the lock's own button does. Switching it off keeps the rest."""
+    enabled = switch(state)
+    what = choice(KEY_ACTIONS, action, "action")
+    how = choice(KEY_TRIGGERS, press, "press")
+    with_lock(target(context), lambda lock: lock.set_key(enabled, what, how))
+    console.print(f"button {enabled:d}" + (f", {press} press, {action}" if enabled else ""))
+
+
+@settings_app.command("auto-lock")
+def settings_auto_lock(
+    context: typer.Context,
+    state: Annotated[str, typer.Argument(help="1|0")],
+    seconds: Annotated[int, typer.Option(help="Delay before it locks itself.")] = 0,
+) -> None:
+    """Lock again by itself after a delay."""
+    enabled = switch(state)
+    with_lock(target(context), lambda lock: lock.set_auto_lock(enabled, seconds))
+    console.print(f"auto lock {enabled:d}" + (f", {seconds}s" if enabled else ""))
+
+
+@settings_app.command("force-lock")
+def settings_force_lock(
+    context: typer.Context,
+    state: Annotated[str, typer.Argument(help="1|0")],
+    seconds: Annotated[int, typer.Option(help="Delay before it locks itself.")] = 0,
+) -> None:
+    """Lock even when the door is reported open."""
+    enabled = switch(state)
+    with_lock(target(context), lambda lock: lock.set_force_lock(enabled, seconds))
+    console.print(f"force lock {enabled:d}" + (f", {seconds}s" if enabled else ""))
+
+
+@settings_app.command("pause")
+def settings_pause(
+    context: typer.Context, state: Annotated[str, typer.Argument(help="1|0")]
+) -> None:
+    """Suspend auto-lock without making it forget its delay."""
+    paused = switch(state)
+    with_lock(target(context), lambda lock: lock.set_auto_lock_paused(paused))
+    console.print(f"auto lock paused {paused:d}")
+
+
+@settings_app.command("latch")
+def settings_latch(
+    context: typer.Context,
+    seconds: Annotated[int, typer.Argument(help="Seconds to hold the latch back.")],
+) -> None:
+    """How long the latch stays retracted before springing back."""
+    with_lock(target(context), lambda lock: lock.set_latch_keep_time(seconds))
+    console.print(f"latch keep time {seconds}s")
+
+
+@settings_app.command("alarm")
+def settings_alarm(
+    context: typer.Context,
+    kind: Annotated[str, typer.Argument(help="door|unlocked")],
+    state: Annotated[str, typer.Argument(help="1|0")],
+    seconds: Annotated[int, typer.Option(help="Delay before it sounds.")] = 0,
+) -> None:
+    """Arm the door-left-open or left-unlocked alarm, and set its delay."""
+    alert = choice(ALERTS, kind, "kind")
+    enabled = switch(state)
+    with_lock(target(context), lambda lock: lock.set_alert(alert, enabled, seconds))
+    console.print(f"{kind} alarm {enabled:d}" + (f", {seconds}s" if enabled else ""))

opensb-0.0.1/src/opensb/cli/main.py

@@ -0,0 +1,57 @@
+"""`opensb` -- drive SwitchBot devices from the shell, over BLE and nothing else."""
+
+from importlib import import_module
+
+import typer
+from opensb.cli.common import Adapter, KeyFile, Mac, Target, console, target
+
+# Each device is its own distribution, so a group appears only when its package is
+# installed: `pip install opensb[keypad,lockpro]`.
+DEVICE_GROUPS = {
+    "keypad": "opensb.cli.keypad",
+    "lockpro": "opensb.cli.lockpro",
+}
+
+app = typer.Typer(help=__doc__, no_args_is_help=True, add_completion=False, rich_markup_mode="rich")
+
+installed = []
+for group, module in DEVICE_GROUPS.items():
+    try:
+        app.add_typer(import_module(module).app, name=group)
+    except ImportError:
+        continue
+    installed.append(group)
+
+
+@app.callback()
+def main_options(
+    context: typer.Context,
+    key_file: KeyFile = None,
+    mac: Mac = None,
+    adapter: Adapter = None,
+) -> None:
+    context.obj = Target(key_file=key_file, mac=mac, adapter=adapter)
+
+
+@app.command("key")
+def key_show(context: typer.Context) -> None:
+    """Show which device the key points at, without revealing it."""
+    key = target(context).key()
+    console.print(f"{key.mac}  key_id {key.key_id:#04x}  key {len(key.key)} bytes")
+
+
+@app.command("devices")
+def devices() -> None:
+    """List the device packages this install can talk to."""
+    for group in DEVICE_GROUPS:
+        console.print(f"{group}\t{'installed' if group in installed else '-'}")
+    if not installed:
+        # markup off: rich would read the extras list as a style tag and eat it.
+        console.print(
+            "\nNo device package installed. Add one:  pip install 'opensb[keypad,lockpro]'",
+            markup=False,
+        )
+
+
+def main() -> None:
+    app()