entr-ble-cli 1.0.0__py3-none-any.whl

entr_ble_cli/__init__.py

@@ -0,0 +1,7 @@
+def main() -> None:
+    from .cli import main as cli_main
+
+    cli_main()
+
+
+__all__ = ["main"]

entr_ble_cli/cli.py

@@ -0,0 +1,132 @@
+import argparse
+import asyncio
+import logging
+
+from bleak.exc import (
+    BleakBluetoothNotAvailableError,
+    BleakBluetoothNotAvailableReason,
+    BleakDeviceNotFoundError,
+    BleakError,
+)
+
+from entr_ble import EntrLockError, EntrProtocolError
+
+from .commands import (
+    access,
+    config,
+    discovery,
+    maintenance,
+    settings,
+    setup,
+    status,
+    users,
+)
+from .commands.common import handle
+from .shared import CommandError
+
+
+class HelpFormatter(argparse.RawDescriptionHelpFormatter):
+    def __init__(self, prog, groups):
+        super().__init__(prog, max_help_position=32)
+        self.groups = groups
+
+    def _format_action(self, action):
+        if not isinstance(action, argparse._SubParsersAction):
+            return super()._format_action(action)
+        commands = {command.dest: command for command in action._get_subactions()}
+        parts = []
+        for title, names in self.groups:
+            parts.append(f"{' ' * self._current_indent}{title}:\n")
+            self._indent()
+            for name in names:
+                parts.append(super()._format_action(commands[name]))
+            self._dedent()
+            parts.append("\n")
+        return "".join(parts)
+
+
+def main() -> None:
+    groups = []
+    parser = argparse.ArgumentParser(
+        prog="entr-ble-cli",
+        description="Set up and control an ENTR Bluetooth lock.",
+        usage="%(prog)s [options] COMMAND ...",
+        formatter_class=lambda prog: HelpFormatter(prog, groups),
+        epilog=(
+            "Getting started:\n"
+            "  1. Find your lock: entr-ble-cli scan\n"
+            "  2. Set up access with set-owner (new lock), enroll (replace the owner),\n"
+            "     or activate (use a key supplied by the owner).\n"
+            "  3. Read its status: entr-ble-cli status ADDRESS\n\n"
+            "Replace ADDRESS with the Bluetooth address printed by scan.\n"
+            "For a command's arguments and options, run:\n"
+            "  entr-ble-cli COMMAND --help\n\n"
+            "Example: entr-ble-cli unlock AA:BB:CC:DD:EE:FF"
+        ),
+    )
+    parser.add_argument(
+        "-q", "--quiet", action="store_true", help="hide progress messages"
+    )
+    sub = parser.add_subparsers(dest="command", title="commands", metavar="COMMAND")
+    for title, modules in (
+        ("Discovery and setup", (discovery, setup)),
+        ("Lock control", (access,)),
+        ("Status and information", (status,)),
+        ("Users and keys", (users,)),
+        ("Settings", (settings,)),
+        ("Maintenance and logs", (maintenance,)),
+        ("Home Assistant", (config,)),
+    ):
+        existing = set(sub.choices)
+        for module in modules:
+            module.register(sub)
+        groups.append((title, [name for name in sub.choices if name not in existing]))
+    for command in sub.choices.values():
+        command.add_argument(
+            "-q",
+            "--quiet",
+            action="store_true",
+            default=argparse.SUPPRESS,
+            help="hide progress messages",
+        )
+    args = parser.parse_args()
+    if args.command is None:
+        parser.print_help()
+        return
+    logger = logging.getLogger("entr_ble_cli")
+    logger.handlers = [logging.StreamHandler()]
+    logger.setLevel(logging.WARNING if args.quiet else logging.INFO)
+    logger.propagate = False
+    try:
+        if args.command == "export-homeassistant":
+            config.run(args)
+        else:
+            asyncio.run(handle(args))
+    except (CommandError, EntrProtocolError, BleakError, OSError, ValueError) as exc:
+        parser.exit(1, f"Error: {error_message(exc)}\n")
+    except KeyboardInterrupt, EOFError:
+        parser.exit(130, "Aborted.\n")
+
+
+def error_message(exc):
+    if isinstance(exc, BleakBluetoothNotAvailableError):
+        if exc.reason == BleakBluetoothNotAvailableReason.POWERED_OFF:
+            return "Bluetooth is turned off. Turn it on and try again."
+        if exc.reason.name.startswith("DENIED_"):
+            return "Bluetooth access was denied. Allow this application to use Bluetooth and try again."
+        return "Bluetooth is unavailable. Check that a Bluetooth adapter is connected and enabled."
+    if isinstance(exc, BleakDeviceNotFoundError):
+        return "The lock could not be found. Move closer and run 'entr-ble-cli scan' to check its address."
+    if isinstance(exc, TimeoutError):
+        return "Bluetooth communication timed out. Move closer to the lock and check that Bluetooth is enabled."
+    if isinstance(exc, BleakError):
+        return "Bluetooth communication failed. Check that Bluetooth is enabled and the lock is nearby, then try again."
+    if isinstance(exc, EntrLockError):
+        return "The lock refused the command. Check your password, key permissions, and whether your lock supports this command."
+    if isinstance(exc, EntrProtocolError):
+        return "The lock sent an unexpected response. Check the connection and whether your lock supports this command."
+    if isinstance(exc, OSError):
+        if exc.filename:
+            return f"Could not access {exc.filename}: {exc.strerror or 'check the file and its permissions'}."
+        return "Could not communicate over Bluetooth. Check your adapter and Bluetooth service, then try again."
+    return str(exc)

entr_ble_cli/commands/access.py

@@ -0,0 +1,16 @@
+def register(sub):
+    p = sub.add_parser("unlock", help="unlock the door")
+    p.add_argument("address")
+    p.set_defaults(run=run)
+
+    p = sub.add_parser("lock", help="lock the door")
+    p.add_argument("address")
+    p.set_defaults(run=run)
+
+
+async def run(client, creds, args) -> list[str]:
+    app_id = bytes.fromhex(creds.app_id)
+    await getattr(client, args.command)(
+        bytes.fromhex(creds.user_id), app_id, bytes.fromhex(creds.ble_ekey)
+    )
+    return [f"{args.command} sent"]

