hoermoles-ble 0.2.0__tar.gz

hoermoles_ble-0.2.0/.gitignore

@@ -0,0 +1,13 @@
+# Reverse-engineering artifacts (decompiles, APKs, analysis notes) - not part of the product
+/reveng/
+
+# Python
+__pycache__/
+*.pyc
+.venv/
+*.egg-info/
+
+# Local configuration (incl. HOERMOLES_CONF_DIR for development)
+.env
+.env.*
+.hoermoles/

hoermoles_ble-0.2.0/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: hoermoles-ble
+Version: 0.2.0
+Summary: Portable protocol/crypto core + BLE client for the Hoermann BlueSecur 'Signed' channel (reverse-engineered)
+Requires-Python: >=3.10
+Requires-Dist: cryptography>=42
+Requires-Dist: python-dotenv>=1.0
+Provides-Extra: bleak
+Requires-Dist: bleak>=0.21; extra == 'bleak'
+Description-Content-Type: text/markdown
+
+# hoermoles-ble
+
+## Getting started: commissioning a drive
+
+Everyday use is via the `hoermoles-ble` CLI (published separately as package
+`hoermoles-ble-cli`, built on top of this library):
+
+1. Install the CLI as a standalone tool - this gives you the `hoermoles-ble`
+   command on your `$PATH`, no workspace checkout needed:
+
+   ```bash
+   uv tool install hoermoles-ble-cli
+   ```
+
+   (Contributing to/developing this repo instead? Use `cd python && uv sync`
+   and prefix every command below with `uv run` instead.)
+
+2. Get the QR code sticker's content onto disk - there's no camera-scanning
+   app yet, so either read it with a separate scanner app, or take a photo of
+   the sticker and decode it with a command-line QR decoder, e.g.
+   [`zbarimg`](https://github.com/mchehab/zbar) (`zbarimg --raw photo.jpg`).
+   Then save the decoded content once:
+
+   ```bash
+   hoermoles-ble save-qr "<QR code content>"
+   ```
+
+3. Scan for the drive over BLE - matches the saved QR code by serial number
+   and saves the drive's product type to the device registry (see below):
+
+   ```bash
+   hoermoles-ble scan
+   ```
+
+   Seeing only the short packet ("incompletely parsed", no `Admin taught:
+   ...` line) is normal and not a sign of anything - both our own drive
+   (already paired) and the official app's own code treat this as a plain
+   BLE scan-timing artifact, not something tied to admin/pairing status (the
+   decompiled app has explicit, unconditional logic to recover once the
+   longer packet eventually arrives - see the local reveng report). Just use
+   a longer `--timeout` or retry `scan`.
+
+4. Register (one-time pairing). Only works while the drive still accepts a
+   new admin (`AdminsCanBeTeached=True` in the scan output above) - reset via
+   the drive's menu 19/parameter 02 first if not (this invalidates the
+   existing pairing, e.g. with your phone):
+
+   ```bash
+   hoermoles-ble register --address <MAC>
+   ```
+
+   This derives and saves the root key under
+   `~/.hoermoles/credentials/<MAC>.json` - no QR code, app, or cloud needed
+   again afterwards.
+
+5. Trigger the gate:
+
+   ```bash
+   hoermoles-ble exec --address <MAC> impulse
+   ```
+
+From here on `--address` can usually be omitted (it defaults to the only/
+first saved credentials). See `packages/hoermoles-ble-cli/README.md` for the
+full command reference (`menu-get`/`menu-set` for operator settings,
+`view-log` for the audit log/diagnostics counters, `list-devices`, ...) and
+the workspace-level `python/README.md` for a longer walkthrough.
+
+## Library internals
+
+Protocol core (`protocol.py`, `crypto_rsa.py`) and BLE client (`client.py`,
+`transport.py`, `ble_transport.py`) for the Hoermann BlueSecur "Signed"
+channel.
+
+`protocol.py` deliberately has no third-party dependencies (stdlib only) and
+serves as a template for ports to other languages. `bleak` (for the real BLE
+transport) is an optional extra: `pip install hoermoles-ble[bleak]`.
+
+Reverse-engineered from the official Hoermann BlueSecur app; see the module
+docstrings in `protocol.py`, `client.py`, and `advertisement.py` for details
+on where each part of the protocol comes from.
+
+## Operator menu/parameter settings
+
+Besides the channel commands (open/close/light/...), the drive also exposes
+its classic numbered configuration menus (menu 20 "reversal limit", menu 25
+"operator light", menu 52 "speed door open", ...) over BLE - the same menus
+normally set via the hand-transmitter/display sequence, exposed by the
+official app as "operator settings". `HoermannClient.read_properties()` and
+`.write_properties()` (in `client.py`) read/write these; `menu_settings.py`
+provides the menu-number-to-wire-byte table and valid values per menu for
+every product the official app knows about (Supramatic Serie 4/E4, Rollmatic
+2, SilentDrive 2, Supramatic 4 H4, HET), sourced from the app's own embedded
+menu-concept resources, one `DriveMenuTable` per (product_class, product_id)
+in `DRIVE_MENU_TABLES`. See the module docstring for the exact
+firmware/software scope per product (menu_group wire bytes are NOT
+interchangeable across products or even across ProductIDs that share the
+same advertised name) and the CLI's `menu-get`/`menu-set` commands for a
+ready-to-use example.
+
+The read direction (`read_properties()`/GET_PROPERTIES/GET_SELECTED_PROPERTIES)
+is live-verified against a real Supramatic E4 - both a full, unfiltered read
+and filtered multi-menu reads returned plausible values. One live-confirmed
+protocol quirk: a GET_SELECTED_PROPERTIES request that mixes a menu group <
+100 with one >= 100 makes the drive drop the connection instead of
+answering - `read_properties()` avoids this via
+`protocol.batch_menu_groups_for_selected_properties()`. The write direction
+(`write_properties()`/SET_PROPERTIES) is only structurally derived from the
+decompiled app and NOT yet confirmed live for any product - read a value back
+before writing it, and double-check menu numbers/values against the printed
+operator manual.
+
+## Device registry (which product a paired drive is)
+
+`devices.py` keeps a separate `<config_dir>/devices.json` registry mapping
+each MAC address to its product_class/product_id/product_name (and serial
+number, if known) via `save_device_info()`/`get_device_info()`/
+`list_device_infos()` - deliberately not part of `credentials.py`/
+`Credentials`, since it's non-secret metadata and, unlike a per-device
+credentials file, one file can list every drive ever seen. `scan_devices()`
+itself is read-only (no root key needed, nothing persisted) - the CLI's
+`scan` command is what saves a `DeviceInfo` for each device it finds with a
+decodable product_class/product_id; `register` also saves one directly from
+the QR code prefix. `menu-get`/`menu-set` use the registry to pick the right
+`DriveMenuTable` automatically.
+
+## Audit log and diagnostics counters
+
+`HoermannClient.read_log()`/`.read_service_data()` (in `client.py`) read the
+same two things the app's "log"/diagnostics view shows: a security/access
+audit log (who registered, which channel got toggled, blocked login
+attempts, clock changes, ...) and service counters (operating hours, door
+cycles, maintenance counters, ...) - see `device_log.py` for the
+`LogTag`/`ServiceType` name tables and per-tag field decoding
+(`parse_log_fields()`). Both are live-verified against a real Supramatic E4 -
+that check is also what caught a transcription error in `SERVICE_TYPE_NAMES`
+(wire byte 17 is `ELEMENTS_COUNTER`, not `ENGINE_RUNTIME` - the
+wire-byte-to-meaning mapping in the decompiled app is an explicit switch
+statement, not the `ServiceType` enum's own declared integer values). A
+handful of `ServiceType` entries carry a proprietary Hoermann fixed-32-day-
+month timestamp encoding instead of a plain counter - NOT decoded here (see
+`SERVICE_TYPE_IS_TIMESTAMP`), only the plain-integer counters (including
+operating hours) are. See the CLI's `view-log` command for a ready-to-use
+example.

hoermoles_ble-0.2.0/README.md

@@ -0,0 +1,143 @@
+# hoermoles-ble
+
+## Getting started: commissioning a drive
+
+Everyday use is via the `hoermoles-ble` CLI (published separately as package
+`hoermoles-ble-cli`, built on top of this library):
+
+1. Install the CLI as a standalone tool - this gives you the `hoermoles-ble`
+   command on your `$PATH`, no workspace checkout needed:
+
+   ```bash
+   uv tool install hoermoles-ble-cli
+   ```
+
+   (Contributing to/developing this repo instead? Use `cd python && uv sync`
+   and prefix every command below with `uv run` instead.)
+
+2. Get the QR code sticker's content onto disk - there's no camera-scanning
+   app yet, so either read it with a separate scanner app, or take a photo of
+   the sticker and decode it with a command-line QR decoder, e.g.
+   [`zbarimg`](https://github.com/mchehab/zbar) (`zbarimg --raw photo.jpg`).
+   Then save the decoded content once:
+
+   ```bash
+   hoermoles-ble save-qr "<QR code content>"
+   ```
+
+3. Scan for the drive over BLE - matches the saved QR code by serial number
+   and saves the drive's product type to the device registry (see below):
+
+   ```bash
+   hoermoles-ble scan
+   ```
+
+   Seeing only the short packet ("incompletely parsed", no `Admin taught:
+   ...` line) is normal and not a sign of anything - both our own drive
+   (already paired) and the official app's own code treat this as a plain
+   BLE scan-timing artifact, not something tied to admin/pairing status (the
+   decompiled app has explicit, unconditional logic to recover once the
+   longer packet eventually arrives - see the local reveng report). Just use
+   a longer `--timeout` or retry `scan`.
+
+4. Register (one-time pairing). Only works while the drive still accepts a
+   new admin (`AdminsCanBeTeached=True` in the scan output above) - reset via
+   the drive's menu 19/parameter 02 first if not (this invalidates the
+   existing pairing, e.g. with your phone):
+
+   ```bash
+   hoermoles-ble register --address <MAC>
+   ```
+
+   This derives and saves the root key under
+   `~/.hoermoles/credentials/<MAC>.json` - no QR code, app, or cloud needed
+   again afterwards.
+
+5. Trigger the gate:
+
+   ```bash
+   hoermoles-ble exec --address <MAC> impulse
+   ```
+
+From here on `--address` can usually be omitted (it defaults to the only/
+first saved credentials). See `packages/hoermoles-ble-cli/README.md` for the
+full command reference (`menu-get`/`menu-set` for operator settings,
+`view-log` for the audit log/diagnostics counters, `list-devices`, ...) and
+the workspace-level `python/README.md` for a longer walkthrough.
+
+## Library internals
+
+Protocol core (`protocol.py`, `crypto_rsa.py`) and BLE client (`client.py`,
+`transport.py`, `ble_transport.py`) for the Hoermann BlueSecur "Signed"
+channel.
+
+`protocol.py` deliberately has no third-party dependencies (stdlib only) and
+serves as a template for ports to other languages. `bleak` (for the real BLE
+transport) is an optional extra: `pip install hoermoles-ble[bleak]`.
+
+Reverse-engineered from the official Hoermann BlueSecur app; see the module
+docstrings in `protocol.py`, `client.py`, and `advertisement.py` for details
+on where each part of the protocol comes from.
+
+## Operator menu/parameter settings
+
+Besides the channel commands (open/close/light/...), the drive also exposes
+its classic numbered configuration menus (menu 20 "reversal limit", menu 25
+"operator light", menu 52 "speed door open", ...) over BLE - the same menus
+normally set via the hand-transmitter/display sequence, exposed by the
+official app as "operator settings". `HoermannClient.read_properties()` and
+`.write_properties()` (in `client.py`) read/write these; `menu_settings.py`
+provides the menu-number-to-wire-byte table and valid values per menu for
+every product the official app knows about (Supramatic Serie 4/E4, Rollmatic
+2, SilentDrive 2, Supramatic 4 H4, HET), sourced from the app's own embedded
+menu-concept resources, one `DriveMenuTable` per (product_class, product_id)
+in `DRIVE_MENU_TABLES`. See the module docstring for the exact
+firmware/software scope per product (menu_group wire bytes are NOT
+interchangeable across products or even across ProductIDs that share the
+same advertised name) and the CLI's `menu-get`/`menu-set` commands for a
+ready-to-use example.
+
+The read direction (`read_properties()`/GET_PROPERTIES/GET_SELECTED_PROPERTIES)
+is live-verified against a real Supramatic E4 - both a full, unfiltered read
+and filtered multi-menu reads returned plausible values. One live-confirmed
+protocol quirk: a GET_SELECTED_PROPERTIES request that mixes a menu group <
+100 with one >= 100 makes the drive drop the connection instead of
+answering - `read_properties()` avoids this via
+`protocol.batch_menu_groups_for_selected_properties()`. The write direction
+(`write_properties()`/SET_PROPERTIES) is only structurally derived from the
+decompiled app and NOT yet confirmed live for any product - read a value back
+before writing it, and double-check menu numbers/values against the printed
+operator manual.
+
+## Device registry (which product a paired drive is)
+
+`devices.py` keeps a separate `<config_dir>/devices.json` registry mapping
+each MAC address to its product_class/product_id/product_name (and serial
+number, if known) via `save_device_info()`/`get_device_info()`/
+`list_device_infos()` - deliberately not part of `credentials.py`/
+`Credentials`, since it's non-secret metadata and, unlike a per-device
+credentials file, one file can list every drive ever seen. `scan_devices()`
+itself is read-only (no root key needed, nothing persisted) - the CLI's
+`scan` command is what saves a `DeviceInfo` for each device it finds with a
+decodable product_class/product_id; `register` also saves one directly from
+the QR code prefix. `menu-get`/`menu-set` use the registry to pick the right
+`DriveMenuTable` automatically.
+
+## Audit log and diagnostics counters
+
+`HoermannClient.read_log()`/`.read_service_data()` (in `client.py`) read the
+same two things the app's "log"/diagnostics view shows: a security/access
+audit log (who registered, which channel got toggled, blocked login
+attempts, clock changes, ...) and service counters (operating hours, door
+cycles, maintenance counters, ...) - see `device_log.py` for the
+`LogTag`/`ServiceType` name tables and per-tag field decoding
+(`parse_log_fields()`). Both are live-verified against a real Supramatic E4 -
+that check is also what caught a transcription error in `SERVICE_TYPE_NAMES`
+(wire byte 17 is `ELEMENTS_COUNTER`, not `ENGINE_RUNTIME` - the
+wire-byte-to-meaning mapping in the decompiled app is an explicit switch
+statement, not the `ServiceType` enum's own declared integer values). A
+handful of `ServiceType` entries carry a proprietary Hoermann fixed-32-day-
+month timestamp encoding instead of a plain counter - NOT decoded here (see
+`SERVICE_TYPE_IS_TIMESTAMP`), only the plain-integer counters (including
+operating hours) are. See the CLI's `view-log` command for a ready-to-use
+example.

hoermoles_ble-0.2.0/pyproject.toml

@@ -0,0 +1,20 @@
+[project]
+name = "hoermoles-ble"
+version = "0.2.0"
+description = "Portable protocol/crypto core + BLE client for the Hoermann BlueSecur 'Signed' channel (reverse-engineered)"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "cryptography>=42",
+    "python-dotenv>=1.0",
+]
+
+[project.optional-dependencies]
+bleak = ["bleak>=0.21"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hoermoles_ble"]

hoermoles_ble-0.2.0/src/hoermoles_ble/__init__.py

@@ -0,0 +1,91 @@
+from .advertisement import AdvertisementInfo
+from .client import HoermannClient, PropertiesRejected, RegistrationTimeout
+from .config import ENV_VAR_CONFIG_DIR, resolve_config_dir
+from .credentials import Credentials, default_credentials_path
+from .device_log import (
+    LOG_TAG_NAMES,
+    SERVICE_TYPE_IS_TIMESTAMP,
+    SERVICE_TYPE_NAMES,
+    log_timestamp_to_datetime,
+    parse_log_fields,
+)
+from .devices import (
+    DeviceInfo,
+    default_devices_registry_path,
+    get_device_info,
+    list_device_infos,
+    load_device_registry,
+    save_device_info,
+)
+from .discovery import find_qr_for_address, scan_devices
+from .menu_settings import (
+    DRIVE_MENU_TABLES,
+    SUPRAMATIC_E4_MENU_TABLE,
+    SUPRAMATIC_E4_PRODUCT_CLASS,
+    SUPRAMATIC_E4_PRODUCT_ID,
+    DriveMenuTable,
+    MenuParameter,
+    MenuSetting,
+    menu_setting_for_number,
+    menu_setting_for_wire_group,
+    menu_table_for_product,
+    menu_tables_for_product,
+    wire_group_for_menu_number,
+)
+from .protocol import (
+    BC_RX,
+    BC_SERVICE,
+    BC_TX,
+    CHANNEL_COMMAND_ID,
+    GATE_ACTIONS,
+    product_class_and_id_from_qr_prefix,
+    serial_no_from_qr_prefix,
+)
+from .qr_store import default_qr_store_path, known_qr_serial_map, load_known_qrs, save_qr
+
+__all__ = [
+    "HoermannClient",
+    "RegistrationTimeout",
+    "PropertiesRejected",
+    "Credentials",
+    "default_credentials_path",
+    "AdvertisementInfo",
+    "scan_devices",
+    "find_qr_for_address",
+    "resolve_config_dir",
+    "ENV_VAR_CONFIG_DIR",
+    "save_qr",
+    "load_known_qrs",
+    "default_qr_store_path",
+    "known_qr_serial_map",
+    "serial_no_from_qr_prefix",
+    "product_class_and_id_from_qr_prefix",
+    "BC_SERVICE",
+    "BC_TX",
+    "BC_RX",
+    "CHANNEL_COMMAND_ID",
+    "GATE_ACTIONS",
+    "MenuSetting",
+    "MenuParameter",
+    "DriveMenuTable",
+    "DRIVE_MENU_TABLES",
+    "SUPRAMATIC_E4_MENU_TABLE",
+    "SUPRAMATIC_E4_PRODUCT_CLASS",
+    "SUPRAMATIC_E4_PRODUCT_ID",
+    "menu_setting_for_number",
+    "menu_setting_for_wire_group",
+    "wire_group_for_menu_number",
+    "menu_tables_for_product",
+    "menu_table_for_product",
+    "DeviceInfo",
+    "default_devices_registry_path",
+    "load_device_registry",
+    "list_device_infos",
+    "get_device_info",
+    "save_device_info",
+    "LOG_TAG_NAMES",
+    "SERVICE_TYPE_NAMES",
+    "SERVICE_TYPE_IS_TIMESTAMP",
+    "parse_log_fields",
+    "log_timestamp_to_datetime",
+]

hoermoles_ble-0.2.0/src/hoermoles_ble/advertisement.py

@@ -0,0 +1,162 @@
+"""
+Passive parsing of the Hoermann BlueSecur BLE advertisement (Manufacturer Specific Data,
+Company ID 0x07B4 = 1972) - provides status info WITHOUT a connection and
+WITHOUT a root key.
+
+Reconstructed from SAL.BlueConnect.API.Devices.Info.DeviceData (BLEAdvertisementData.cs,
+BlueSecurAdvertisementService.cs, ServiceProduct.cs, product-specific *AdvertisementService.cs)
+and verified empirically against a real, freshly reset drive: after a reset via
+menu 19/parameter 02, `admins_can_be_teached` reliably flipped from False to
+True - confirming the bit position.
+
+Important quirk: the device sends the content for Company ID 1972 across two
+different, alternating manufacturer-data packets (6 and 17 bytes on our test
+device). Only the 2-byte company ID + both payloads concatenated (shortest
+first) yields the byte sequence expected by the original parser -
+`combine_manufacturer_payloads()` reproduces that. A single scan callback
+usually only sees one of the two packets; `scan_devices()` in discovery.py
+therefore collects over the entire scan window.
+"""
+from __future__ import annotations
+
+import struct
+from dataclasses import dataclass
+from typing import Optional
+
+COMPANY_ID = 1972  # 0x07B4
+
+# SAL.BlueConnect.API.Devices.Info.DeviceData.DeviceService.ProductType, incomplete
+# (only the mappings visible in the decompiled BLEAdvertisementData.cs)
+PRODUCT_TYPE_NAMES = {
+    (1, None): "HET",
+    (2, 1): "Supramatic Serie 4",
+    (2, 2): "Supramatic Serie 4",
+    (2, 17): "Rollmatic 2",
+    (2, 33): "SilentDrive 2",
+    (2, 49): "Supramatic 4 H4",
+    (3, 1): "ST560", (3, 2): "ST560", (3, 8): "ST560", (3, 40): "ST560",
+    (3, 17): "ST560 Dockleveller",
+    (3, 33): "ST545",
+}
+
+
+def _bit(b: int, position: int) -> bool:
+    """DeviceData.GetBitFromByte: position is 1-indexed (1 = LSB)."""
+    return (b & (1 << (position - 1))) != 0
+
+
+def combine_manufacturer_payloads(payloads: list[bytes]) -> bytes:
+    """2-byte company ID (LE) + the payloads seen, shortest first - see module
+    docstring. With only one payload seen, only that one is used; the length
+    then usually isn't enough for the full parser (>=17 bytes needed, see
+    AdvertisementInfo.parse_error)."""
+    ordered = sorted(set(payloads), key=len)
+    return COMPANY_ID.to_bytes(2, "little") + b"".join(ordered)
+
+
+@dataclass
+class AdvertisementInfo:
+    """Everything that can be read purely from the advertisement without a
+    root key. Fields stay None if not enough raw data was seen, or the field
+    isn't defined for the given product type (see parse_error)."""
+
+    address: str
+    rssi: int
+    raw_manufacturer_data: list[str]  # hex strings, as seen during the scan
+
+    product_class: Optional[int] = None
+    product_id: Optional[int] = None
+    product_name: Optional[str] = None
+    serial_no: Optional[int] = None
+    is_blue_secur: Optional[bool] = None
+    clock_time_set: Optional[bool] = None
+    protection_active: Optional[bool] = None
+    admin_teached: Optional[bool] = None
+    admins_can_be_teached: Optional[bool] = None
+
+    in_action: Optional[bool] = None
+    opening_time: Optional[bool] = None
+    warning_time: Optional[bool] = None
+    emergency_mode: Optional[bool] = None
+    low_battery: Optional[bool] = None
+    teached_control: Optional[bool] = None
+    vacation_mode: Optional[bool] = None
+
+    relais1_open: Optional[bool] = None
+    relais2_open: Optional[bool] = None
+    opening_progress_percent: Optional[float] = None
+    maintenance_required: Optional[bool] = None
+
+    parse_error: Optional[str] = None
+
+    @classmethod
+    def from_scan(cls, address: str, rssi: int, payloads: list[bytes]) -> "AdvertisementInfo":
+        info = cls(address=address, rssi=rssi, raw_manufacturer_data=[p.hex() for p in payloads])
+        if not payloads:
+            return info
+        distinct = list({p for p in payloads})
+        if len(distinct) < 2:
+            # Empirically (see module docstring) the device sends status/product
+            # info in two alternating packets - with only one of them the length
+            # and "enough bytes present" checks would pass, but the result would
+            # be computed from the wrong bytes (e.g. all flags falsely False).
+            # Better to honestly parse nothing than to fake a wrong result.
+            info.parse_error = (f"only {len(distinct)} distinct manufacturer-data packet(s) "
+                                 "seen, need at least 2 for full parsing - "
+                                 "scan longer (increase --timeout)")
+            return info
+        try:
+            info._parse(combine_manufacturer_payloads(distinct))
+        except Exception as exc:  # advertisement parsing must never crash a scan
+            info.parse_error = f"{type(exc).__name__}: {exc}"
+        return info
+
+    def _parse(self, data: bytes) -> None:
+        # BLEAdvertisementData.ParseData
+        if len(data) < 4:
+            self.parse_error = "not enough raw data for product class/ID"
+            return
+        product_id, product_class = data[2], data[3]
+        self.product_class = product_class
+        self.product_id = product_id
+        self.product_name = (PRODUCT_TYPE_NAMES.get((product_class, product_id))
+                              or PRODUCT_TYPE_NAMES.get((product_class, None)))
+
+        if len(data) < 17:
+            self.parse_error = (f"only {len(data)} of the required >=17 bytes seen "
+                                 "(maybe not both advertisement packets were captured during the scan)")
+            return
+
+        status_byte = data[4]
+        self.is_blue_secur = _bit(status_byte, 1)
+        self.clock_time_set = _bit(status_byte, 3)
+        self.admin_teached = _bit(status_byte, 4)
+        self.protection_active = _bit(status_byte, 5)
+        self.admins_can_be_teached = _bit(status_byte, 6)
+        self.in_action = _bit(status_byte, 7)
+        self.opening_time = _bit(status_byte, 8)
+
+        # BlueSecurAdvertisementService/ServiceProduct receive the same 13 bytes from here on
+        product_data = data[4:17]
+        if len(product_data) >= 2:
+            b1 = product_data[1]
+            self.warning_time = _bit(b1, 1)
+            self.emergency_mode = _bit(b1, 2)
+            self.low_battery = _bit(b1, 3)
+            self.teached_control = not _bit(b1, 7)
+            self.vacation_mode = _bit(b1, 8)
+
+        if product_class == 1 and len(product_data) >= 1:
+            # HetBlueSecurAdvertisementService.ParseData replaces the ServiceProduct base fields entirely
+            self.relais1_open = _bit(product_data[0], 1)
+            self.relais2_open = _bit(product_data[0], 2)
+        elif product_class == 2 and len(product_data) >= 7:
+            # SupramaticBlueSecurAdvertisementService.ParseDeviceDependentData
+            self.opening_progress_percent = product_data[5] / 2.0
+            self.maintenance_required = _bit(product_data[6], 1)
+
+        # BLEAdvertisementData.ParseData: the serial number follows as a uint64 LE
+        # from position 17 (4+13) onward - verified live against the QR code prefix
+        # of the same device (see protocol.serial_no_from_qr_prefix).
+        if len(data) >= 25:
+            self.serial_no = struct.unpack_from("<Q", data, 17)[0]

hoermoles_ble-0.2.0/src/hoermoles_ble/ble_transport.py

@@ -0,0 +1,50 @@
+"""bleak-based BleTransport implementation (Linux/BlueZ, macOS, Windows)."""
+from __future__ import annotations
+
+from typing import Callable, Optional
+
+from bleak import BleakClient
+
+from .protocol import BC_RX, BC_TX
+from .transport import BleTransport
+
+
+class BleakTransport(BleTransport):
+    def __init__(self, address: str, adapter: Optional[str] = None,
+                 on_log: Optional[Callable[[str], None]] = None):
+        self._address = address
+        self._adapter = adapter
+        self._on_log = on_log or (lambda msg: None)
+        self._client: Optional[BleakClient] = None
+
+    def _on_disconnected(self, client: BleakClient) -> None:
+        self._on_log(f"BLE connection lost (disconnected_callback), was connected={client.is_connected}")
+
+    async def connect(self) -> None:
+        self._client = BleakClient(self._address, adapter=self._adapter,
+                                    disconnected_callback=self._on_disconnected)
+        await self._client.connect()
+        self._on_log(f"MTU after connecting: {self._client.mtu_size}")
+
+    async def disconnect(self) -> None:
+        if self._client is not None:
+            await self._client.disconnect()
+            self._client = None
+
+    async def write(self, data: bytes) -> None:
+        assert self._client is not None, "not connected"
+        self._on_log(f"  write_gatt_char {len(data)} bytes: {data.hex()} "
+                     f"(is_connected={self._client.is_connected})")
+        await self._client.write_gatt_char(BC_TX, data, response=False)
+
+    async def start_notify(self, callback: Callable[[bytes], None]) -> None:
+        assert self._client is not None, "not connected"
+
+        def _on_notify(_, data: bytearray) -> None:
+            callback(bytes(data))
+
+        await self._client.start_notify(BC_RX, _on_notify)
+
+    async def stop_notify(self) -> None:
+        if self._client is not None:
+            await self._client.stop_notify(BC_RX)