opensb-lockpro 0.0.1__tar.gz

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

@@ -0,0 +1,23 @@
+Metadata-Version: 2.5
+Name: opensb-lockpro
+Version: 0.0.1
+Summary: Local BLE control of the SwitchBot Lock Pro: lock, unlock, status and the event log
+Author-email: Yorsh Siarhei <yorsh.srg@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ble,bluetooth,home-assistant,lock,switchbot
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Home Automation
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Requires-Dist: opensb-core
+Description-Content-Type: text/markdown
+
+# opensb-lockpro
+
+Local BLE control of the SwitchBot Lock Pro: lock, unlock, status, settings, emergency
+unlock, calibration and the event log.
+
+    python3 -m pip install 'opensb[lockpro]'

opensb_lockpro-0.0.1/README.md

@@ -0,0 +1,6 @@
+# opensb-lockpro
+
+Local BLE control of the SwitchBot Lock Pro: lock, unlock, status, settings, emergency
+unlock, calibration and the event log.
+
+    python3 -m pip install 'opensb[lockpro]'

opensb_lockpro-0.0.1/pyproject.toml

@@ -0,0 +1,29 @@
+[project]
+name = "opensb-lockpro"
+dynamic = ["version"]
+description = "Local BLE control of the SwitchBot Lock Pro: lock, unlock, status and the event log"
+readme = "README.md"
+requires-python = ">=3.14"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Yorsh Siarhei", email = "yorsh.srg@gmail.com" }]
+keywords = ["switchbot", "lock", "ble", "bluetooth", "home-assistant"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Home Automation",
+    "Typing :: Typed",
+]
+dependencies = ["opensb-core"]
+
+[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_lockpro-0.0.1/src/opensb/lockpro/__init__.py

@@ -0,0 +1,54 @@
+"""The SwitchBot Lock Pro: lock, unlock, settings, calibration and its event log."""
+
+from opensb.lockpro.advertisement import (
+    is_lock,
+    parse_advertisement,
+    parse_bleak_advertisement,
+    status_from_byte,
+)
+from opensb.lockpro.device import Lock
+from opensb.lockpro.discovery import DiscoveredLock, discover
+from opensb.lockpro.enums import (
+    KeyAction,
+    KeyTrigger,
+    LatchType,
+    LockAlert,
+    LockStatus,
+    LogSource,
+)
+from opensb.lockpro.models import (
+    Advertisement,
+    Battery,
+    BatteryBay,
+    BatteryBays,
+    LockFlags,
+    LockInfo,
+    LogEntry,
+    Settings,
+    TimedSetting,
+)
+
+__all__ = [
+    "Advertisement",
+    "Battery",
+    "BatteryBay",
+    "BatteryBays",
+    "DiscoveredLock",
+    "KeyAction",
+    "KeyTrigger",
+    "LatchType",
+    "Lock",
+    "LockAlert",
+    "LockFlags",
+    "LockInfo",
+    "LockStatus",
+    "LogEntry",
+    "LogSource",
+    "Settings",
+    "TimedSetting",
+    "discover",
+    "is_lock",
+    "parse_advertisement",
+    "parse_bleak_advertisement",
+    "status_from_byte",
+]

opensb_lockpro-0.0.1/src/opensb/lockpro/advertisement.py

@@ -0,0 +1,64 @@
+"""Decode what the lock broadcasts. No key needed, no connection made."""
+
+from opensb.ble.const import COMPANY_ID, SERVICE_UUID
+from opensb.ble.errors import ProtocolError
+from opensb.lockpro.const import DEVICE_TYPE, DEVICE_TYPE_PAIRING
+from opensb.lockpro.enums import LockStatus
+from opensb.lockpro.models import Advertisement
+
+LOCK_DEVICE_TYPES = frozenset({DEVICE_TYPE, DEVICE_TYPE_PAIRING})
+
+
+def is_lock(service_data: bytes) -> bool:
+    """Whether this 0xFD3D service data came from a Lock Pro."""
+    return len(service_data) >= 3 and (service_data[0] & 0x7F) in LOCK_DEVICE_TYPES
+
+
+def status_from_byte(value: int) -> LockStatus:
+    """Decode the status byte the advertisement and the info reply share."""
+    return LockStatus((value & 0x78) >> 3)
+
+
+def parse_advertisement(service_data: bytes, manufacturer_data: bytes) -> Advertisement:
+    """Decode a Lock Pro advertisement.
+
+    Only the primary cell's percentage is broadcast; the second is reported as a
+    low-battery flag and nothing more.
+    """
+    if not is_lock(service_data):
+        raise ProtocolError(f"not Lock Pro service data: {service_data.hex()}")
+    if len(manufacturer_data) < 12:
+        raise ProtocolError(f"lock manufacturer data too short: {manufacturer_data.hex()}")
+
+    state, autolock, charge, group, alerts = manufacturer_data[7:12]
+    return Advertisement(
+        status=status_from_byte(state),
+        calibrated=bool(state & 0x80),
+        action_source=state & 0x07,
+        battery=service_data[2] & 0x7F,
+        auto_lock_paused=bool(autolock & 0x08),
+        charging=bool(charge & 0x80),
+        grouped=bool(group & 0x80),
+        door_open_alert=bool(alerts & 0x80),
+        unlocked_alert=bool(alerts & 0x40),
+        low_temp_alert=bool(alerts & 0x20),
+        weak_drive_alert=bool(alerts & 0x10),
+        door_magnet_alert=bool(alerts & 0x08),
+        left_battery_low=bool(alerts & 0x04),
+        right_battery_low=bool(alerts & 0x02),
+        sequence=manufacturer_data[6] & 0x3F,
+    )
+
+
+def parse_bleak_advertisement(advertisement_data: object) -> Advertisement:
+    """Decode straight from a bleak AdvertisementData.
+
+    Duck-typed, so importing this module never pulls bleak in.
+    """
+    service_data = getattr(advertisement_data, "service_data", {}) or {}
+    manufacturer_data = getattr(advertisement_data, "manufacturer_data", {}) or {}
+    payload = service_data.get(SERVICE_UUID)
+    mfr = manufacturer_data.get(COMPANY_ID)
+    if payload is None or mfr is None:
+        raise ProtocolError("advertisement carries no SwitchBot service or manufacturer data")
+    return parse_advertisement(bytes(payload), bytes(mfr))

opensb_lockpro-0.0.1/src/opensb/lockpro/const.py

@@ -0,0 +1,9 @@
+"""Wire constants specific to the Lock Pro."""
+
+# service_data[0] & 0x7f. 0x04 is the pair-mode marker.
+DEVICE_TYPE = 0x24
+DEVICE_TYPE_PAIRING = 0x04
+
+# Control and info groups, the Lock Pro's analogue of the keypad's 0x52 / 0x53.
+GROUP_CONTROL = 0x4E
+GROUP_INFO = 0x4F

opensb_lockpro-0.0.1/src/opensb/lockpro/device.py

@@ -0,0 +1,230 @@
+"""The lock as an object: connect, then ask it things."""
+
+import time
+from collections.abc import AsyncIterator
+
+from opensb.ble.models import CommunicationKey
+from opensb.ble.session import Session
+from opensb.ble.transport import BleakTransport, Transport
+from opensb.lockpro import frames, replies
+from opensb.lockpro.enums import KeyAction, KeyTrigger, LatchType, LockAlert
+from opensb.lockpro.models import (
+    Battery,
+    BatteryBays,
+    LockFlags,
+    LockInfo,
+    LogEntry,
+    Settings,
+    TimedSetting,
+)
+
+
+class Lock:
+    """A SwitchBot Lock Pro, over its encrypted local channel."""
+
+    def __init__(self, transport: Transport, key: CommunicationKey) -> None:
+        self.transport = transport
+        self.key = key
+        self.session = Session(transport, key)
+
+    @classmethod
+    def over_ble(
+        cls,
+        key: CommunicationKey,
+        *,
+        adapter: str | None = None,
+        scan_timeout: float | None = None,
+    ) -> Lock:
+        """A lock reached over BLE at the address its key names."""
+        kwargs = {"scan_timeout": scan_timeout} if scan_timeout is not None else {}
+        return cls(BleakTransport(key.mac, adapter=adapter, **kwargs), key)
+
+    async def __aenter__(self) -> Lock:
+        await self.connect()
+        return self
+
+    async def __aexit__(self, *_exc: object) -> None:
+        await self.disconnect()
+
+    async def connect(self) -> None:
+        await self.transport.connect()
+        self.session.invalidate()
+
+    async def disconnect(self) -> None:
+        self.session.invalidate()
+        await self.transport.disconnect()
+
+    async def info(self) -> LockInfo:
+        """Where the bolt is, and the battery."""
+        return replies.parse_info(await self.session.send(frames.info()))
+
+    async def battery(self) -> Battery:
+        """Battery percentage and firmware version."""
+        return replies.parse_battery(await self.session.send(frames.battery()))
+
+    async def lock(self) -> LockInfo:
+        """Throw the bolt."""
+        return replies.parse_info(await self.session.send(frames.lock()))
+
+    async def unlock(self, unlatch: bool = True) -> LockInfo:
+        """Withdraw the bolt. `unlatch` also pulls the latch, which opens the door."""
+        return replies.parse_info(await self.session.send(frames.unlock(unlatch)))
+
+    async def emergency_unlock(self, reverse: bool = False) -> None:
+        """Drive the motor until it stalls, ignoring the calibrated end positions.
+
+        The only control that still works on a jammed lock. It clears the
+        calibration, so `calibrate` has to follow, and until it does the status the
+        lock reports means nothing -- which is why the app asks whether the door
+        actually opened, and offers `reverse` when it did not.
+        """
+        await self.session.send(frames.emergency_unlock(reverse))
+
+    # --- calibration ---
+    # Every step has to run inside one `async with`: over separate connections each
+    # is still accepted while nothing is recorded, and the commit then leaves the
+    # lock uncalibrated.
+
+    async def enter_calibration(self) -> None:
+        """Release the motor so the knob turns by hand, and start recording."""
+        await self.session.send(frames.enter_calibration())
+
+    async def set_lock_position(self) -> None:
+        """Record where the knob is now as locked, and the door as closed."""
+        await self.session.send(frames.set_lock_position())
+
+    async def set_unlock_position(self) -> None:
+        """Record where the knob is now as unlocked."""
+        await self.session.send(frames.set_unlock_position())
+
+    async def set_door_open_position(self) -> None:
+        """Record the door as open, for the door sensor."""
+        await self.session.send(frames.set_door_open_position())
+
+    async def test_unlock(self) -> None:
+        """Drive to the recorded unlock position, still inside calibration."""
+        await self.session.send(frames.test_unlock())
+
+    async def test_lock(self) -> None:
+        """Drive to the recorded lock position, still inside calibration."""
+        await self.session.send(frames.test_lock())
+
+    async def set_latch_type(self, latch: LatchType) -> None:
+        """Tell the lock which latch it drives, inside a calibration run.
+
+        The lock detects this itself, so the app only ever confirms what the lock
+        already reported. On the Lock Pro the app never sends it at all.
+        """
+        await self.session.send(frames.set_latch_type(latch))
+
+    async def finish_calibration(self) -> None:
+        """Commit the recorded positions and leave calibration mode."""
+        await self.session.send(frames.finish_calibration())
+
+    async def recover_calibration(self) -> None:
+        """Abandon a calibration run in progress.
+
+        Not a way back to a calibration that is already lost: an uncalibrated lock
+        accepts this and nothing changes.
+        """
+        await self.session.send(frames.recover_calibration())
+
+    # --- settings ---
+
+    async def flags(self) -> LockFlags:
+        """Light, sound, linkage and the lock's own button, all in one byte."""
+        return replies.parse_flags(await self.session.send(frames.read_flags()))
+
+    async def auto_lock(self) -> TimedSetting:
+        """How long after unlocking the lock closes itself."""
+        return replies.parse_timed_setting(
+            await self.session.send(frames.read_auto_lock()), "auto lock"
+        )
+
+    async def force_lock(self) -> TimedSetting:
+        """Whether it locks even with the door reported open, and after how long."""
+        return replies.parse_timed_setting(
+            await self.session.send(frames.read_force_lock()), "force lock"
+        )
+
+    async def auto_lock_paused(self) -> bool:
+        """Whether auto-lock is suspended, with its delay remembered."""
+        return replies.parse_auto_lock_paused(
+            await self.session.send(frames.read_auto_lock_paused())
+        )
+
+    async def latch_keep_time(self) -> int:
+        """Seconds the latch stays retracted before springing back."""
+        return replies.parse_latch_keep_time(
+            await self.session.send(frames.read_latch_keep_time())
+        )
+
+    async def battery_bays(self) -> BatteryBays:
+        """Charge in each of the two bays, and whether a cell sits in them."""
+        return replies.parse_battery_bays(await self.session.send(frames.read_battery_bays()))
+
+    async def alert(self, kind: LockAlert) -> TimedSetting:
+        """One alert's flag and delay."""
+        return replies.parse_timed_setting(
+            await self.session.send(frames.read_alert(kind)), f"alert {kind.name}"
+        )
+
+    async def settings(self) -> Settings:
+        """Every configuration value, read one at a time over the open connection."""
+        return Settings(
+            flags=await self.flags(),
+            auto_lock=await self.auto_lock(),
+            force_lock=await self.force_lock(),
+            auto_lock_paused=await self.auto_lock_paused(),
+            latch_keep_time=await self.latch_keep_time(),
+            door_left_open_alert=await self.alert(LockAlert.DOOR_LEFT_OPEN),
+            not_locked_alert=await self.alert(LockAlert.NOT_LOCKED),
+            battery_bays=await self.battery_bays(),
+        )
+
+    async def set_light(self, enabled: bool) -> None:
+        await self.session.send(frames.set_light(enabled))
+
+    async def set_sound(self, enabled: bool) -> None:
+        await self.session.send(frames.set_sound(enabled))
+
+    async def set_manual_unlock_linkage(self, enabled: bool) -> None:
+        """Report a by-hand unlock to whatever is linked to the lock."""
+        await self.session.send(frames.set_manual_unlock_linkage(enabled))
+
+    async def set_key(
+        self,
+        enabled: bool,
+        action: KeyAction = KeyAction.TOGGLE,
+        trigger: KeyTrigger = KeyTrigger.SINGLE,
+    ) -> None:
+        """What the lock's own button does. Switching it off keeps the rest."""
+        await self.session.send(frames.set_key(enabled, action, trigger))
+
+    async def set_auto_lock(self, enabled: bool, seconds: int = 0) -> None:
+        await self.session.send(frames.set_auto_lock(enabled, seconds))
+
+    async def set_force_lock(self, enabled: bool, seconds: int = 0) -> None:
+        await self.session.send(frames.set_force_lock(enabled, seconds))
+
+    async def set_auto_lock_paused(self, paused: bool) -> None:
+        await self.session.send(frames.set_auto_lock_paused(paused))
+
+    async def set_alert(self, kind: LockAlert, enabled: bool, seconds: int = 0) -> None:
+        await self.session.send(frames.set_alert(kind, enabled, seconds))
+
+    async def set_latch_keep_time(self, seconds: int) -> None:
+        await self.session.send(frames.set_latch_keep_time(seconds))
+
+    async def set_notify(self, enabled: bool = True) -> None:
+        """Ask the lock to report state changes as they happen."""
+        await self.session.send(frames.set_notify(enabled))
+
+    async def read_log(self, since: int | None = None, limit: int = 50) -> AsyncIterator[LogEntry]:
+        """Walk the lock's event log, newest first, back from `since`."""
+        await self.session.send(frames.set_log_cursor(int(time.time()) if since is None else since))
+        for _ in range(limit):
+            entry = replies.parse_log_entry(await self.session.send(frames.read_log()))
+            if entry is None:
+                return
+            yield entry

opensb_lockpro-0.0.1/src/opensb/lockpro/discovery.py

@@ -0,0 +1,31 @@
+"""Finding Lock Pro devices among whatever is on the air."""
+
+from opensb.ble.discovery import DEFAULT_DISCOVERY_SECONDS, scan
+from opensb.ble.errors import ProtocolError
+from opensb.ble.models import Frozen
+from opensb.lockpro.advertisement import parse_bleak_advertisement
+from opensb.lockpro.models import Advertisement
+from pydantic import Field
+
+
+class DiscoveredLock(Frozen):
+    """A lock seen on the air."""
+
+    address: str = Field(description="BLE address to connect to")
+    name: str | None = Field(default=None, description="Advertised local name")
+    rssi: int = Field(description="Signal strength of the last advertisement seen")
+    state: Advertisement = Field(description="What that advertisement said")
+
+
+async def discover(seconds: float = DEFAULT_DISCOVERY_SECONDS) -> list[DiscoveredLock]:
+    """Scan for Lock Pro devices in range."""
+    locks = []
+    for seen in await scan(seconds):
+        try:
+            state = parse_bleak_advertisement(seen.advertisement)
+        except ProtocolError:
+            continue  # anything that is not a Lock Pro
+        locks.append(
+            DiscoveredLock(address=seen.address, name=seen.name, rssi=seen.rssi, state=state)
+        )
+    return locks

opensb_lockpro-0.0.1/src/opensb/lockpro/enums.py

@@ -0,0 +1,65 @@
+"""Enumerations specific to the Lock Pro."""
+
+from enum import IntEnum
+
+
+class LockStatus(IntEnum):
+    """Where the bolt is, from bits 3-6 of the status byte."""
+
+    LOCKED = 0
+    UNLOCKED = 1
+    LOCKING = 2
+    UNLOCKING = 3
+    LOCKING_BLOCKED = 4
+    UNLOCKING_BLOCKED = 5
+    LATCH_LOCKED = 6
+    PARTIALLY_LOCKED = 7
+
+
+class LogSource(IntEnum):
+    """What raised a lock-log entry.
+
+    A credential entry is the trigger -- a code entered on a paired keypad -- and the
+    actuation entries that follow it are the motor moving.
+    """
+
+    OTHER = -1
+    RESTART = 1
+    CREDENTIAL = 2
+    ACTUATION = 3
+    MANUAL = 6
+    SYSTEM = 14
+
+
+class LockAlert(IntEnum):
+    """The lock's two alerts. Each has its own enable flag and delay."""
+
+    DOOR_LEFT_OPEN = 1
+    NOT_LOCKED = 2
+
+
+class KeyAction(IntEnum):
+    """What a press of the lock's own button does."""
+
+    LOCK = 0
+    UNLOCK = 1
+    TOGGLE = 2
+
+
+class KeyTrigger(IntEnum):
+    """How many presses the button wants."""
+
+    SINGLE = 0
+    DOUBLE = 1
+
+
+class LatchType(IntEnum):
+    """What kind of latch the lock drives.
+
+    UNKNOWN is what the lock reports before it has decided; only the other two are
+    ever written.
+    """
+
+    UNKNOWN = 0
+    NORMAL = 1
+    NIGHT_LATCH = 2

opensb_lockpro-0.0.1/src/opensb/lockpro/frames.py

@@ -0,0 +1,249 @@
+"""Plaintext Lock Pro command frames, before the encryption envelope.
+
+The Lock Pro's bytes differ from the base Lock's for the same actions.
+"""
+
+from opensb.ble.const import FRAME_MAGIC
+from opensb.ble.errors import ProtocolError
+from opensb.lockpro.enums import KeyAction, KeyTrigger, LatchType, LockAlert
+
+# Byte 5 of a control or settings frame: one lock on its own, not half of a pair.
+SINGLE = 0x00
+
+
+def lock() -> bytes:
+    """Throw the bolt."""
+    return bytes.fromhex("570f4e0101000000")
+
+
+def unlock(unlatch: bool = True) -> bytes:
+    """Withdraw the bolt. `unlatch` also pulls the latch, which opens the door."""
+    return bytes.fromhex("570f4e0101000080" if unlatch else "570f4e01010000a0")
+
+
+def info() -> bytes:
+    """Read status and battery."""
+    return bytes.fromhex("570f4f8104")
+
+
+def battery() -> bytes:
+    """Read battery percentage and firmware version."""
+    return bytes([FRAME_MAGIC, 0x02])
+
+
+def set_notify(enabled: bool = True) -> bytes:
+    """Ask the lock to report state changes on the notify characteristic."""
+    return bytes.fromhex("570e01001e00008104" if enabled else "570e00")
+
+
+def set_log_cursor(unix_seconds: int) -> bytes:
+    """Point the log cursor: subsequent reads return entries older than this."""
+    return bytes([FRAME_MAGIC, 0x00, 0x14, 0x01]) + (unix_seconds & 0xFFFFFFFF).to_bytes(4, "big")
+
+
+def read_log() -> bytes:
+    """Read the next batch of entries older than the cursor."""
+    return bytes.fromhex("57001405")
+
+
+def emergency_unlock(reverse: bool = False) -> bytes:
+    """Drive the motor until it stalls, ignoring the calibrated end positions.
+
+    This is the only control that still works on a jammed lock, or on one whose
+    calibration is gone. The direction is a raw rotation rather than a target, so
+    the lock does not know which end it is heading for -- `reverse` turns it the
+    other way, which is what the app offers once the bolt has gone the wrong way.
+    It leaves the lock uncalibrated, so a calibration run has to follow.
+    """
+    return bytes([0x57, 0x0F, 0x4E, 0x01, 0x01, SINGLE, 0x01, 0xC0 if reverse else 0x40])
+
+
+# --- calibration ---
+# The recorded positions live in the connection. Sent one per connection every step
+# still answers "accepted" while nothing is kept, and the commit then leaves the lock
+# uncalibrated, so the whole run has to hold one link.
+
+
+def enter_calibration() -> bytes:
+    """Release the motor so the knob turns by hand, and start recording."""
+    return bytes.fromhex("570f4e030100c0")
+
+
+def set_lock_position() -> bytes:
+    """Record where the knob is now as locked, and the door as closed."""
+    return bytes.fromhex("570f4e030400c000")
+
+
+def set_unlock_position() -> bytes:
+    """Record where the knob is now as unlocked."""
+    return bytes.fromhex("570f4e0304008080")
+
+
+def set_door_open_position() -> bytes:
+    """Record the door as open, for the door sensor."""
+    return bytes.fromhex("570f4e0304004040")
+
+
+def test_unlock() -> bytes:
+    """Drive to the recorded unlock position, still inside calibration."""
+    return bytes.fromhex("570f4e03030080")
+
+
+def test_lock() -> bytes:
+    """Drive to the recorded lock position, still inside calibration."""
+    return bytes.fromhex("570f4e03030000")
+
+
+def set_latch_type(latch: LatchType) -> bytes:
+    """Tell the lock which latch it drives. A calibration step, not a setting.
+
+    The lock detects the type itself and reports it; the app only confirms what it
+    already said. Writing a type it has not reported is not something it corrects.
+    On the Lock Pro the app leaves this frame unsent -- its screens never reach the
+    call, though the firmware answers it -- so it is opt-in here.
+    """
+    if latch is LatchType.UNKNOWN:
+        raise ProtocolError("UNKNOWN is what the lock reports, not something to write")
+    return bytes([0x57, 0x0F, 0x4E, 0x04, 0x08, int(latch)])
+
+
+def finish_calibration() -> bytes:
+    """Commit the recorded positions and leave calibration mode."""
+    return bytes.fromhex("570f4e030200")
+
+
+def recover_calibration() -> bytes:
+    """Abandon a calibration run in progress.
+
+    Not a way back to a calibration that is already lost: an uncalibrated lock
+    accepts this and nothing changes.
+    """
+    return bytes.fromhex("570f4e030600")
+
+
+# --- settings ---
+# Sub-commands 0x03 and 0x04 mean the opposite on the base Lock, and there 0x09 is the
+# latch time rather than the battery bays. A base-Lock frame is not refused here, only
+# answered wrongly, and the shape of the reply is what gives it away.
+
+
+def read_flags() -> bytes:
+    """Read the settings byte: light, sound, linkage and the button."""
+    return bytes.fromhex("570f4f0401")
+
+
+def read_auto_lock() -> bytes:
+    """Read the auto-lock delay."""
+    return bytes.fromhex("570f4f0402")
+
+
+def read_force_lock() -> bytes:
+    """Read the force-lock delay."""
+    return bytes.fromhex("570f4f0403")
+
+
+def read_auto_lock_paused() -> bytes:
+    """Read whether auto-lock is suspended."""
+    return bytes.fromhex("570f4f0404")
+
+
+def read_latch_keep_time() -> bytes:
+    """Read how long the latch stays retracted."""
+    return bytes.fromhex("570f4f0407")
+
+
+def read_battery_bays() -> bytes:
+    """Read the charge in each battery bay."""
+    return bytes.fromhex("570f4f0409")
+
+
+def read_alert(alert: LockAlert) -> bytes:
+    """Read one alert's flag and delay."""
+    return bytes([0x57, 0x0F, 0x4F, 0x05, int(alert)])
+
+
+def _timed(enabled: bool, seconds: int) -> bytes:
+    """The (flag, delay) pair every timed setting uses.
+
+    The seconds go in split: whatever is under a minute rides in the low bits of the
+    flag byte, and whole minutes follow in the next one.
+    """
+    minutes, rest = divmod(max(seconds, 0), 60)
+    return bytes([(0x80 if enabled else 0) | rest, minutes & 0xFF])
+
+
+def set_flags(
+    light: bool,
+    sound: bool,
+    lock_go: bool = False,
+    linkage: bool = False,
+    device: int = SINGLE,
+) -> bytes:
+    """Write all four flags at once, with 0xF0 naming them in the mask byte.
+
+    The app's own builder never sets the lock-go bit, so 0x20 for it is read off the
+    bit order rather than off a call.
+    """
+    flags = (0x80 if light else 0) | (0x40 if sound else 0)
+    flags |= (0x20 if lock_go else 0) | (0x10 if linkage else 0)
+    return bytes([0x57, 0x0F, 0x4E, 0x04, 0x01, device & 0xFF, 0xF0, flags])
+
+
+def set_light(enabled: bool, device: int = SINGLE) -> bytes:
+    """The indicator light on the lock body."""
+    return bytes([0x57, 0x0F, 0x4E, 0x04, 0x01, device & 0xFF, 0x80, 0x80 if enabled else 0x00])
+
+
+def set_sound(enabled: bool, device: int = SINGLE) -> bytes:
+    """Beeps and voice prompts."""
+    return bytes([0x57, 0x0F, 0x4E, 0x04, 0x01, device & 0xFF, 0x40, 0x40 if enabled else 0x00])
+
+
+def set_manual_unlock_linkage(enabled: bool, device: int = SINGLE) -> bytes:
+    """Report a by-hand unlock to whatever is linked to the lock."""
+    return bytes([0x57, 0x0F, 0x4E, 0x04, 0x01, device & 0xFF, 0x10, 0x10 if enabled else 0x00])
+
+
+def set_key(
+    enabled: bool,
+    action: KeyAction = KeyAction.TOGGLE,
+    trigger: KeyTrigger = KeyTrigger.SINGLE,
+    device: int = SINGLE,
+) -> bytes:
+    """What the lock's own button does, and how many presses it wants.
+
+    Switching it off narrows the mask to the enable bit, so the action and trigger
+    the lock remembers survive. The 0x0E mask names the button field as a whole and
+    carries the action's low bit with it.
+    """
+    if not enabled:
+        return bytes([0x57, 0x0F, 0x4E, 0x04, 0x01, device & 0xFF, 0x08, 0x00])
+    value = 0x08 | (int(trigger) << 2) | int(action)
+    return bytes([0x57, 0x0F, 0x4E, 0x04, 0x01, device & 0xFF, 0x0E, value])
+
+
+def set_auto_lock(enabled: bool, seconds: int = 0, device: int = SINGLE) -> bytes:
+    """Lock again by itself, `seconds` after being unlocked."""
+    return bytes([0x57, 0x0F, 0x4E, 0x04, 0x02, device & 0xFF]) + _timed(enabled, seconds)
+
+
+def set_force_lock(enabled: bool, seconds: int = 0, device: int = SINGLE) -> bytes:
+    """Lock even when the door is reported open, after `seconds`."""
+    return bytes([0x57, 0x0F, 0x4E, 0x04, 0x03, device & 0xFF]) + _timed(enabled, seconds)
+
+
+def set_auto_lock_paused(paused: bool, device: int = SINGLE) -> bytes:
+    """Suspend auto-lock without making it forget its delay."""
+    return bytes([0x57, 0x0F, 0x4E, 0x04, 0x04, device & 0xFF, 0x80 if paused else 0x00])
+
+
+def set_alert(
+    alert: LockAlert, enabled: bool, seconds: int = 0, device: int = SINGLE
+) -> bytes:
+    """Arm one alert and give it its delay."""
+    return bytes([0x57, 0x0F, 0x4E, 0x05, int(alert), device & 0xFF]) + _timed(enabled, seconds)
+
+
+def set_latch_keep_time(seconds: int) -> bytes:
+    """How long the latch stays retracted before it springs back."""
+    return bytes([0x57, 0x0F, 0x4E, 0x04, 0x07, 0xFF, seconds & 0xFF])

opensb_lockpro-0.0.1/src/opensb/lockpro/models.py

@@ -0,0 +1,136 @@
+"""Structured results the Lock Pro parsers return."""
+
+from opensb.ble.models import Frozen
+from opensb.lockpro.enums import KeyAction, KeyTrigger, LockStatus, LogSource
+from pydantic import Field, field_validator
+
+
+class Advertisement(Frozen):
+    """What the lock broadcasts without any key."""
+
+    status: LockStatus = Field(description="Where the bolt is")
+    calibrated: bool = Field(description="Whether the lock knows its travel")
+    battery: int = Field(description="Primary cell percentage")
+    charging: bool = Field(description="Whether the lock is on charge")
+    grouped: bool = Field(description="Part of a dual-lock group")
+    auto_lock_paused: bool = Field(description="Auto-lock suspended")
+    door_open_alert: bool = Field(description="Door left open")
+    unlocked_alert: bool = Field(description="Left unlocked")
+    low_temp_alert: bool = Field(description="Battery too cold to work")
+    weak_drive_alert: bool = Field(description="Not enough power to move the bolt")
+    door_magnet_alert: bool = Field(description="Door-close sensor alarm")
+    left_battery_low: bool = Field(description="Left cell low; the Lock Pro has two")
+    right_battery_low: bool = Field(description="Right cell low")
+    sequence: int = Field(description="Broadcast counter")
+    action_source: int = Field(description="What caused the last movement")
+
+
+class LockInfo(Frozen):
+    """The lock's answer to a status read.
+
+    Five fields are decoded; the rest is handed back as `tail` rather than given
+    invented meanings. Battery has its own command; see `Lock.battery`.
+    """
+
+    status: LockStatus = Field(description="Where the bolt is")
+    calibrated: bool = Field(description="Whether the lock knows its travel")
+    door_open: bool = Field(description="Door reported open")
+    door_not_closed_alert: bool = Field(description="Door left open alarm")
+    not_locked_alert: bool = Field(description="Left unlocked alarm")
+    tail: bytes = Field(description="The undecoded remainder of the reply")
+
+
+class Battery(Frozen):
+    """Battery and firmware, from the short read."""
+
+    battery: int = Field(description="Percentage")
+    firmware: float = Field(description="Firmware version")
+
+
+class LogEntry(Frozen):
+    """One entry of the lock's event log.
+
+    `source` and `action` are raw. The direction of a credential event has not been
+    confirmed against a labelled action, so it is not derived here.
+    """
+
+    at: int = Field(description="Unix seconds")
+    index: int = Field(description="Entry index")
+    source: LogSource | int = Field(description="What raised the entry")
+    action: int = Field(description="Action byte")
+    value: int = Field(description="Direction and slot bits")
+    payload: bytes = Field(default=b"", description="Extra bytes, used by some sources")
+
+    @field_validator("source", mode="before")
+    @classmethod
+    def _name_the_source(cls, value: int) -> LogSource | int:
+        try:
+            return LogSource(value)
+        except ValueError:
+            return value
+
+    @property
+    def credential_ref(self) -> bytes | None:
+        """The key reference a credential event carries, which names the credential."""
+        if self.source is not LogSource.CREDENTIAL or len(self.payload) < 3:
+            return None
+        return self.payload[2:]
+
+
+class LockFlags(Frozen):
+    """The settings byte, which holds seven fields at once.
+
+    Every write names in byte 6 the field it touches, so `raw` is kept: it is the
+    only way to see bits nothing here decodes.
+    """
+
+    light: bool = Field(description="Indicator light on the lock body")
+    sound: bool = Field(description="Beeps and voice prompts")
+    lock_go: bool = Field(description="Lock-go; the app never sets this bit")
+    linkage: bool = Field(description="Report a by-hand unlock to linked devices")
+    key_enabled: bool = Field(description="Whether the lock's button responds")
+    key_trigger: KeyTrigger = Field(description="One press or two")
+    key_action: KeyAction | int = Field(description="What a press does")
+    raw: int = Field(description="The byte as it arrived")
+
+    @field_validator("key_action", mode="before")
+    @classmethod
+    def _name_the_action(cls, value: int) -> KeyAction | int:
+        try:
+            return KeyAction(value)
+        except ValueError:
+            return value
+
+
+class TimedSetting(Frozen):
+    """A setting that is on or off and acts after a delay."""
+
+    enabled: bool = Field(description="Whether it is armed")
+    seconds: int = Field(description="Delay before it acts")
+
+
+class BatteryBay(Frozen):
+    """One of the Lock Pro's two battery bays."""
+
+    inserted: bool = Field(description="Whether a cell sits in the bay")
+    battery: int = Field(description="Percentage")
+
+
+class BatteryBays(Frozen):
+    """Both bays. A grouped lock appends the slave's; only the master's are read."""
+
+    left: BatteryBay = Field(description="Left bay")
+    right: BatteryBay = Field(description="Right bay")
+
+
+class Settings(Frozen):
+    """Every configuration value the lock will report, read one at a time."""
+
+    flags: LockFlags = Field(description="Light, sound, linkage and the button")
+    auto_lock: TimedSetting = Field(description="Lock again by itself after a delay")
+    force_lock: TimedSetting = Field(description="Lock even with the door reported open")
+    auto_lock_paused: bool = Field(description="Auto-lock suspended, delay remembered")
+    latch_keep_time: int = Field(description="Seconds the latch is held back")
+    door_left_open_alert: TimedSetting = Field(description="Alarm for a door left open")
+    not_locked_alert: TimedSetting = Field(description="Alarm for a lock left open")
+    battery_bays: BatteryBays = Field(description="Charge in each bay")

opensb_lockpro-0.0.1/src/opensb/lockpro/replies.py

@@ -0,0 +1,91 @@
+"""Turn decrypted Lock Pro replies into models."""
+
+from opensb.ble.replies import check
+from opensb.lockpro.advertisement import status_from_byte
+from opensb.lockpro.enums import KeyTrigger
+from opensb.lockpro.models import (
+    Battery,
+    BatteryBay,
+    BatteryBays,
+    LockFlags,
+    LockInfo,
+    LogEntry,
+    TimedSetting,
+)
+
+
+def parse_info(reply: bytes) -> LockInfo:
+    """Decode an info() reply. Byte 1 carries the same status bits as the advertisement."""
+    check(reply, "lock info", minimum=7)
+    return LockInfo(
+        status=status_from_byte(reply[1]),
+        calibrated=bool(reply[1] & 0x80),
+        door_open=bool(reply[2] & 0x10),
+        door_not_closed_alert=bool(reply[6] & 0x80),
+        not_locked_alert=bool(reply[6] & 0x40),
+        tail=reply[3:],
+    )
+
+
+def parse_battery(reply: bytes) -> Battery:
+    """Decode a battery() reply. Byte 3 is unexplained on this firmware."""
+    check(reply, "battery", minimum=3)
+    return Battery(battery=reply[1], firmware=reply[2] / 10)
+
+
+def parse_log_entry(reply: bytes) -> LogEntry | None:
+    """Decode one log entry, or None once the log has run out."""
+    check(reply, "read log")
+    if len(reply) < 9 or not any(reply[1:]):
+        return None
+    return LogEntry(
+        at=int.from_bytes(reply[1:5], "big"),
+        index=reply[5],
+        source=reply[6],
+        action=reply[7],
+        value=reply[8],
+        payload=reply[9:],
+    )
+
+
+def parse_flags(reply: bytes) -> LockFlags:
+    """Decode a read_flags() reply. One byte carries all seven fields."""
+    check(reply, "lock flags", minimum=2)
+    flags = reply[1]
+    return LockFlags(
+        light=bool(flags & 0x80),
+        sound=bool(flags & 0x40),
+        lock_go=bool(flags & 0x20),
+        linkage=bool(flags & 0x10),
+        key_enabled=bool(flags & 0x08),
+        key_trigger=KeyTrigger(bool(flags & 0x04)),
+        key_action=flags & 0x03,
+        raw=flags,
+    )
+
+
+def parse_timed_setting(reply: bytes, context: str = "timed setting") -> TimedSetting:
+    """Decode the (flag, delay) pair auto-lock, force-lock and the alerts share."""
+    check(reply, context, minimum=3)
+    return TimedSetting(enabled=bool(reply[1] & 0x80), seconds=(reply[1] & 0x3F) + reply[2] * 60)
+
+
+def parse_auto_lock_paused(reply: bytes) -> bool:
+    """Decode a read_auto_lock_paused() reply, which is one flag byte."""
+    check(reply, "auto-lock paused", minimum=2)
+    return bool(reply[1] & 0x80)
+
+
+def parse_latch_keep_time(reply: bytes) -> int:
+    """Decode a read_latch_keep_time() reply. The seconds sit in byte 2."""
+    check(reply, "latch keep time", minimum=3)
+    return reply[2]
+
+
+def parse_battery_bays(reply: bytes) -> BatteryBays:
+    """Decode a read_battery_bays() reply: one byte per bay, seated flag in bit 7."""
+    check(reply, "battery bays", minimum=3)
+    return BatteryBays(
+        left=BatteryBay(inserted=bool(reply[1] & 0x80), battery=reply[1] & 0x7F),
+        right=BatteryBay(inserted=bool(reply[2] & 0x80), battery=reply[2] & 0x7F),
+    )