entr_ble_cli/commands/common.py

@@ -0,0 +1,78 @@
+import argparse
+import getpass
+import logging
+import warnings
+
+from bleak.exc import BleakError
+
+from entr_ble.client import EntrLockClient
+
+from ..shared import CommandError
+from ..store import get as get_credentials
+from .discovery import scan
+
+logger = logging.getLogger(__name__)
+
+
+async def handle(args: argparse.Namespace) -> None:
+    if args.command == "scan":
+        logger.info("Looking for nearby locks...")
+        lines = await scan(args.timeout, args.all)
+    else:
+        if args.command == "factory-reset" and not args.yes:
+            answer = input(
+                f"wipe all users and settings on {args.address}? type 'yes' to confirm: "
+            )
+            if answer.strip().lower() != "yes":
+                raise CommandError("aborted")
+        credentials = get_credentials(args.address)
+        if credentials is None and not getattr(args, "setup", False):
+            raise CommandError(
+                f"No saved key for {args.address}. Run 'entr-ble-cli activate --help' to use an existing key, or 'entr-ble-cli enroll --help' to become the owner."
+            )
+        if hasattr(args, "admin_code"):
+            if args.admin_code is None:
+                args.admin_code = read_password(args.password_prompt, "-p / --password")
+            if not args.admin_code:
+                args.admin_code = getattr(args, "password_default", None)
+            if not args.admin_code:
+                raise CommandError("The admin password cannot be empty.")
+        if hasattr(args, "new_code"):
+            if args.new_code is None:
+                args.new_code = read_password("New admin password: ", "--new-password")
+            if not args.new_code:
+                raise CommandError("The new admin password cannot be empty.")
+        client = EntrLockClient(args.address)
+        try:
+            logger.info("Connecting to %s...", args.address)
+            await client.connect()
+            logger.info("Checking the lock...")
+            await client.fetch_comm_version()
+            if credentials is not None:
+                logger.info("Using your saved key...")
+                await client.kdf_resync(
+                    credentials.kdf_id,
+                    credentials.role,
+                    bytes.fromhex(credentials.aes_key),
+                )
+            logger.info("Sending the command...")
+            lines = await args.run(client, credentials, args)
+        finally:
+            logger.info("Closing the connection...")
+            try:
+                await client.disconnect()
+            except BleakError, OSError:
+                logger.warning("Could not close the Bluetooth connection cleanly.")
+    for line in lines:
+        print(line)
+
+
+def read_password(prompt, option):
+    try:
+        with warnings.catch_warnings():
+            warnings.simplefilter("error", getpass.GetPassWarning)
+            return getpass.getpass(prompt)
+    except getpass.GetPassWarning, EOFError:
+        raise CommandError(
+            f"Could not read a hidden password. Run in a terminal or supply it with {option}."
+        ) from None

entr_ble_cli/commands/config.py

@@ -0,0 +1,28 @@
+import json
+import logging
+from dataclasses import asdict
+
+from ..shared import CommandError
+from ..store import get as get_credentials
+
+logger = logging.getLogger(__name__)
+
+
+def register(sub):
+    p = sub.add_parser(
+        "export-homeassistant",
+        help="export saved credentials for Home Assistant",
+        description="Print the saved credentials as JSON without connecting to the lock. In the ENTR BLE integration setup, choose 'Import existing credentials', enter the same Bluetooth address, and paste this JSON into the credentials field.",
+        epilog="The output contains keys that grant access to the lock. Keep it private.",
+    )
+    p.add_argument("address", help="Bluetooth address of the lock with a saved key")
+
+
+def run(args):
+    logger.info("Reading the saved configuration...")
+    credentials = get_credentials(args.address)
+    if credentials is None:
+        raise CommandError(
+            f"No saved key for {args.address}. Set up access with set-owner, enroll, or activate before exporting."
+        )
+    print(json.dumps(asdict(credentials), indent=2))

entr_ble_cli/commands/discovery.py

@@ -0,0 +1,43 @@
+from bleak import BleakScanner
+
+from entr_ble import advertising
+
+
+def register(sub):
+    p = sub.add_parser("scan", help="find nearby ENTR locks")
+    p.add_argument("--all", action="store_true", help="also list non-ENTR BLE devices")
+    p.add_argument(
+        "--timeout",
+        type=float,
+        default=5.0,
+        help="scan duration in seconds (default: 5)",
+    )
+
+
+async def scan(timeout: float = 5.0, show_all: bool = False) -> list[str]:
+    found = await BleakScanner.discover(timeout=timeout, return_adv=True)
+    locks = []
+    others = []
+    for address, (device, adv) in found.items():
+        lock = advertising.parse_advertisement(address, adv)
+        if lock is None:
+            others.append((address, f"{address} {device.name or '?'}"))
+        else:
+            locks.append(
+                (
+                    lock.rssi,
+                    f"{address} ENTR name={lock.name} state={lock.state_name} rssi={lock.rssi}",
+                )
+            )
+    locks.sort(key=lambda item: -(item[0] if item[0] is not None else -1000))
+    others.sort()
+    lock_lines = [label for _, label in locks]
+    other_lines = [label for _, label in others]
+    lines = lock_lines or ["no ENTR lock found"]
+    if show_all:
+        lines.extend(other_lines)
+    elif other_lines:
+        lines.append(
+            f"({len(other_lines)} other BLE devices hidden, use --all to show them)"
+        )
+    return lines

entr_ble_cli/commands/maintenance.py

