bmx-ble 0.1.0__tar.gz

bmx_ble-0.1.0/LICENSE

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

bmx_ble-0.1.0/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: bmx-ble
+Version: 0.1.0
+Summary: BLE protocol support for BM2 battery monitors
+Author: Andrew Stewart
+License-Expression: MIT
+Project-URL: Repository, https://github.com/andystewart999/bmx-ble
+Project-URL: Issues, https://github.com/andystewart999/bmx-ble/issues
+Keywords: BM2,Bluetooth,BLE,battery-monitor
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Home Automation
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: bleak>=0.22.0
+Requires-Dist: bleak-retry-connector>=3.0.0
+Requires-Dist: pycryptodome>=3.20.0
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: pytest-asyncio>=0.24; extra == "test"
+Dynamic: license-file
+
+# bmx-ble
+
+Python library for BMx battery monitor BLE advertisements and GATT notifications.
+The initial release supports BM2; the package name allows additional BM models
+to be supported later.
+
+It decodes legacy percentage advertisements and encrypted enhanced voltage and
+percentage advertisements, validates the BM2 notification characteristic, and
+tries an active GATT reading before falling back to cached advertisement data.
+
+## Installation
+
+```bash
+python -m pip install bmx-ble
+```
+
+## Use
+
+```python
+from bmx_ble import BM2Protocol
+
+monitor = BM2Protocol()
+monitor.process_advertisement(service_info.manufacturer_data)
+reading = await monitor.async_poll(ble_device)  # None allows passive fallback.
+print(reading.voltage, reading.percentage, reading.generation)
+```
+
+Supply a `bleak.backends.device.BLEDevice` for active reading. Connection
+failures propagate when no usable advertisement has been cached.
+
+## Development
+
+```bash
+python -m pip install -e '.[test]'
+python -m pytest
+python -m build
+```
+
+The Home Assistant integration is kept separately from this library.
+
+## Publishing
+
+Create a public repository with this source and an enabled issue tracker.
+Set up PyPI Trusted Publishing for the repository's release workflow, tag a
+release matching the version in `pyproject.toml`, then run the publish workflow.
+Confirm the project name is available on PyPI before the first release.
+
+## License
+
+MIT; see `LICENSE`.

bmx_ble-0.1.0/README.md

@@ -0,0 +1,50 @@
+# bmx-ble
+
+Python library for BMx battery monitor BLE advertisements and GATT notifications.
+The initial release supports BM2; the package name allows additional BM models
+to be supported later.
+
+It decodes legacy percentage advertisements and encrypted enhanced voltage and
+percentage advertisements, validates the BM2 notification characteristic, and
+tries an active GATT reading before falling back to cached advertisement data.
+
+## Installation
+
+```bash
+python -m pip install bmx-ble
+```
+
+## Use
+
+```python
+from bmx_ble import BM2Protocol
+
+monitor = BM2Protocol()
+monitor.process_advertisement(service_info.manufacturer_data)
+reading = await monitor.async_poll(ble_device)  # None allows passive fallback.
+print(reading.voltage, reading.percentage, reading.generation)
+```
+
+Supply a `bleak.backends.device.BLEDevice` for active reading. Connection
+failures propagate when no usable advertisement has been cached.
+
+## Development
+
+```bash
+python -m pip install -e '.[test]'
+python -m pytest
+python -m build
+```
+
+The Home Assistant integration is kept separately from this library.
+
+## Publishing
+
+Create a public repository with this source and an enabled issue tracker.
+Set up PyPI Trusted Publishing for the repository's release workflow, tag a
+release matching the version in `pyproject.toml`, then run the publish workflow.
+Confirm the project name is available on PyPI before the first release.
+
+## License
+
+MIT; see `LICENSE`.