@@ -0,0 +1,112 @@
+from entr_ble import const
+
+from ..shared import CommandError, add_password_argument
+from ..store import remove as remove_credentials
+
+
+def register(sub):
+    p = sub.add_parser("calibrate", help="calibrate the lock")
+    p.add_argument("address")
+    add_password_argument(p)
+    p.add_argument(
+        "--door",
+        choices=["left", "right"],
+        default="left",
+        help="door opening direction (default: left)",
+    )
+    p.add_argument(
+        "--type",
+        choices=["normal", "lift"],
+        default="normal",
+        help="lock type (default: normal)",
+    )
+    p.set_defaults(run=run)
+
+    p = sub.add_parser("magnet-calibrate", help="calibrate the door magnet")
+    p.add_argument("address")
+    add_password_argument(p)
+    p.set_defaults(run=run)
+
+    p = sub.add_parser("set-time", help="set the lock clock")
+    p.add_argument("address")
+    p.set_defaults(run=run)
+
+    p = sub.add_parser("audit-trail", help="show the event log")
+    p.add_argument("address")
+    add_password_argument(
+        p, "Admin password (Enter for factory audit password Aa1111): "
+    )
+    p.set_defaults(password_default=const.DEFAULT_AUDIT_PASSWORD)
+    p.set_defaults(run=run)
+
+    p = sub.add_parser("get-errors", help="show the error log")
+    p.add_argument("address")
+    p.add_argument(
+        "--query",
+        default="00" * 8,
+        help="8-byte query in hexadecimal (default: zeros)",
+    )
+    p.add_argument(
+        "--raw", action="store_true", help="also print the undecoded response bytes"
+    )
+    p.set_defaults(run=run)
+
+    p = sub.add_parser("factory-reset", help="erase all users and settings")
+    p.add_argument("address")
+    add_password_argument(p)
+    p.add_argument("--yes", action="store_true", help="skip the confirmation prompt")
+    p.set_defaults(run=run)
+
+
+async def run(client, creds, args) -> list[str]:
+    app_id = bytes.fromhex(creds.app_id)
+    if args.command == "calibrate":
+        door = args.door
+        lock_type = args.type
+        await client.calibrate(
+            app_id,
+            args.admin_code,
+            {"left": 1, "right": 3}[door],
+            {"normal": 0, "lift": 2}[lock_type],
+        )
+        return [
+            f"calibration done (door {door}, lock type {lock_type})",
+            "now run magnet-calibrate with the door magnet in place",
+        ]
+    if args.command == "magnet-calibrate":
+        await client.magnet_calibrate(app_id, args.admin_code)
+        return ["magnet calibration done"]
+    if args.command == "factory-reset":
+        await client.factory_reset(app_id, args.admin_code)
+        remove_credentials(creds.address)
+        return ["factory reset done, local credentials removed"]
+    if args.command == "set-time":
+        await client.update_time(app_id)
+        return ["lock time set to current UTC time"]
+    if args.command == "audit-trail":
+        code = args.admin_code
+        status = await client.audit_trail_status(code, app_id)
+        records = await client.audit_trail_records(code, app_id)
+        return [f"records in log: {status['records_count']}"] + [
+            f"{r.get('date', '?')}  {r.get('event', '?'):<18}  {r.get('user', '?') or '-'}"
+            for r in records
+        ]
+    if args.command == "get-errors":
+        try:
+            query = bytes.fromhex(args.query)
+        except ValueError as exc:
+            raise CommandError("--query must be hex, e.g. 0000000000000000") from exc
+        result = await client.get_errors(query)
+        lines = []
+        if result["empty"]:
+            lines.append(f"no errors logged ({result['length']} bytes, all zero)")
+        if not result["empty"] or args.raw:
+            data = bytes.fromhex(result["data"])
+            lines.extend(
+                f"{offset:04x}  {data[offset : offset + 8].hex(' ')}"
+                for offset in range(0, len(data), 8)
+            )
+        if args.raw:
+            lines.append(f"raw: {result['raw']}")
+        return lines
+    raise ValueError(args.command)

entr_ble_cli/commands/settings.py

@@ -0,0 +1,103 @@
+from entr_ble.client import EntrLockClient, build_lock_name, settings_status_byte
+
+from ..shared import VOLUME_CHOICES, CommandError, add_password_argument, require_admin
+from ..store import LockCredentials
+from ..store import put as put_credentials
+
+
+def register(sub):
+    p = sub.add_parser("settings", help="change lock settings")
+    p.add_argument("address")
+    add_password_argument(p)
+    p.add_argument(
+        "--volume",
+        choices=VOLUME_CHOICES,
+        help="sound volume",
+    )
+    p.add_argument("--auto-lock", choices=["on", "off"])
+    p.add_argument(
+        "--name",
+        help="lock name, if not saved locally",
+    )
+    p.set_defaults(run=run)
+
+    p = sub.add_parser("change-admin-code", help="change the lock's admin password")
+    p.add_argument("address")
+    add_password_argument(p, "Current admin password: ")
+    p.add_argument(
+        "--new-password",
+        dest="new_code",
+        metavar="PASSWORD",
+        help="new admin password, 6 characters (asked securely if omitted)",
+    )
+    p.add_argument(
+        "--name",
+        help="lock name, if not saved locally",
+    )
+    p.set_defaults(run=run)
+
+
+async def run(client, creds, args) -> list[str]:
+    require_admin(creds)
+    if args.command == "change-admin-code":
+        await _send_device_config(
+            client, creds, args.admin_code, args.new_code, None, None, args.name
+        )
+        return ["admin code changed"]
+    auto_lock = {"on": True, "off": False}.get(args.auto_lock or "")
+    volume = VOLUME_CHOICES.get(args.volume or "")
+    await _send_device_config(
+        client,
+        creds,
+        args.admin_code,
+        args.admin_code,
+        auto_lock,
+        volume,
+        args.name,
+    )
+    changes = [
+        label
+        for flag, label in (
+            (auto_lock is not None, f"auto-lock {args.auto_lock}"),
+            (volume is not None, f"volume {args.volume}"),
+            (bool(args.name), f"lock name {args.name}"),
+        )
+        if flag
+    ]
+    return [
+        "settings updated"
+        + (f": {', '.join(changes)}" if changes else " (no change requested)")
+    ]
+
+
+async def _send_device_config(
+    client: EntrLockClient,
+    creds: LockCredentials,
+    prev_code: str,
+    new_code: str,
+    auto_lock: bool | None,
+    volume: int | None,
+    requested_name: str | None,
+) -> None:
+    config = await client.get_device_config()
+    niz_statuses = None
+    if "wall_reader_status" in config and "integration_unit_status" in config:
+        niz_statuses = bytes(
+            [config["wall_reader_status"], config["integration_unit_status"]]
+        )
+    name = requested_name or creds.lock_name
+    if not name:
+        raise CommandError(
+            "the lock name is unknown, pass --name once (it is stored afterwards)"
+        )
+    await client.set_device_config(
+        bytes.fromhex(creds.app_id),
+        prev_code,
+        new_code,
+        settings_status_byte(client.status_raw or 0, auto_lock, volume),
+        build_lock_name(name),
+        niz_statuses=niz_statuses,
+    )
+    if creds.lock_name != name:
+        creds.lock_name = name
+        put_credentials(creds)

entr_ble_cli/commands/setup.py

@@ -0,0 +1,110 @@
+import logging
+import os
+
+from entr_ble import const
+from entr_ble.client import EntrLockError, build_lock_name, user_id_bytes
+
+from ..shared import CommandError, add_password_argument
+from ..store import LockCredentials
+from ..store import put as put_credentials
+
+logger = logging.getLogger(__name__)
+
+
+def register(sub):
+    p = sub.add_parser("set-owner", help="set up a new lock")
+    p.add_argument("address")
+    add_password_argument(p, "New owner password: ")
+    p.add_argument(
+        "--name",
+        required=True,
+        help="lock name (up to 12 bytes)",
+    )
+    p.add_argument(
+        "--user",
+        default="owner",
+        help="owner name (default: owner)",
+    )
+    p.add_argument(
+        "--provider",
+        type=int,
+        default=4,
+        help="brand id: Mul-T-Lock 1, Yale 2, Nemef 3, Vachette 4, Tesa 5, ASSA 6 (default: 4)",
+    )
+    p.add_argument(
+        "--sync-time",
+        action="store_true",
+        help="also set the lock clock",
+    )
+    p.set_defaults(run=run, setup=True)
+
+    p = sub.add_parser(
+        "enroll",
+        help="recover owner access, replacing the current owner's key",
+    )
+    p.add_argument("address")
+    add_password_argument(p, "Owner password: ")
+    p.add_argument("--name", help="lock name, stored for later settings commands")
+    p.set_defaults(run=run, setup=True)
+
+    p = sub.add_parser("activate", help="redeem a supplied key")
+    p.add_argument("address")
+    p.add_argument("key_code", help="6-character key code")
+    p.set_defaults(run=run, setup=True)
+
+
+async def run(client, credentials, args) -> list[str]:
+    if credentials is not None:
+        raise CommandError("this lock already has local credentials")
+    app_id = os.urandom(16)
+    logger.info("Setting up access to the lock...")
+    await client.pair()
+    await client.handshake(app_id)
+    role = const.ROLE_OWNER
+    lock_name = getattr(args, "name", None)
+    if args.command == "set-owner":
+        user_id = user_id_bytes(args.user)
+        result = await client.set_owner(
+            args.admin_code,
+            app_id,
+            user_id,
+            build_lock_name(args.name),
+            args.provider,
+        )
+        prefix = f"owner claimed: kdf_id={result['kdf_id']}"
+    elif args.command == "enroll":
+        result = await client.recover_owner(args.admin_code, app_id)
+        user_id = result["user_id"]
+        prefix = f"recovered owner: user_id={user_id.hex()} kdf_id={result['kdf_id']}"
+    else:
+        result = await client.get_new_key(args.key_code, app_id)
+        user_id = result["user_id"]
+        role = result["role"]
+        prefix = f"key activated: user_id={user_id.hex()} role={const.ROLE_NAMES.get(role, role)} kdf_id={result['kdf_id']}"
+    if client.session is None:
+        raise CommandError("pairing did not create an encrypted session")
+    credentials = LockCredentials(
+        address=args.address,
+        app_id=app_id.hex(),
+        user_id=user_id.hex(),
+        ble_ekey=result["ble_ekey"].hex(),
+        kdf_id=result["kdf_id"],
+        aes_key=client.session.key.hex(),
+        comm_version=client.comm_version or "",
+        role=role,
+        lock_name=lock_name,
+    )
+    logger.info("Saving your key...")
+    put_credentials(credentials)
+    lines = [prefix, f"credentials saved for {args.address}"]
+    if args.command == "set-owner":
+        if args.sync_time:
+            try:
+                await client.update_time(app_id)
+                lines.append("lock time set")
+            except EntrLockError as exc:
+                lines.append(f"warning: could not set the lock clock ({exc})")
+        lines.append(
+            "if the lock is uncalibrated, run 'calibrate' then 'magnet-calibrate'"
+        )
+    return lines

entr_ble_cli/commands/status.py

@@ -0,0 +1,38 @@
+def register(sub):
+    p = sub.add_parser("status", help="show lock, door and battery status")
+    p.add_argument("address")
+    p.add_argument(
+        "--raw", action="store_true", help="also print the undecoded response bytes"
+    )
+    p.set_defaults(run=run)
+
+    p = sub.add_parser("info", help="show serial number and firmware")
+    p.add_argument("address")
+    p.add_argument(
+        "--raw", action="store_true", help="also print the undecoded response bytes"
+    )
+    p.set_defaults(run=run)
+
+    p = sub.add_parser(
+        "device-info", help="show model, device ID and firmware versions"
+    )
+    p.add_argument("address")
+    p.add_argument(
+        "--raw", action="store_true", help="also print the undecoded response bytes"
+    )
+    p.set_defaults(run=run)
+
+
+async def run(client, creds, args) -> list[str]:
+    method = {
+        "status": client.get_device_config,
+        "info": client.get_lock_sn,
+        "device-info": client.get_device_info,
+    }[args.command]
+    fields = await method()
+    lines = [
+        f"{key}: {value}" for key, value in fields.items() if key != "raw" or args.raw
+    ]
+    if args.command == "info":
+        lines.append(f"comm_version: {client.comm_version}")
+    return lines