bmx_ble-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "bmx-ble"
+version = "0.1.0"
+description = "BLE protocol support for BM2 battery monitors"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+authors = [{name = "Andrew Stewart"}]
+keywords = ["BM2", "Bluetooth", "BLE", "battery-monitor"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Home Automation",
+]
+dependencies = [
+    "bleak>=0.22.0",
+    "bleak-retry-connector>=3.0.0",
+    "pycryptodome>=3.20.0",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=8", "pytest-asyncio>=0.24"]
+
+[project.urls]
+Repository = "https://github.com/andystewart999/bmx-ble"
+Issues = "https://github.com/andystewart999/bmx-ble/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

bmx_ble-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

bmx_ble-0.1.0/src/bmx_ble/__init__.py

@@ -0,0 +1,5 @@
+"""BM2 Bluetooth battery monitor protocol."""
+
+from .protocol import BM2Generation, BM2Protocol, BM2Reading
+
+__all__ = ["BM2Generation", "BM2Protocol", "BM2Reading"]

bmx_ble-0.1.0/src/bmx_ble/protocol.py

@@ -0,0 +1,408 @@
+"""BM2 BLE advertisements and active GATT protocol (no Home Assistant dependency)."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from dataclasses import dataclass
+from enum import StrEnum
+
+from bleak import BleakError, BLEDevice
+from bleak_retry_connector import (
+    BleakClientWithServiceCache,
+    establish_connection,
+    retry_bluetooth_connection_error,
+)
+from Crypto.Cipher import AES
+
+_LOGGER = logging.getLogger(__name__)
+GATT_TIMEOUT = 20
+BM2_CHARACTERISTIC = "{0000fff4-0000-1000-8000-00805f9b34fb}"
+VALID_BATTERY_STATUSES = frozenset({0, 1, 2, 4, 8})
+
+# The BM2 GATT notification and the newer encrypted manufacturer advertisement
+# use the same AES-128-CBC key and a zero IV.
+BM2_AES_KEY = bytes(
+    [108, 101, 97, 103, 101, 110, 100, 255, 254, 49, 56, 56, 50, 52, 54, 54]
+)
+BM2_AES_IV = bytes(16)
+
+# The useful manufacturer-data BODY is 14 bytes in Home Assistant.  HA keeps
+# the two-byte manufacturer identifier separately as the dict key, so those
+# two bytes are prepended before decrypting the resulting 16-byte block.
+BM2_ENHANCED_ADVERTISEMENT_PAYLOAD_LENGTH = 14
+
+# Legacy BM2s use an iBeacon-shaped Apple manufacturer record.  Home Assistant
+# removes the 0x004C manufacturer ID, leaving a 23-byte body:
+#   02 15 + fixed 16-byte UUID + major(2) + minor(2) + percentage(1)
+BM2_LEGACY_MANUFACTURER_ID = 0x004C
+BM2_LEGACY_PAYLOAD_LENGTH = 23
+BM2_LEGACY_PREFIX = bytes.fromhex("0215655f83caae16a10a702e31f30d58dd82")
+
+# Sanity bounds are aligned to what the BM2 itself supports
+# 10-15 V range so unusual 12 V battery chemistries/states are not rejected.
+BM2_MIN_VALID_VOLTAGE = 6.0
+BM2_MAX_VALID_VOLTAGE = 20.0
+BM2_MIN_VALID_PERCENTAGE = 0
+BM2_MAX_VALID_PERCENTAGE = 100
+
+
+class BM2Generation(StrEnum):
+    """General BM2 protocol generation inferred from advertisement format."""
+
+    UNKNOWN = "Unknown"
+    LEGACY = "Legacy (percentage advertisement)"
+    ENHANCED = "Enhanced (voltage + percentage advertisement)"
+
+
+@dataclass(frozen=True)
+class BM2Reading:
+    """A decoded BM2 reading from a notification or advertisement."""
+
+    voltage: float | None
+    percentage: int | None
+    status: int | None
+    source: str
+    generation: BM2Generation = BM2Generation.UNKNOWN
+
+
+class BM2Protocol:
+    """Decode BM2 packets and read FFF4 notifications via Bleak.
+
+    Home Assistant is responsible for scan discovery, poll scheduling and entities.
+    """
+
+    def __init__(self) -> None:
+        """Create an independent BM2 reader with no cached telemetry."""
+        self._gattdata: bytes | None = None
+        self._ignore_advertisement = False
+        self._advertisement_reading: BM2Reading | None = None
+        self._bm2_generation = BM2Generation.UNKNOWN
+
+    @property
+    def bm2_generation(self) -> BM2Generation:
+        """Return the most capable advertisement format seen so far."""
+        return self._bm2_generation
+
+    @property
+    def ignore_advertisement(self) -> bool:
+        """Return whether an active notification read is in progress."""
+        return self._ignore_advertisement
+
+    def process_advertisement(self, manufacturer_data: dict[int, bytes]) -> None:
+        """Cache recognised advertisements, retaining enhanced voltage when possible."""
+        reading = self._decode_advertisement(manufacturer_data)
+        if reading is not None:
+            # CONFIG FLOW / GENERATION:
+            # Enhanced BM2s can emit BOTH the old iBeacon-style percentage
+            # packet and the newer encrypted voltage+percentage packet.
+            #
+            # Once Enhanced has been positively observed, never downgrade the
+            # device back to Legacy merely because the next advertisement was
+            # the old-format packet.
+            if reading.generation is BM2Generation.ENHANCED:
+                self._bm2_generation = BM2Generation.ENHANCED
+                self._advertisement_reading = reading
+
+            elif (
+                reading.generation is BM2Generation.LEGACY
+                and self._bm2_generation is BM2Generation.ENHANCED
+                and self._advertisement_reading is not None
+            ):
+                # Preserve the most recently known enhanced voltage while
+                # accepting the fresher percentage from the legacy packet.
+                self._advertisement_reading = BM2Reading(
+                    voltage=self._advertisement_reading.voltage,
+                    percentage=reading.percentage,
+                    status=None,
+                    source="advertisement",
+                    generation=BM2Generation.ENHANCED,
+                )
+
+            else:
+                self._bm2_generation = reading.generation
+                self._advertisement_reading = reading
+
+            _LOGGER.debug(
+                "Cached BM2 advertisement reading: generation=%s, "
+                "voltage=%s, percentage=%s",
+                self._bm2_generation,
+                self._advertisement_reading.voltage,
+                self._advertisement_reading.percentage,
+            )
+
+    @staticmethod
+    def _decrypt(data: bytes) -> bytes:
+        """Decrypt one complete 16-byte BM2 AES block."""
+        if len(data) != AES.block_size:
+            raise ValueError(
+                f"BM2 encrypted payload must be {AES.block_size} bytes; "
+                f"received {len(data)}"
+            )
+
+        cipher = AES.new(BM2_AES_KEY, AES.MODE_CBC, BM2_AES_IV)
+        return cipher.decrypt(data)
+
+    # ADVERTISEMENT FALLBACK:
+    def _decode_advertisement(
+        self,
+        manufacturer_data: dict[int, bytes],
+    ) -> BM2Reading | None:
+        """Decode either known BM2 advertisement generation.
+
+        Enhanced/newer format:
+            - any 14-byte manufacturer-data body
+            - prepend the two-byte manufacturer ID (little-endian)
+            - AES decrypt the resulting 16-byte block
+            - decrypted bytes 6-7 = voltage * 100, big-endian
+            - decrypted byte 8 = battery percentage
+
+        Legacy/older format:
+            - Apple manufacturer ID 0x004C
+            - 23-byte iBeacon-shaped body
+            - fixed BM2 UUID prefix
+            - final byte = battery percentage
+            - no voltage is present in the advertisement
+        """
+
+        # Prefer the enhanced packet when both formats are advertised.
+        for manufacturer_id, payload in manufacturer_data.items():
+            if len(payload) != BM2_ENHANCED_ADVERTISEMENT_PAYLOAD_LENGTH:
+                continue
+
+            encrypted = manufacturer_id.to_bytes(2, byteorder="little") + payload
+
+            try:
+                decrypted = self._decrypt(encrypted)
+            except ValueError:
+                continue
+
+            voltage = int.from_bytes(decrypted[6:8], byteorder="big") / 100.0
+            percentage = decrypted[8]
+
+            # Packet length alone is not enough to identify BM2 telemetry.
+            if not BM2_MIN_VALID_VOLTAGE <= voltage <= BM2_MAX_VALID_VOLTAGE:
+                continue
+            if not (BM2_MIN_VALID_PERCENTAGE <= percentage <= BM2_MAX_VALID_PERCENTAGE):
+                continue
+
+            return BM2Reading(
+                voltage=voltage,
+                percentage=percentage,
+                status=None,
+                source="advertisement",
+                generation=BM2Generation.ENHANCED,
+            )
+
+        # Legacy packet: Home Assistant exposes 0x004C as the dict key, so the
+        # payload itself begins at the iBeacon 0x02 0x15 marker.
+        legacy_payload = manufacturer_data.get(BM2_LEGACY_MANUFACTURER_ID)
+
+        if (
+            legacy_payload is not None
+            and len(legacy_payload) == BM2_LEGACY_PAYLOAD_LENGTH
+            and legacy_payload.startswith(BM2_LEGACY_PREFIX)
+        ):
+            percentage = legacy_payload[-1]
+
+            if BM2_MIN_VALID_PERCENTAGE <= percentage <= BM2_MAX_VALID_PERCENTAGE:
+                return BM2Reading(
+                    voltage=None,
+                    percentage=percentage,
+                    status=None,
+                    source="advertisement",
+                    generation=BM2Generation.LEGACY,
+                )
+
+        return None
+
+    def _decode_gatt(self, data: bytes) -> BM2Reading:
+        """Decode the BM2 GATT notification payload."""
+        decrypted = self._decrypt(data)
+
+        # Preserve the currently proven GATT byte/nibble mapping from the
+        # existing integration:
+        #   voltage    = decrypted hex chars [2:5] / 100
+        #   status     = decrypted hex char  [5:6]
+        #   percentage = decrypted hex chars [6:8]
+        raw = decrypted.hex()
+
+        return BM2Reading(
+            voltage=int(raw[2:5], 16) / 100.0,
+            percentage=int(raw[6:8], 16),
+            status=int(raw[5:6], 16),
+            source="gatt",
+            generation=BM2Generation.UNKNOWN,
+        )
+
+    @retry_bluetooth_connection_error()
+    async def _get_payload(
+        self,
+        client: BleakClientWithServiceCache,
+    ) -> BM2Reading:
+        """Read and decode the active BM2 GATT notification."""
+        self._gattdata = None
+        self._ignore_advertisement = True
+
+        try:
+            await client.start_notify(
+                BM2_CHARACTERISTIC,
+                self.notification_handler,
+            )
+
+            ticks = 0
+            while self._gattdata is None and ticks < GATT_TIMEOUT * 4:
+                await asyncio.sleep(0.25)
+                ticks += 1
+
+        finally:
+            # Always attempt to stop notification handling and, importantly,
+            # always clear the ignore flag even if Bleak throws.
+            try:
+                await client.stop_notify(BM2_CHARACTERISTIC)
+            finally:
+                self._ignore_advertisement = False
+
+        if self._gattdata is None:
+            # CHANGED:
+            # The previous implementation silently returned here.  Raising
+            # makes a no-notification timeout a genuine failed active read,
+            # allowing async_poll() to use the cached advertisement.
+            raise BleakError(
+                f"Timed out waiting for BM2 GATT notification from {client.address}"
+            )
+
+        _LOGGER.debug(
+            "Successfully read characteristic %s",
+            BM2_CHARACTERISTIC,
+        )
+        return self._decode_gatt(self._gattdata)
+
+    def notification_handler(self, sender, data: bytearray) -> None:
+        """Bluetooth notification handler."""
+        self._gattdata = bytes(data)
+
+    async def async_validate_active(self, ble_device: BLEDevice) -> bool:
+        """Positively validate a BM2 using its active GATT protocol.
+
+        This is intended for config-flow validation only.
+
+        Returns:
+            True:
+                FFF4 exists, a notification was received, it decrypted with
+                the BM2 key, and the decoded values are plausible.
+
+            False:
+                The device is positively incompatible (for example FFF4 is
+                absent, or a notification decrypts to implausible BM2 data).
+
+        Connection errors and notification timeouts deliberately propagate.
+        The config flow treats those as "could not validate" rather than
+        incorrectly declaring that the device is not a BM2.
+        """
+        client: BleakClientWithServiceCache | None = None
+
+        try:
+            client = await establish_connection(
+                BleakClientWithServiceCache,
+                ble_device,
+                ble_device.address,
+            )
+
+            target_uuid = BM2_CHARACTERISTIC.lower().strip("{}")
+
+            characteristic_found = any(
+                characteristic.uuid.lower().strip("{}") == target_uuid
+                for service in client.services
+                for characteristic in service.characteristics
+            )
+
+            if not characteristic_found:
+                _LOGGER.debug(
+                    "BM2 validation failed for %s: characteristic %s not found",
+                    ble_device.address,
+                    BM2_CHARACTERISTIC,
+                )
+                return False
+
+            reading = await self._get_payload(client)
+
+            if reading.voltage is None or reading.percentage is None:
+                return False
+
+            if not (BM2_MIN_VALID_VOLTAGE <= reading.voltage <= BM2_MAX_VALID_VOLTAGE):
+                return False
+
+            if not (
+                BM2_MIN_VALID_PERCENTAGE
+                <= reading.percentage
+                <= BM2_MAX_VALID_PERCENTAGE
+            ):
+                return False
+
+            return not (
+                reading.status is not None
+                and reading.status not in VALID_BATTERY_STATUSES
+            )
+
+        finally:
+            if client is not None:
+                await client.disconnect()
+
+    async def async_poll(
+        self,
+        ble_device: BLEDevice | None,
+    ) -> BM2Reading:
+        """Prefer an active GATT read and fall back to advertisement data.
+
+        Passing ble_device=None means Home Assistant heard the device through a
+        passive scanner/proxy but currently has no connectable Bluetooth path.
+        """
+        client: BleakClientWithServiceCache | None = None
+
+        try:
+            if ble_device is None:
+                raise BleakError("No connectable Bluetooth path is currently available")
+
+            _LOGGER.debug(
+                "Connecting to Bluetooth device %s",
+                ble_device.address,
+            )
+
+            client = await establish_connection(
+                BleakClientWithServiceCache,
+                ble_device,
+                ble_device.address,
+            )
+
+            _LOGGER.debug(
+                "Connected to BM2 device %s",
+                ble_device.address,
+            )
+
+            reading = await self._get_payload(client)
+            return reading
+
+        except Exception as ex:
+            # ADVERTISEMENT FALLBACK:
+            # Active connection/read failed.  If the immediately preceding
+            # advertisement contained usable telemetry, publish it instead.
+            if self._advertisement_reading is not None:
+                address = ble_device.address if ble_device is not None else "unknown"
+                _LOGGER.debug(
+                    "Active BM2 read failed for %s (%s); using cached "
+                    "advertisement data",
+                    address,
+                    ex,
+                )
+                return self._advertisement_reading
+
+            # No usable passive fallback exists, so preserve the failure.
+            raise
+
+        finally:
+            if client is not None:
+                try:
+                    await client.disconnect()
+                finally:
+                    _LOGGER.debug("Disconnected from active Bluetooth client")

bmx_ble-0.1.0/src/bmx_ble.egg-info/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: bmx-ble
+Version: 0.1.0
+Summary: BLE protocol support for BM2 battery monitors
+Author: Andrew Stewart
+License-Expression: MIT
+Project-URL: Repository, https://github.com/andystewart999/bmx-ble
+Project-URL: Issues, https://github.com/andystewart999/bmx-ble/issues
+Keywords: BM2,Bluetooth,BLE,battery-monitor
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Home Automation
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: bleak>=0.22.0
+Requires-Dist: bleak-retry-connector>=3.0.0
+Requires-Dist: pycryptodome>=3.20.0
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: pytest-asyncio>=0.24; extra == "test"
+Dynamic: license-file
+
+# bmx-ble
+
+Python library for BMx battery monitor BLE advertisements and GATT notifications.
+The initial release supports BM2; the package name allows additional BM models
+to be supported later.
+
+It decodes legacy percentage advertisements and encrypted enhanced voltage and
+percentage advertisements, validates the BM2 notification characteristic, and
+tries an active GATT reading before falling back to cached advertisement data.
+
+## Installation
+
+```bash
+python -m pip install bmx-ble
+```
+
+## Use
+
+```python
+from bmx_ble import BM2Protocol
+
+monitor = BM2Protocol()
+monitor.process_advertisement(service_info.manufacturer_data)
+reading = await monitor.async_poll(ble_device)  # None allows passive fallback.
+print(reading.voltage, reading.percentage, reading.generation)
+```
+
+Supply a `bleak.backends.device.BLEDevice` for active reading. Connection
+failures propagate when no usable advertisement has been cached.
+
+## Development
+
+```bash
+python -m pip install -e '.[test]'
+python -m pytest
+python -m build
+```
+
+The Home Assistant integration is kept separately from this library.
+
+## Publishing
+
+Create a public repository with this source and an enabled issue tracker.
+Set up PyPI Trusted Publishing for the repository's release workflow, tag a
+release matching the version in `pyproject.toml`, then run the publish workflow.
+Confirm the project name is available on PyPI before the first release.
+
+## License
+
+MIT; see `LICENSE`.

bmx_ble-0.1.0/src/bmx_ble.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+src/bmx_ble/__init__.py
+src/bmx_ble/protocol.py
+src/bmx_ble.egg-info/PKG-INFO
+src/bmx_ble.egg-info/SOURCES.txt
+src/bmx_ble.egg-info/dependency_links.txt
+src/bmx_ble.egg-info/requires.txt
+src/bmx_ble.egg-info/top_level.txt
+tests/test_protocol.py

bmx_ble-0.1.0/src/bmx_ble.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

bmx_ble-0.1.0/src/bmx_ble.egg-info/requires.txt

@@ -0,0 +1,7 @@
+bleak>=0.22.0
+bleak-retry-connector>=3.0.0
+pycryptodome>=3.20.0
+
+[test]
+pytest>=8
+pytest-asyncio>=0.24

bmx_ble-0.1.0/src/bmx_ble.egg-info/top_level.txt

@@ -0,0 +1 @@
+bmx_ble

bmx_ble-0.1.0/tests/test_protocol.py

@@ -0,0 +1,116 @@
+"""BM2 packet and connection behaviour without Home Assistant."""
+
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, patch
+
+import pytest
+from bmx_ble import BM2Generation, BM2Protocol
+from bmx_ble.protocol import BM2_AES_IV, BM2_AES_KEY, BM2_CHARACTERISTIC
+from Crypto.Cipher import AES
+
+
+def _encrypt(plain: bytes) -> bytes:
+    return AES.new(BM2_AES_KEY, AES.MODE_CBC, BM2_AES_IV).encrypt(plain)
+
+
+def _enhanced_packet(
+    voltage_cents: int = 1250, percentage: int = 75
+) -> dict[int, bytes]:
+    plain = bytearray(16)
+    plain[6:8] = voltage_cents.to_bytes(2, "big")
+    plain[8] = percentage
+    encrypted = _encrypt(bytes(plain))
+    return {int.from_bytes(encrypted[:2], "little"): encrypted[2:]}
+
+
+LEGACY_PACKET = {
+    0x004C: bytes.fromhex("0215655f83caae16a10a702e31f30d58dd82")
+    + bytes.fromhex("00010002")
+    + bytes([48])
+}
+
+
+def test_legacy_packet() -> None:
+    """A recognised legacy frame provides only percentage."""
+    monitor = BM2Protocol()
+    monitor.process_advertisement(LEGACY_PACKET)
+    assert monitor.bm2_generation is BM2Generation.LEGACY
+    reading = monitor._advertisement_reading
+    assert reading is not None
+    assert reading.voltage is None
+    assert reading.percentage == 48
+
+
+def test_enhanced_then_legacy_preserves_voltage() -> None:
+    """Alternating packets must keep known enhanced voltage and fresh percentage."""
+    monitor = BM2Protocol()
+    monitor.process_advertisement(_enhanced_packet())
+    monitor.process_advertisement(LEGACY_PACKET)
+    assert monitor.bm2_generation is BM2Generation.ENHANCED
+    assert monitor._advertisement_reading is not None
+    assert monitor._advertisement_reading.voltage == 12.5
+    assert monitor._advertisement_reading.percentage == 48
+
+
+def test_invalid_packet_is_ignored() -> None:
+    """Plausible frame shape alone must not identify a BM2."""
+    monitor = BM2Protocol()
+    monitor.process_advertisement(_enhanced_packet(voltage_cents=500))
+    monitor.process_advertisement({0x004C: b"\x02\x15" + bytes(21)})
+    assert monitor.bm2_generation is BM2Generation.UNKNOWN
+
+
+def test_gatt_payload() -> None:
+    """GATT decryption preserves the established voltage/status mapping."""
+    plain = bytes.fromhex("004e2464" + "00" * 12)
+    reading = BM2Protocol()._decode_gatt(_encrypt(plain))
+    assert (reading.voltage, reading.percentage, reading.status) == (12.5, 100, 4)
+
+
+@pytest.mark.asyncio
+async def test_passive_fallback_and_missing_data() -> None:
+    """A cached packet works without a connectable path; no packet fails."""
+    monitor = BM2Protocol()
+    with pytest.raises(Exception, match="No connectable Bluetooth path"):
+        await monitor.async_poll(None)
+    monitor.process_advertisement(LEGACY_PACKET)
+    reading = await monitor.async_poll(None)
+    assert reading.percentage == 48
+
+
+@pytest.mark.asyncio
+async def test_active_validation_and_poll() -> None:
+    """Validate FFF4 with a decryptable notification and return its data."""
+    notification = _encrypt(bytes.fromhex("004e2464" + "00" * 12))
+    client = SimpleNamespace(
+        address="AA:BB:CC:DD:EE:FF",
+        services=[
+            SimpleNamespace(characteristics=[SimpleNamespace(uuid=BM2_CHARACTERISTIC)])
+        ],
+        start_notify=AsyncMock(
+            side_effect=lambda _uuid, callback: callback(0, bytearray(notification))
+        ),
+        stop_notify=AsyncMock(),
+        disconnect=AsyncMock(),
+    )
+    device = SimpleNamespace(address=client.address)
+    with patch(
+        "bmx_ble.protocol.establish_connection", new=AsyncMock(return_value=client)
+    ):
+        assert await BM2Protocol().async_validate_active(device)
+        reading = await BM2Protocol().async_poll(device)
+    assert reading.voltage == 12.5
+    assert reading.status == 4
+    assert client.disconnect.await_count == 2
+
+
+@pytest.mark.asyncio
+async def test_active_validation_rejects_missing_characteristic() -> None:
+    """Successful connection without FFF4 is a positive rejection."""
+    client = SimpleNamespace(services=[], disconnect=AsyncMock())
+    device = SimpleNamespace(address="AA:BB:CC:DD:EE:FF")
+    with patch(
+        "bmx_ble.protocol.establish_connection", new=AsyncMock(return_value=client)
+    ):
+        assert not await BM2Protocol().async_validate_active(device)
+    client.disconnect.assert_awaited_once()