entr_ble_cli/commands/users.py

@@ -0,0 +1,120 @@
+from entr_ble import const
+
+from ..shared import (
+    CONTROL_UNIT_PIN,
+    CONTROL_UNIT_ROLES,
+    ROLE_CHOICES,
+    CommandError,
+    add_password_argument,
+    generate_key_code,
+    require_admin,
+    user_role,
+)
+
+
+def register(sub):
+    p = sub.add_parser("list-users", help="list users")
+    p.add_argument("address")
+    add_password_argument(p)
+    p.set_defaults(run=run)
+
+    p = sub.add_parser(
+        "create-user", help="create a user and print its activation code"
+    )
+    p.add_argument("address")
+    add_password_argument(p)
+    p.add_argument("name", help="user name (up to 16 characters)")
+    p.add_argument(
+        "--role",
+        choices=ROLE_CHOICES,
+        default="user",
+        help="role for the new key",
+    )
+    p.add_argument(
+        "--expiration",
+        type=int,
+        default=3,
+        choices=const.EXPIRATION_HOURS,
+        help="hours the key code stays redeemable (default: 3)",
+    )
+    p.add_argument("--code", help="use this key code instead of generating one")
+    p.set_defaults(run=run)
+
+    p = sub.add_parser(
+        "set-admin-code",
+        help="set this admin key's password",
+        epilog="Choose six characters including a lowercase letter, an uppercase letter, and a digit from 1 to 9.",
+    )
+    p.add_argument("address")
+    add_password_argument(p, "New admin password: ")
+    p.set_defaults(run=run)
+
+    p = sub.add_parser("disable-user", help="suspend a user without revoking it")
+    p.add_argument("address")
+    add_password_argument(p)
+    p.add_argument("name")
+    p.set_defaults(run=run)
+
+    p = sub.add_parser("enable-user", help="re-enable a suspended user")
+    p.add_argument("address")
+    add_password_argument(p)
+    p.add_argument("name")
+    p.set_defaults(run=run)
+
+    p = sub.add_parser("delete-user", help="revoke a user permanently")
+    p.add_argument("address")
+    add_password_argument(p)
+    p.add_argument("name")
+    p.set_defaults(run=run)
+
+
+async def run(client, creds, args) -> list[str]:
+    app_id = bytes.fromhex(creds.app_id)
+    if args.command == "list-users":
+        users = await client.list_users(args.admin_code, app_id)
+        return [
+            f"{u['name']}  role={const.ROLE_NAMES.get(u['role'], u['role'])}  state={const.STATE_NAMES.get(u['state'], u['state'])}"
+            for u in users
+        ]
+    if args.command == "create-user":
+        role = ROLE_CHOICES[args.role]
+        if role in CONTROL_UNIT_ROLES:
+            key_code, expiration = CONTROL_UNIT_PIN, 0
+        else:
+            key_code = args.code or generate_key_code()
+            expiration = args.expiration
+        await client.create_user(
+            args.admin_code,
+            app_id,
+            args.name,
+            key_code,
+            role=role,
+            expiration_hours=expiration,
+        )
+        lines = [f"created {args.name} as {const.ROLE_NAMES[role]}"]
+        if role in CONTROL_UNIT_ROLES:
+            return lines + [
+                "pair the accessory now (radio pairing happens on the hardware side)"
+            ]
+        return lines + [
+            f"key code: {key_code}",
+            f"redeem it within {expiration}h with: entr-ble-cli activate {creds.address} {key_code}",
+        ]
+    if args.command == "set-admin-code":
+        if creds.role != const.ROLE_ADMIN:
+            raise CommandError("only an admin can set an admin code")
+        await client.set_admin_code(
+            bytes.fromhex(creds.user_id), app_id, args.admin_code
+        )
+        return [
+            "admin code set, it is now needed for list-users, create-user and delete-user"
+        ]
+    if args.command in {"delete-user", "disable-user", "enable-user"}:
+        require_admin(creds)
+        role = await user_role(client, args.admin_code, app_id, args.name)
+        await getattr(client, args.command.replace("-user", "_user"))(
+            args.admin_code, app_id, args.name, role
+        )
+        verb = args.command.split("-")[0]
+        return [f"{verb}d {args.name} ({const.ROLE_NAMES.get(role, role)})"]
+    raise ValueError(args.command)

entr_ble_cli/shared.py

@@ -0,0 +1,76 @@
+import secrets
+
+from entr_ble import const
+from entr_ble.client import EntrProtocolError
+
+from .store import LockCredentials
+
+ROLE_CHOICES = {
+    "user": const.ROLE_USER,
+    "admin": const.ROLE_ADMIN,
+    "remote-control": const.ROLE_REMOTE_CONTROL,
+    "wall-reader": const.ROLE_WALL_READER,
+    "integration-unit": const.ROLE_INTEGRATION_UNIT,
+}
+VOLUME_CHOICES = {
+    "high": const.VOLUME_HIGH,
+    "medium": const.VOLUME_MEDIUM,
+    "low": const.VOLUME_LOW,
+    "muted": const.VOLUME_MUTED,
+}
+CONTROL_UNIT_ROLES = (
+    const.ROLE_REMOTE_CONTROL,
+    const.ROLE_WALL_READER,
+    const.ROLE_INTEGRATION_UNIT,
+)
+CONTROL_UNIT_PIN = "p7G513"
+_KEY_CODE_UPPER = "ABCDEFGHJKLMNPQRSTUVWXYZ"
+_KEY_CODE_LOWER = "abcdefghijkmnopqrstuvwxyz"
+_KEY_CODE_DIGITS = "123456789"
+_KEY_CODE_ALPHABET = _KEY_CODE_UPPER + _KEY_CODE_LOWER + _KEY_CODE_DIGITS
+
+
+class CommandError(Exception):
+    pass
+
+
+def add_password_argument(parser, prompt="Admin password: "):
+    parser.add_argument(
+        "-p",
+        "--password",
+        dest="admin_code",
+        metavar="PASSWORD",
+        help=f"{prompt.removesuffix(': ')} (6 characters; asked securely if omitted)",
+    )
+    parser.set_defaults(password_prompt=prompt)
+
+
+def generate_key_code() -> str:
+    while True:
+        code = "".join(
+            secrets.choice(_KEY_CODE_ALPHABET) for _ in range(const.KEY_CODE_LENGTH)
+        )
+        if (
+            any(c in _KEY_CODE_UPPER for c in code)
+            and any(c in _KEY_CODE_LOWER for c in code)
+            and any(c in _KEY_CODE_DIGITS for c in code)
+        ):
+            return code
+
+
+def require_admin(creds: LockCredentials) -> None:
+    if creds.role not in (const.ROLE_ADMIN, const.ROLE_OWNER):
+        raise CommandError(
+            f"this needs an admin or owner key, this one is a {const.ROLE_NAMES.get(creds.role, creds.role)}"
+        )
+
+
+async def user_role(client, admin_code: str, app_id: bytes, name: str) -> int:
+    users = await client.list_users(admin_code, app_id)
+    for user in users:
+        if user["name"] == name:
+            return user["role"]
+    known = ", ".join(u["name"] for u in users) or "none"
+    raise EntrProtocolError(
+        f"no user named {name!r} on this lock (known users: {known})"
+    )

entr_ble_cli/store.py

@@ -0,0 +1,96 @@
+import json
+import os
+import tempfile
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+DEFAULT_STORE_PATH = Path(
+    os.environ.get(
+        "ENTR_BLE_STORE", Path.home() / ".config" / "entr-ble" / "credentials.json"
+    )
+)
+
+
+@dataclass
+class LockCredentials:
+    address: str
+    app_id: str  # hex
+    user_id: str  # hex
+    ble_ekey: str  # hex
+    kdf_id: int
+    aes_key: str  # hex
+    comm_version: str
+    role: int = 2  # const.ROLE_OWNER; the KDF handshake replays it every connection
+    lock_name: str | None = None  # needed again by OP_DEVICE_CONFIG frames
+
+
+def get(address: str, path: Path = DEFAULT_STORE_PATH) -> LockCredentials | None:
+    return _load(path).get(address.upper())
+
+
+def put(creds: LockCredentials, path: Path = DEFAULT_STORE_PATH) -> None:
+    store = _load(path)
+    store[creds.address.upper()] = creds
+    _save(store, path)
+
+
+def remove(address: str, path: Path = DEFAULT_STORE_PATH) -> None:
+    store = _load(path)
+    if store.pop(address.upper(), None) is not None:
+        _save(store, path)
+
+
+def _load(path: Path) -> dict[str, LockCredentials]:
+    if not path.exists():
+        return {}
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+        if not isinstance(data, dict):
+            raise TypeError("expected an object indexed by Bluetooth address")
+        return {
+            addr.upper(): _credentials(addr, fields) for addr, fields in data.items()
+        }
+    except (ValueError, TypeError) as exc:
+        raise ValueError(f"Invalid credentials file: {path}") from exc
+
+
+def _credentials(address, fields):
+    creds = LockCredentials(**fields)
+    if not isinstance(creds.address, str) or creds.address.upper() != address.upper():
+        raise ValueError("address does not match credential entry")
+    for name, size in (
+        ("app_id", 16),
+        ("user_id", 16),
+        ("ble_ekey", 32),
+        ("aes_key", 16),
+    ):
+        value = getattr(creds, name)
+        if not isinstance(value, str) or len(bytes.fromhex(value)) != size:
+            raise ValueError(f"invalid {name}")
+    for value in (creds.kdf_id, creds.role):
+        if type(value) is not int or not 0 <= value <= 255:
+            raise ValueError("invalid credential identifier")
+    if not isinstance(creds.comm_version, str) or (
+        creds.lock_name is not None and not isinstance(creds.lock_name, str)
+    ):
+        raise ValueError("invalid lock metadata")
+    return creds
+
+
+def _save(store: dict[str, LockCredentials], path: Path) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    data = {addr: asdict(creds) for addr, creds in store.items()}
+    temporary = None
+    try:
+        with tempfile.NamedTemporaryFile(
+            mode="w", encoding="utf-8", dir=path.parent, delete=False
+        ) as stream:
+            temporary = Path(stream.name)
+            json.dump(data, stream, indent=2)
+            stream.write("\n")
+            stream.flush()
+            os.fsync(stream.fileno())
+        temporary.replace(path)
+    finally:
+        if temporary is not None:
+            temporary.unlink(missing_ok=True)

entr_ble_cli-1.0.0.dist-info/METADATA

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: entr-ble-cli
+Version: 1.0.0
+Summary: Command-line interface for ENTR Bluetooth locks
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: entr-ble==1.0.0
+Requires-Python: >=3.14
+Project-URL: Repository, https://github.com/johannlejeune/entr-ble
+Project-URL: Issues, https://github.com/johannlejeune/entr-ble/issues
+Description-Content-Type: text/markdown
+
+# ENTR BLE · CLI
+
+**Set up and control your ENTR lock from the terminal.** Discover locks, manage user keys, change settings, and export credentials to Home Assistant.
+
+[Project overview](../../README.md) · [Python library](../../src/entr_ble/README.md) · [Home Assistant](../../custom_components/entr_ble/README.md) · [Feature coverage](../../docs/FEATURES.md)
+
+## Install
+
+Requires **Python 3.14+** and a working Bluetooth adapter. On Linux, Bluetooth access requires BlueZ and access to the system D-Bus.
+
+Run the CLI without a checkout:
+
+```sh
+uvx entr-ble-cli --help
+uvx entr-ble-cli scan
+```
+
+For a persistent command, use `uv tool install entr-ble-cli`, then run `entr-ble-cli` directly. With `uvx`, prefix the commands below with `uvx`.
+
+Alternatively, from a checkout, run:
+
+```sh
+uv sync --locked --package entr-ble-cli
+uv run --package entr-ble-cli entr-ble-cli --help
+```
+
+For the checkout workflow, prefix the commands below with `uv run --package entr-ble-cli`. The `entr-ble-cli` package supplies the `entr-ble-cli` command; installing the `entr-ble` library alone does not.
+
+## Quick start
+
+### 1. Find your lock
+
+```sh
+entr-ble-cli scan
+```
+
+The scan lists each lock's address, advertised name, initialization state, and signal strength. Replace `ADDRESS` in the examples below with the exact address shown by your scan.
+
+For a longer scan, or to include other BLE devices:
+
+```sh
+entr-ble-cli scan --timeout 10
+entr-ble-cli scan --all
+```
+
+### 2. Choose how to access the lock
+
+Run **one** of the following setup commands. Each saves the resulting credential locally for subsequent commands.
+
+| Your situation | Command | Effect |
+| --- | --- | --- |
+| New, uninitialized lock | `entr-ble-cli set-owner ADDRESS --name "Front door"` | Creates the first owner and asks for a new password |
+| Initialized lock; you want owner access | `entr-ble-cli enroll ADDRESS --name "Front door"` | Asks for the current owner password and replaces the owner credential |
+| You have an activation code from the owner | `entr-ble-cli activate ADDRESS KEY_CODE` | Redeems an additional key while preserving the owner |
+
+> [!WARNING]
+> `enroll` replaces the lock's single owner slot. The previous owner, including the mobile app if it holds that slot, loses access. Use `activate` to keep the existing owner.
+
+`KEY_CODE` is the six-character code supplied by the owner. A setup command refuses to overwrite credentials already saved for that address.
+
+For a new lock, `--name` accepts up to 12 bytes. `--user` sets the owner name, and `--provider` selects the brand id; see `entr-ble-cli set-owner --help`. After initial setup, an uncalibrated lock needs `calibrate` followed by `magnet-calibrate` with the door magnet in place.
+
+### 3. Read status and control the lock
+
+```sh
+entr-ble-cli status ADDRESS
+entr-ble-cli unlock ADDRESS
+entr-ble-cli lock ADDRESS
+```
+
+Commands restore your saved session and close the Bluetooth connection when finished. Unlock behavior follows the lock's auto-lock setting. Reported state can be stale after manual operation; see [protocol limitations](../../docs/PROTOCOL.md).
+
+## Everyday tasks
+
+### Share access
+
+With an owner or admin key, create a user:
+
+```sh
+entr-ble-cli create-user ADDRESS Guest
+```
+
+The command asks for the admin password and prints an activation code and the command to redeem it. Run that activation command on the recipient's machine with its own credential store.
+
+The code stays redeemable for **three hours by default**. `--expiration` changes that window; the activated key does not expire when the code's redemption window ends.
+
+```sh
+entr-ble-cli list-users ADDRESS
+entr-ble-cli disable-user ADDRESS Guest
+entr-ble-cli enable-user ADDRESS Guest
+entr-ble-cli delete-user ADDRESS Guest
+```
+
+Disable suspends a key; enable restores it; delete permanently revokes it. `create-user --role admin` creates an admin key. After activation, that admin uses `set-admin-code` to set its personal password. Accessory roles are also available; radio pairing happens on the hardware, as described in [feature coverage](../../docs/FEATURES.md#users-and-accessories).
+
+### Change settings
+
+```sh
+entr-ble-cli settings ADDRESS --volume medium --auto-lock on
+entr-ble-cli change-admin-code ADDRESS
+```
+
+Volume choices are `high`, `medium`, `low`, and `muted`. These commands require an owner or admin key. The CLI reads the current configuration before applying changes. If the lock name was not saved during enrollment, pass `--name "Front door"` once; the CLI saves it for later settings commands.
+
+### Bring an existing key into Home Assistant
+
+```sh
+entr-ble-cli export-homeassistant ADDRESS
+```
+
+In the [integration setup](../../custom_components/entr_ble/README.md#use-credentials-from-the-cli), choose **Import existing credentials**, enter the same address, and paste the output into **Credentials JSON**.
+
+Export reads the local store without connecting to the lock or changing credentials. Home Assistant stores its own copy. The JSON contains access keys: keep it private.
+
+## Command reference
+
+Run `entr-ble-cli` to see grouped help, or `entr-ble-cli COMMAND --help` for arguments and options. All lock commands below take `ADDRESS`; `scan` does not.
+
+| Group | Commands | Purpose |
+| --- | --- | --- |
+| Discovery and setup | `scan`, `set-owner`, `enroll`, `activate` | Find locks and save an access credential |
+| Lock control | `lock`, `unlock` | Operate the lock |
+| Status and information | `status`, `info`, `device-info` | Read status, serial number, model, and firmware |
+| Users and keys | `list-users`, `create-user`, `set-admin-code`, `disable-user`, `enable-user`, `delete-user` | Manage access |
+| Settings | `settings`, `change-admin-code` | Change volume, auto-lock, name, or admin password |
+| Maintenance | `calibrate`, `magnet-calibrate`, `factory-reset` | Calibrate hardware or restore factory settings |
+| Clock and logs | `set-time`, `audit-trail`, `get-errors` | Set UTC time and read diagnostics |
+| Home Assistant | `export-homeassistant` | Export one saved credential as JSON |
+
+`set-time` and `audit-trail` require NIZ firmware. `device-info` requires the FOTA GATT service and communication version 1.29r3+; `get-errors` requires the FOTA service. See [feature coverage](../../docs/FEATURES.md) for the full compatibility matrix.
+
+> [!WARNING]
+> `factory-reset` erases lock users and settings, then removes the local credential after success. It asks you to type `yes`; `--yes` skips that confirmation.
+
+## Passwords and scripting
+
+Commands needing a password ask for it **without echo**, before connecting. `set-owner` and `set-admin-code` ask for the password to set; `change-admin-code` asks for both current and new passwords. At the `audit-trail` prompt, press Enter to use the factory audit password.
+
+For scripts without a terminal, use `-p PASSWORD` or `--password PASSWORD`. For password changes, also supply `--new-password NEW`. Command-line passwords may appear in shell history and process arguments; prefer the hidden prompt when working interactively.
+
+Results go to **stdout**, progress to **stderr**. Add `-q` or `--quiet` before or after a command to suppress progress while keeping warnings and errors:
+
+```sh
+entr-ble-cli --quiet status ADDRESS > status.txt
+entr-ble-cli status ADDRESS --quiet
+```
+
+Expected Bluetooth and lock failures produce a short error and exit with code `1`; interrupted input exits with `130`. Unexpected internal errors retain their traceback. Ordinary command output is human-readable; `export-homeassistant` produces JSON.
+
+## Credential storage
+
+| Setting | Value |
+| --- | --- |
+| Default store | `~/.config/entr-ble/credentials.json` |
+| Override | `ENTR_BLE_STORE` environment variable |
+| Protection | Access restricted to the current user; unencrypted at rest |
+| Writes | Atomic file replacement; no coordination between concurrent writers |
+
+Keep the store private, backed up securely, and out of version control. Use one process at a time when modifying a shared store. An alternate store can keep credentials for a separate client:
+
+```sh
+export ENTR_BLE_STORE="$HOME/.config/entr-ble/guest.json"
+entr-ble-cli activate ADDRESS KEY_CODE
+```
+
+Subsequent commands in that shell use the alternate store.
+
+## Troubleshooting
+
+| Symptom | Next step |
+| --- | --- |
+| No lock found or communication times out | Move closer, check Bluetooth is enabled, and try `scan --timeout 10 --all` |
+| Bluetooth access denied | Check application Bluetooth permissions; on Linux, check BlueZ and system D-Bus access |
+| No saved key | Check the address and `ENTR_BLE_STORE`; choose the appropriate setup method above |
+| Lock refuses a command | Check the password, key permissions, and firmware support |
+| Settings command needs a name | Pass `--name` once to save the lock name locally |
+| Status disagrees with manual operation | Read the [firmware state limitations](../../docs/PROTOCOL.md); a reported value can be stale |
+
+For a bug report, include the command, error, software version, and lock model/firmware. Remove passwords and credential material before sharing output.
+
+## Development
+
+From the repository root, after the checkout installation above:
+
+```sh
+uv run --package entr-ble-cli python -m unittest discover -s packages/entr-ble-cli/tests -v
+```
+
+Tests use simulated BLE responses and do not operate a lock. See the [workspace development guide](../../README.md#development) for all checks.
+
+Licensed under the [MIT License](LICENSE).

entr_ble_cli-1.0.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+entr_ble_cli/__init__.py,sha256=iyDYjHaLo7laVwWM-l3lE_9MF0EyefXhqiHNV2hnZTo,95
+entr_ble_cli/cli.py,sha256=I8-f4W8Df2hWYGkb5lVi6tUGrDdDrlpPETd2oOfO9mI,5277
+entr_ble_cli/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+entr_ble_cli/commands/access.py,sha256=vG2NIEVziAITH_cnzqeXYOAVtJi4m16sbCI-gXkHC94,497
+entr_ble_cli/commands/common.py,sha256=v-mCNGonKRPHS0QQcL-e2C9ZmzMoaySdtdFH-kc8omU,3094
+entr_ble_cli/commands/config.py,sha256=8tzP17d-9TNuWIsz9pbkoyTvx-9Y8scsBEFyG8TJ9BM,1093
+entr_ble_cli/commands/discovery.py,sha256=GYXg8q2yIBq41dsX9gFDxKMGCFMHfWPaZRJZStm2BX8,1433
+entr_ble_cli/commands/maintenance.py,sha256=ljkZAYYCACLtiKoJm4FjgkyTeEBZAasS-7nlVP7J8II,4000
+entr_ble_cli/commands/settings.py,sha256=pqNz7Y7-3GkWBgxE0vUyRWUEEAnDAZcFBQS0bYs3Lvo,3151
+entr_ble_cli/commands/setup.py,sha256=2kO10mHLL8ojVYfwZ4lbPGllPn4eCqZZsiYsxPehQfU,3751
+entr_ble_cli/commands/status.py,sha256=UBQp4auCpuE7MYq32a2K_Hwt9u2d4epo1NBqeonLRAg,1236
+entr_ble_cli/commands/users.py,sha256=-NJvuBbUVlyiqLQPFbZ40FbzdMnVpbkT1ZfEenX93o8,4076
+entr_ble_cli/shared.py,sha256=OTAeU1P_8-BYDlQSwaoOj2qYF1kH3aEhBTcifffvr48,2237
+entr_ble_cli/store.py,sha256=b0F8OajUWFvuFGcgAVZEfUOeCMXaZ0ojeGw8KW-Y2gs,3120
+entr_ble_cli-1.0.0.dist-info/licenses/LICENSE,sha256=kW6bEOhiZYBVbMnSrzF4DA5wCF32ZcngmKzrNawq6Oc,1071
+entr_ble_cli-1.0.0.dist-info/WHEEL,sha256=VOHKyukui3UMeyUkkBf5F7N5xN_6X6W7zHVvalNVVvI,81
+entr_ble_cli-1.0.0.dist-info/entry_points.txt,sha256=dWjKA9Vj259tSo7h5F159GDGJKK5x89YNVviFhu-YCo,52
+entr_ble_cli-1.0.0.dist-info/METADATA,sha256=tlHop8BbP9TRlmTNaQ1946RAkCw2j530yHH-YmX9Kqs,9878
+entr_ble_cli-1.0.0.dist-info/RECORD,,

entr_ble_cli-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.12.21
+Root-Is-Purelib: true
+Tag: py3-none-any

entr_ble_cli-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+entr-ble-cli = entr_ble_cli:main
+

entr_ble_cli-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Johann Lejeune
+
+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.