aiobmsble 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

aiobmsble/__init__.py

@@ -1,9 +1,12 @@
 """Package for battery management systems (BMS) via Bluetooth LE."""
 
-from typing import Literal, TypedDict
+from collections.abc import Callable
+from enum import IntEnum
+from typing import Any, Literal, NamedTuple, TypedDict
 
 type BMSvalue = Literal[
     "battery_charging",
+    "battery_mode",
     "battery_level",
     "current",
     "power",
@@ -15,36 +18,77 @@ type BMSvalue = Literal[
     "delta_voltage",
     "problem",
     "runtime",
+    "balance_current",
+    "cell_count",
     "cell_voltages",
     "design_capacity",
+    "pack_count",
+    "temp_sensors",
     "temp_values",
     "problem_code",
 ]
 
+type BMSpackvalue = Literal[
+    "pack_voltages",
+    "pack_currents",
+    "pack_battery_levels",
+    "pack_cycles",
+]
+
+
+class BMSmode(IntEnum):
+    """Enumeration of BMS modes."""
+
+    UNKNOWN = -1
+    BULK = 0x00
+    ABSORPTION = 0x01
+    FLOAT = 0x02
+
 
 class BMSsample(TypedDict, total=False):
     """Dictionary representing a sample of battery management system (BMS) data."""
 
-    battery_charging: bool
+    battery_charging: bool  # True: battery charging
+    battery_mode: BMSmode  # BMS charging mode
     battery_level: int | float  # [%]
-    current: float  # [A]
-    power: float  # [W]
+    current: float  # [A] (positive: charging)
+    power: float  # [W] (positive: charging)
     temperature: int | float  # [°C]
     voltage: float  # [V]
     cycle_capacity: int | float  # [Wh]
     cycles: int  # [#]
     delta_voltage: float  # [V]
-    problem: bool
+    problem: bool  # True: problem detected
     runtime: int  # [s]
-    # internal
+    # detailed information
+    balance_current: float  # [A]
+    cell_count: int  # [#]
     cell_voltages: list[float]  # [V]
     cycle_charge: int | float  # [Ah]
     design_capacity: int  # [Ah]
+    pack_count: int  # [#]
+    temp_sensors: int  # [#]
     temp_values: list[int | float]  # [°C]
-    problem_code: int
+    problem_code: int  # BMS specific code, 0 no problem
+    # battery pack data
+    pack_voltages: list[float]  # [V]
+    pack_currents: list[float]  # [A]
+    pack_battery_levels: list[int | float]  # [%]
+    pack_cycles: list[int]  # [#]
+
+
+class BMSdp(NamedTuple):
+    """Representation of one BMS data point."""
+
+    key: BMSvalue  # the key of the value to be parsed
+    pos: int  # position within the message
+    size: int  # size in bytes
+    signed: bool  # signed value
+    fct: Callable[[int], Any] = lambda x: x  # conversion function (default do nothing)
+    idx: int = -1  # array index containing the message to be parsed
 
 
-class AdvertisementPattern(TypedDict, total=False):
+class MatcherPattern(TypedDict, total=False):
     """Optional patterns that can match Bleak advertisement data."""
 
     local_name: str  # name pattern that supports Unix shell-style wildcards
@@ -52,3 +96,4 @@ class AdvertisementPattern(TypedDict, total=False):
     service_data_uuid: str  # service data for the service UUID
     manufacturer_id: int  # required manufacturer ID
     manufacturer_data_start: list[int]  # required starting bytes of manufacturer data
+    connectable: bool  # True if active connections to the device are required

aiobmsble/__main__.py

@@ -1,8 +1,9 @@
 """Example function for package usage."""
 
+import argparse
 import asyncio
 import logging
-from types import ModuleType
+from typing import Final
 
 from bleak import BleakScanner
 from bleak.backends.device import BLEDevice
@@ -10,31 +11,31 @@ from bleak.backends.scanner import AdvertisementData
 from bleak.exc import BleakError
 
 from aiobmsble import BMSsample
-from aiobmsble.bms import ogt_bms
-from aiobmsble.utils import bms_supported
-
-bms_plugins: list[ModuleType] = [ogt_bms]
+from aiobmsble.basebms import BaseBMS
+from aiobmsble.utils import bms_identify
 
 logging.basicConfig(
     format="%(levelname)s: %(message)s",
     level=logging.INFO,
 )
-logger: logging.Logger = logging.getLogger(__name__)
-
-logger.info(
-    "loaded BMS types: %s", [key.__name__.rsplit(".", 1)[-1] for key in bms_plugins]
-)
+logger: logging.Logger = logging.getLogger(__package__)
 
 
-async def detect_bms() -> None:
-    """Query a Bluetooth device based on the provided arguments."""
-
+async def scan_devices() -> dict[str, tuple[BLEDevice, AdvertisementData]]:
+    """Scan for BLE devices and return results."""
     logger.info("starting scan...")
     scan_result: dict[str, tuple[BLEDevice, AdvertisementData]] = (
         await BleakScanner.discover(return_adv=True)
     )
+    logger.info(scan_result)
     logger.info("%i BT devices in range.", len(scan_result))
+    return scan_result
 
+
+async def detect_bms() -> None:
+    """Query a Bluetooth device based on the provided arguments."""
+
+    scan_result: dict[str, tuple[BLEDevice, AdvertisementData]] = await scan_devices()
     for ble_dev, advertisement in scan_result.values():
         logger.info(
             "%s\nBT device '%s' (%s)\n\t%s",
@@ -43,27 +44,50 @@ async def detect_bms() -> None:
             ble_dev.address,
             repr(advertisement).replace(", ", ",\n\t"),
         )
-        for bms_module in bms_plugins:
-            if bms_supported(bms_module.BMS, advertisement):
-                logger.info(
-                    "Found matching BMS type: %s",
-                    bms_module.__name__.rsplit(".", maxsplit=1)[-1],
-                )
-                bms = bms_module.BMS(ble_device=ble_dev, reconnect=True)
-                try:
-                    logger.info("Updating BMS data...")
-                    data: BMSsample = await bms.async_update()
-                    logger.info("BMS data: %s", repr(data).replace(", ", ",\n\t"))
-                except BleakError as ex:
-                    logger.error("Failed to update BMS: %s", ex)
+
+        if bms_cls := bms_identify(advertisement):
+            logger.info("Found matching BMS type: %s", bms_cls.device_id())
+            bms: BaseBMS = bms_cls(ble_device=ble_dev, reconnect=True)
+
+            try:
+                logger.info("Updating BMS data...")
+                data: BMSsample = await bms.async_update()
+                logger.info("BMS data: %s", repr(data).replace(", '", ",\n\t'"))
+            except (BleakError, TimeoutError) as exc:
+                logger.error("Failed to update BMS: %s", type(exc).__name__)
 
     logger.info("done.")
 
 
+def setup_logging(args: argparse.Namespace) -> None:
+    """Configure logging based on command line arguments."""
+    loglevel: Final[int] = logging.DEBUG if args.verbose else logging.INFO
+
+    if args.logfile:
+        file_handler = logging.FileHandler(args.logfile)
+        file_handler.setLevel(loglevel)
+        file_handler.setFormatter(
+            logging.Formatter("%(asctime)s - %(levelname)s: %(message)s")
+        )
+        logger.addHandler(file_handler)
+
+    logger.setLevel(loglevel)
+
+
 def main() -> None:
     """Entry point for the script to run the BMS detection."""
+    parser = argparse.ArgumentParser(
+        description="Reference script for 'aiobmsble' to show all recognized BMS in range."
+    )
+    parser.add_argument("-l", "--logfile", type=str, help="Path to the log file")
+    parser.add_argument(
+        "-v", "--verbose", action="store_true", help="Enable debug logging"
+    )
+
+    setup_logging(parser.parse_args())
+
     asyncio.run(detect_bms())
 
 
 if __name__ == "__main__":
-    main()
+    main()  # pragma: no cover

aiobmsble/basebms.py

@@ -2,34 +2,46 @@
 
 from abc import ABC, abstractmethod
 import asyncio
-from collections.abc import Callable
+from collections.abc import Callable, MutableMapping
 import logging
 from statistics import fmean
-from typing import Any, Final
+from typing import Any, Final, Literal
 
 from bleak import BleakClient
 from bleak.backends.characteristic import BleakGATTCharacteristic
 from bleak.backends.device import BLEDevice
 from bleak.exc import BleakError
-from bleak_retry_connector import establish_connection
+from bleak_retry_connector import BLEAK_TIMEOUT, establish_connection
 
-from aiobmsble import AdvertisementPattern, BMSsample, BMSvalue
-
-KEY_CELL_VOLTAGE: Final[str] = "cell#"  # [V]
+from aiobmsble import BMSdp, BMSsample, BMSvalue, MatcherPattern
 
 
 class BaseBMS(ABC):
     """Abstract base class for battery management system."""
 
-    TIMEOUT = 5.0
+    MAX_RETRY: Final[int] = 3  # max number of retries for data requests
+    TIMEOUT: Final[float] = BLEAK_TIMEOUT / 4  # default timeout for BMS operations
+    # calculate time between retries to complete all retries (2 modes) in TIMEOUT seconds
+    _RETRY_TIMEOUT: Final[float] = TIMEOUT / (2**MAX_RETRY - 1)
+    _MAX_TIMEOUT_FACTOR: Final[int] = 8  # limit timout increase to 8x
     _MAX_CELL_VOLT: Final[float] = 5.906  # max cell potential
     _HRS_TO_SECS: Final[int] = 60 * 60  # seconds in an hour
 
+    class PrefixAdapter(logging.LoggerAdapter):
+        """Logging adpater to add instance ID to each log message."""
+
+        def process(
+            self, msg: str, kwargs: MutableMapping[str, Any]
+        ) -> tuple[str, MutableMapping[str, Any]]:
+            """Process the logging message."""
+            prefix: str = str(self.extra.get("prefix") if self.extra else "")
+            return (f"{prefix} {msg}", kwargs)
+
     def __init__(
         self,
-        logger_name: str,
         ble_device: BLEDevice,
         reconnect: bool = False,
+        logger_name: str = "",
     ) -> None:
         """Intialize the BMS.
 
@@ -49,9 +61,11 @@ class BaseBMS(ABC):
         self._ble_device: Final[BLEDevice] = ble_device
         self._reconnect: Final[bool] = reconnect
         self.name: Final[str] = self._ble_device.name or "undefined"
-        self._log: Final[logging.Logger] = logging.getLogger(
-            f"{logger_name.replace('.plugins', '')}::{self.name}:"
-            f"{self._ble_device.address[-5:].replace(':','')})"
+        self._inv_wr_mode: bool | None = None  # invert write mode (WNR <-> W)
+        logger_name = logger_name or self.__class__.__module__
+        self._log: Final[BaseBMS.PrefixAdapter] = BaseBMS.PrefixAdapter(
+            logging.getLogger(f"{logger_name}"),
+            {"prefix": f"{self.name}|{self._ble_device.address[-5:].replace(':','')}:"},
         )
 
         self._log.debug(
@@ -67,7 +81,7 @@ class BaseBMS(ABC):
 
     @staticmethod
     @abstractmethod
-    def matcher_dict_list() -> list[AdvertisementPattern]:
+    def matcher_dict_list() -> list[MatcherPattern]:
         """Return a list of Bluetooth advertisement matchers."""
 
     @staticmethod
@@ -126,55 +140,78 @@ class BaseBMS(ABC):
             return (value in values) and (value not in data) and using.issubset(data)
 
         cell_voltages: Final[list[float]] = data.get("cell_voltages", [])
-        design_capacity: Final[int | float] = data.get("design_capacity", 0)
         battery_level: Final[int | float] = data.get("battery_level", 0)
-        voltage: Final[float] = data.get("voltage", 0)
-        cycle_charge: Final[int | float] = data.get("cycle_charge", 0)
         current: Final[float] = data.get("current", 0)
 
         calculations: dict[BMSvalue, tuple[set[BMSvalue], Callable[[], Any]]] = {
             "voltage": ({"cell_voltages"}, lambda: round(sum(cell_voltages), 3)),
             "delta_voltage": (
                 {"cell_voltages"},
-                lambda: round(max(cell_voltages) - min(cell_voltages), 3),
+                lambda: (
+                    round(max(cell_voltages) - min(cell_voltages), 3)
+                    if len(cell_voltages)
+                    else None
+                ),
             ),
             "cycle_charge": (
                 {"design_capacity", "battery_level"},
-                lambda: (design_capacity * battery_level) / 100,
+                lambda: (data.get("design_capacity", 0) * battery_level) / 100,
+            ),
+            "battery_level": (
+                {"design_capacity", "cycle_charge"},
+                lambda: round(
+                    data.get("cycle_charge", 0) / data.get("design_capacity", 0) * 100,
+                    1,
+                ),
             ),
             "cycle_capacity": (
                 {"voltage", "cycle_charge"},
-                lambda: voltage * cycle_charge,
+                lambda: round(data.get("voltage", 0) * data.get("cycle_charge", 0), 3),
+            ),
+            "power": (
+                {"voltage", "current"},
+                lambda: round(data.get("voltage", 0) * current, 3),
             ),
-            "power": ({"voltage", "current"}, lambda: round(voltage * current, 3)),
             "battery_charging": ({"current"}, lambda: current > 0),
             "runtime": (
                 {"current", "cycle_charge"},
                 lambda: (
-                    int(cycle_charge / abs(current) * BaseBMS._HRS_TO_SECS)
+                    int(
+                        data.get("cycle_charge", 0)
+                        / abs(current)
+                        * BaseBMS._HRS_TO_SECS
+                    )
                     if current < 0
                     else None
                 ),
             ),
             "temperature": (
                 {"temp_values"},
-                lambda: round(fmean(data.get("temp_values", [])), 3),
+                lambda: (
+                    round(fmean(data.get("temp_values", [])), 3)
+                    if data.get("temp_values")
+                    else None
+                ),
             ),
         }
 
         for attr, (required, calc_func) in calculations.items():
-            if can_calc(attr, frozenset(required)):
-                data[attr] = calc_func()
+            if (
+                can_calc(attr, frozenset(required))
+                and (value := calc_func()) is not None
+            ):
+                data[attr] = value
 
         # do sanity check on values to set problem state
         data["problem"] = any(
             [
                 data.get("problem", False),
                 data.get("problem_code", False),
-                voltage <= 0,
+                data.get("voltage") is not None and data.get("voltage", 0) <= 0,
                 any(v <= 0 or v > BaseBMS._MAX_CELL_VOLT for v in cell_voltages),
                 data.get("delta_voltage", 0) > BaseBMS._MAX_CELL_VOLT,
-                cycle_charge <= 0,
+                data.get("cycle_charge") is not None
+                and data.get("cycle_charge", 0.0) <= 0.0,
                 battery_level > 100,
             ]
         )
@@ -184,13 +221,15 @@ class BaseBMS(ABC):
 
         self._log.debug("disconnected from BMS")
 
-    async def _init_connection(self) -> None:
+    async def _init_connection(
+        self, char_notify: BleakGATTCharacteristic | int | str | None = None
+    ) -> None:
         # reset any stale data from BMS
         self._data.clear()
         self._data_event.clear()
 
         await self._client.start_notify(
-            self.uuid_rx(), getattr(self, "_notification_handler")
+            char_notify or self.uuid_rx(), getattr(self, "_notification_handler")
         )
 
     async def _connect(self) -> None:
@@ -200,6 +239,13 @@ class BaseBMS(ABC):
             self._log.debug("BMS already connected")
             return
 
+        try:
+            await self._client.disconnect()  # ensure no stale connection exists
+        except (BleakError, TimeoutError) as exc:
+            self._log.debug(
+                "failed to disconnect stale connection (%s)", type(exc).__name__
+            )
+
         self._log.debug("connecting BMS")
         self._client = await establish_connection(
             client_class=BleakClient,
@@ -211,37 +257,98 @@ class BaseBMS(ABC):
 
         try:
             await self._init_connection()
-        except Exception as err:
+        except Exception as exc:
             self._log.info(
-                "failed to initialize BMS connection (%s)", type(err).__name__
+                "failed to initialize BMS connection (%s)", type(exc).__name__
             )
             await self.disconnect()
             raise
 
+    def _wr_response(self, char: int | str) -> bool:
+        char_tx: Final[BleakGATTCharacteristic | None] = (
+            self._client.services.get_characteristic(char)
+        )
+        return bool(char_tx and "write" in getattr(char_tx, "properties", []))
+
+    async def _send_msg(
+        self,
+        data: bytes,
+        max_size: int,
+        char: int | str,
+        attempt: int,
+        inv_wr_mode: bool = False,
+    ) -> None:
+        """Send message to the bms in chunks if needed."""
+        chunk_size: Final[int] = max_size or len(data)
+
+        for i in range(0, len(data), chunk_size):
+            chunk: bytes = data[i : i + chunk_size]
+            self._log.debug(
+                "TX BLE req #%i (%s%s%s): %s",
+                attempt + 1,
+                "!" if inv_wr_mode else "",
+                "W" if self._wr_response(char) else "WNR",
+                "." if self._inv_wr_mode is not None else "",
+                chunk.hex(" "),
+            )
+            await self._client.write_gatt_char(
+                char,
+                chunk,
+                response=(self._wr_response(char) != inv_wr_mode),
+            )
+
     async def _await_reply(
         self,
         data: bytes,
-        char: BleakGATTCharacteristic | int | str | None = None,
+        char: int | str | None = None,
         wait_for_notify: bool = True,
+        max_size: int = 0,
     ) -> None:
         """Send data to the BMS and wait for valid reply notification."""
 
-        self._log.debug("TX BLE data: %s", data.hex(" "))
-        self._data_event.clear()  # clear event before requesting new data
-        await self._client.write_gatt_char(char or self.uuid_tx(), data, response=False)
-        if wait_for_notify:
-            await asyncio.wait_for(self._wait_event(), timeout=self.TIMEOUT)
-
-    async def disconnect(self) -> None:
+        for inv_wr_mode in (
+            [False, True] if self._inv_wr_mode is None else [self._inv_wr_mode]
+        ):
+            try:
+                self._data_event.clear()  # clear event before requesting new data
+                for attempt in range(BaseBMS.MAX_RETRY):
+                    await self._send_msg(
+                        data, max_size, char or self.uuid_tx(), attempt, inv_wr_mode
+                    )
+                    if not wait_for_notify:
+                        return  # write without wait for response selected
+                    try:
+                        await asyncio.wait_for(
+                            self._wait_event(),
+                            BaseBMS._RETRY_TIMEOUT
+                            * min(2**attempt, BaseBMS._MAX_TIMEOUT_FACTOR),
+                        )
+                    except TimeoutError:
+                        self._log.debug("TX BLE request timed out.")
+                        continue  # retry sending data
+
+                    self._inv_wr_mode = inv_wr_mode
+                    return  # leave loop if no exception
+            except BleakError as exc:
+                # reconnect on communication errors
+                self._log.warning(
+                    "TX BLE request error, retrying connection (%s)", type(exc).__name__
+                )
+                await self.disconnect()
+                await self._connect()
+        raise TimeoutError
+
+    async def disconnect(self, reset: bool = False) -> None:
         """Disconnect the BMS, includes stoping notifications."""
 
-        if self._client.is_connected:
-            self._log.debug("disconnecting BMS")
-            try:
-                self._data_event.clear()
-                await self._client.disconnect()
-            except BleakError:
-                self._log.warning("disconnect failed!")
+        self._log.debug("disconnecting BMS (%s)", str(self._client.is_connected))
+        try:
+            self._data_event.clear()
+            if reset:
+                self._inv_wr_mode = None  # reset write mode
+            await self._client.disconnect()
+        except BleakError:
+            self._log.warning("disconnect failed!")
 
     async def _wait_event(self) -> None:
         """Wait for data event and clear it."""
@@ -252,7 +359,7 @@ class BaseBMS(ABC):
     async def _async_update(self) -> BMSsample:
         """Return a dictionary of BMS values (keys need to come from the SENSOR_TYPES list)."""
 
-    async def async_update(self, raw: bool = False) -> BMSsample:
+    async def async_update(self) -> BMSsample:
         """Retrieve updated values from the BMS using method of the subclass.
 
         Args:
@@ -266,8 +373,7 @@ class BaseBMS(ABC):
         await self._connect()
 
         data: BMSsample = await self._async_update()
-        if not raw:
-            self._add_missing_values(data, self._calc_values())
+        self._add_missing_values(data, self._calc_values())
 
         if self._reconnect:
             # disconnect after data update to force reconnect next time (slow!)
@@ -275,6 +381,107 @@ class BaseBMS(ABC):
 
         return data
 
+    @staticmethod
+    def _decode_data(
+        fields: tuple[BMSdp, ...],
+        data: bytearray | dict[int, bytearray],
+        *,
+        byteorder: Literal["little", "big"] = "big",
+        offset: int = 0,
+    ) -> BMSsample:
+        result: BMSsample = {}
+        for field in fields:
+            if isinstance(data, dict) and field.idx not in data:
+                continue
+            msg: bytearray = data[field.idx] if isinstance(data, dict) else data
+            result[field.key] = field.fct(
+                int.from_bytes(
+                    msg[offset + field.pos : offset + field.pos + field.size],
+                    byteorder=byteorder,
+                    signed=field.signed,
+                )
+            )
+        return result
+
+    @staticmethod
+    def _cell_voltages(
+        data: bytearray,
+        *,
+        cells: int,
+        start: int,
+        size: int = 2,
+        byteorder: Literal["little", "big"] = "big",
+        divider: int = 1000,
+    ) -> list[float]:
+        """Return cell voltages from BMS message.
+
+        Args:
+            data: Raw data from BMS
+            cells: Number of cells to read
+            start: Start position in data array
+            size: Number of bytes per cell value (defaults 2)
+            byteorder: Byte order ("big"/"little" endian)
+            divider: Value to divide raw value by, defaults to 1000 (mv to V)
+
+        Returns:
+            list[float]: List of cell voltages in volts
+
+        """
+        return [
+            value / divider
+            for idx in range(cells)
+            if (len(data) >= start + (idx + 1) * size)
+            and (
+                value := int.from_bytes(
+                    data[start + idx * size : start + (idx + 1) * size],
+                    byteorder=byteorder,
+                    signed=False,
+                )
+            )
+        ]
+
+    @staticmethod
+    def _temp_values(
+        data: bytearray,
+        *,
+        values: int,
+        start: int,
+        size: int = 2,
+        byteorder: Literal["little", "big"] = "big",
+        signed: bool = True,
+        offset: float = 0,
+        divider: int = 1,
+    ) -> list[int | float]:
+        """Return temperature values from BMS message.
+
+        Args:
+            data: Raw data from BMS
+            values: Number of values to read
+            start: Start position in data array
+            size: Number of bytes per cell value (defaults 2)
+            byteorder: Byte order ("big"/"little" endian)
+            signed: Indicates whether two's complement is used to represent the integer.
+            offset: The offset read values are shifted by (for Kelvin use 273.15)
+            divider: Value to divide raw value by, defaults to 1000 (mv to V)
+
+        Returns:
+            list[int | float]: List of temperature values
+
+        """
+        return [
+            value / divider if divider != 1 else value
+            for idx in range(values)
+            if (len(data) >= start + (idx + 1) * size)
+            and (
+                value := int.from_bytes(
+                    data[start + idx * size : start + (idx + 1) * size],
+                    byteorder=byteorder,
+                    signed=signed,
+                )
+                - offset
+            )
+        ]
+
 
 def crc_modbus(data: bytearray) -> int:
     """Calculate CRC-16-CCITT MODBUS."""
@@ -286,6 +493,11 @@ def crc_modbus(data: bytearray) -> int:
     return crc & 0xFFFF
 
 
+def lrc_modbus(data: bytearray) -> int:
+    """Calculate MODBUS LRC."""
+    return ((sum(data) ^ 0xFFFF) + 1) & 0xFFFF
+
+
 def crc_xmodem(data: bytearray) -> int:
     """Calculate CRC-16-CCITT XMODEM."""
     crc: int = 0x0000
@@ -308,6 +520,10 @@ def crc8(data: bytearray) -> int:
     return crc & 0xFF
 
 
-def crc_sum(frame: bytearray) -> int:
-    """Calculate frame CRC."""
-    return sum(frame) & 0xFF
+def crc_sum(frame: bytearray, size: int = 1) -> int:
+    """Calculate the checksum of a frame using a specified size.
+
+    size : int, optional
+        The size of the checksum in bytes (default is 1).
+    """
+    return sum(frame) & ((1 << (8 * size)) - 1)

aiobmsble/utils.py

@@ -1,16 +1,20 @@
 """Utilitiy/Support functions for aiobmsble."""
 
 from fnmatch import translate
+from functools import lru_cache
+import importlib
+import pkgutil
 import re
+from types import ModuleType
 
 from bleak.backends.scanner import AdvertisementData
 
-from aiobmsble import AdvertisementPattern
+from aiobmsble import MatcherPattern
 from aiobmsble.basebms import BaseBMS
 
 
-def advertisement_matches(
-    matcher: AdvertisementPattern,
+def _advertisement_matches(
+    matcher: MatcherPattern,
     adv_data: AdvertisementData,
 ) -> bool:
     """Determine whether the given advertisement data matches the specified pattern.
@@ -56,18 +60,104 @@ def advertisement_matches(
     )
 
 
-def bms_supported(bms: BaseBMS, adv_data: AdvertisementData) -> bool:
+@lru_cache
+def load_bms_plugins() -> set[ModuleType]:
+    """Discover and load all available Battery Management System (BMS) plugin modules.
+
+    This function scans the 'aiobmsble/bms' directory for all Python modules,
+    dynamically imports each discovered module, and returns a set containing
+    the imported module objects required to end with "_bms".
+
+    Returns:
+        set[ModuleType]: A set of imported BMS plugin modules.
+
+    Raises:
+        ImportError: If a module cannot be imported.
+        OSError: If the plugin directory cannot be accessed.
+
+    """
+    return {
+        importlib.import_module(f"aiobmsble.bms.{module_name}")
+        for _, module_name, _ in pkgutil.iter_modules(["aiobmsble/bms"])
+        if module_name.endswith("_bms")
+    }
+
+
+def bms_cls(name: str) -> type[BaseBMS] | None:
+    """Return the BMS class that is defined by the name argument.
+
+    Args:
+        name (str): The name of the BMS type
+
+    Returns:
+        type[BaseBMS] | None: If the BMS class defined by name is found, None otherwise.
+
+    """
+    try:
+        bms_module: ModuleType = importlib.import_module(f"aiobmsble.bms.{name}_bms")
+    except ModuleNotFoundError:
+        return None
+    return bms_module.BMS
+
+
+def bms_matching(
+    adv_data: AdvertisementData, mac_addr: str | None = None
+) -> list[type[BaseBMS]]:
+    """Return the BMS classes that match the given advertisement data.
+
+    Currently the function returns at most one match, but this behaviour might change
+    in the future to multiple entries, if BMSs cannot be distinguished uniquely using
+    their Bluetooth advertisement / OUI (Organizationally Unique Identifier)
+
+    Args:
+        adv_data (AdvertisementData): The advertisement data to match against available BMS plugins.
+        mac_addr (str | None): Optional MAC address to check OUI against
+
+    Returns:
+        list[type[BaseBMS]]: A list of matching BMS class(es) if found, an empty list otherwhise.
+
+    """
+    for bms_module in load_bms_plugins():
+        if bms_supported(bms_module.BMS, adv_data, mac_addr):
+            return [bms_module.BMS]
+    return []
+
+
+def bms_identify(
+    adv_data: AdvertisementData, mac_addr: str | None = None
+) -> type[BaseBMS] | None:
+    """Return the BMS classes that best matches the given advertisement data.
+
+    Args:
+        adv_data (AdvertisementData): The advertisement data to match against available BMS plugins.
+        mac_addr (str | None): Optional MAC address to check OUI against
+
+    Returns:
+        type[BaseBMS] | None: The identified BMS class if a match is found, None otherwhise
+
+    """
+
+    matching_bms: list[type[BaseBMS]] = bms_matching(adv_data, mac_addr)
+    return matching_bms[0] if matching_bms else None
+
+
+def bms_supported(
+    bms: BaseBMS, adv_data: AdvertisementData, mac_addr: str | None = None
+) -> bool:
     """Determine if the given BMS is supported based on advertisement data.
 
     Args:
         bms (BaseBMS): The BMS class to check.
         adv_data (AdvertisementData): The advertisement data to match against.
+        mac_addr (str | None): Optional MAC address to check OUI against
 
     Returns:
         bool: True if the BMS is supported, False otherwise.
 
     """
+    if mac_addr:
+        raise NotImplementedError  # pragma: no cover
     for matcher in bms.matcher_dict_list():
-        if advertisement_matches(matcher, adv_data):
+        if _advertisement_matches(matcher, adv_data):
             return True
     return False

{aiobmsble-0.1.0.dist-info → aiobmsble-0.2.0.dist-info}/METADATA

@@ -1,12 +1,14 @@
 Metadata-Version: 2.4
 Name: aiobmsble
-Version: 0.1.0
+Version: 0.2.0
 Summary: Asynchronous Python library to query battery management systems via Bluetooth Low Energy.
 Author: Patrick Loschmidt
 Maintainer: Patrick Loschmidt
 License-Expression: Apache-2.0
 Project-URL: Homepage, https://github.com/patman15/aiobmsble/
-Project-URL: Documentation, https://github.com/patman15/aiobmsble/
+Project-URL: Documentation, https://github.com/patman15/aiobmsble/README
+Project-URL: Source Code, https://github.com/patman15/aiobmsble/
+Project-URL: Bug Reports, https://github.com/patman15/aiobmsble/issues
 Keywords: BMS,BLE,battery,bluetooth
 Classifier: Programming Language :: Python :: 3
 Classifier: Operating System :: OS Independent
@@ -16,8 +18,8 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: bleak~=0.22.3
-Requires-Dist: bleak-retry-connector~=3.8.1
+Requires-Dist: bleak~=1.1.0
+Requires-Dist: bleak-retry-connector~=4.0.1
 Requires-Dist: asyncio
 Requires-Dist: logging
 Requires-Dist: statistics
@@ -26,6 +28,7 @@ Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-asyncio; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: pytest-xdist; extra == "dev"
 Requires-Dist: mypy; extra == "dev"
 Requires-Dist: ruff; extra == "dev"
 Dynamic: license-file
@@ -35,9 +38,8 @@ Dynamic: license-file
 # Aiobmsble
 Requires Python 3 and uses [asyncio](https://pypi.org/project/asyncio/) and [bleak](https://pypi.org/project/bleak/)
 > [!IMPORTANT]
-> At the moment the library is under development and not all BMS classes have been ported over from the [BMS_BLE-HA integration](https://github.com/patman15/BMS_BLE-HA/)!
+> At the moment the library is under development and there might be missing functionality compared to the [BMS_BLE-HA integration](https://github.com/patman15/BMS_BLE-HA/)!
 > Please do not (yet) report missing BMS support or bugs here. Instead please raise an issue at the integration till the library reached at least development status *beta*.
-> Plan is to support all BMSs that are listed [here](https://github.com/patman15/BMS_BLE-HA/edit/main/README.md#supported-devices).
 
 ## Asynchronous Library to Query Battery Management Systems via Bluetooth LE
 This library is intended to query data from battery management systems that use Bluetooth LE. It is developed to support [BMS_BLE-HA integration](https://github.com/patman15/BMS_BLE-HA/) that was written to make BMS data available to Home Assistant. While the integration depends on Home Assistant, this library can be used stand-alone in any Python environment (with necessary dependencies installed).
@@ -55,6 +57,7 @@ This example can also be found as an [example](/examples/minimal.py) in the resp
 """Example of using the aiobmsble library to find a BLE device by name and print its senosr data."""
 
 import asyncio
+import logging
 from typing import Final
 
 from bleak import BleakScanner
@@ -62,30 +65,35 @@ from bleak.backends.device import BLEDevice
 from bleak.exc import BleakError
 
 from aiobmsble import BMSsample
-from aiobmsble.bms.ogt_bms import BMS  # use the right BMS class for your device
+from aiobmsble.bms.dummy_bms import BMS  # use the right BMS class for your device
 
 NAME: Final[str] = "BT Device Name"  # Replace with the name of your BLE device
 
+# Configure logging
+logging.basicConfig(level=logging.INFO)
+logger: logging.Logger = logging.getLogger(__name__)
+
 
 async def main(dev_name) -> None:
-    """Main function to find a BLE device by name and update its sensor data."""
+    """Find a BLE device by name and update its sensor data."""
 
     device: BLEDevice | None = await BleakScanner.find_device_by_name(dev_name)
     if device is None:
-        print(f"Device '{dev_name}' not found.")
+        logger.error("Device '%s' not found.", dev_name)
         return
 
-    print(f"Found device: {device.name} ({device.address})")
+    logger.info("Found device: %s (%s)", device.name, device.address)
     bms = BMS(ble_device=device, reconnect=True)
     try:
-        print("Updating BMS data...")
+        logger.info("Updating BMS data...")
         data: BMSsample = await bms.async_update()
-        print("BMS data: ", repr(data).replace(", ", ",\n\t"))
+        logger.info("BMS data: %s", repr(data).replace(", ", ",\n\t"))
     except BleakError as ex:
-        print(f"Failed to update BMS: {ex}")
+        logger.error("Failed to update BMS: %s", type(ex).__name__)
 
 
-asyncio.run(main(NAME))
+if __name__ == "__main__":
+    asyncio.run(main(NAME))  # pragma: no cover
 ```
 
 ## Installation

aiobmsble-0.2.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+aiobmsble/__init__.py,sha256=gwWO0ojesAR4aYsu5P4LZYlaQgkJpMkzg4Q27V3VOrg,2932
+aiobmsble/__main__.py,sha256=7h8ZnUlQ67IMjnRMJJt091ndGIrYuvd5i12OEMxy2j0,3000
+aiobmsble/basebms.py,sha256=bNik9TsHTlAqAR-RPxFFXy6qD1E7l7f53u8wffMgQyU,18556
+aiobmsble/utils.py,sha256=9DQT4y7VGlSgCEjfTyu3fqKxOBu97cT9V8y8Ce1MTgA,5524
+aiobmsble-0.2.0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+aiobmsble-0.2.0.dist-info/METADATA,sha256=6_PNHNaXNX5GuU_HXB-PWZdrJB5fgKzMoWbYBt0Cj1w,4669
+aiobmsble-0.2.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+aiobmsble-0.2.0.dist-info/entry_points.txt,sha256=HSC_C3nQikc3nk0a6mcG92RuIM7wAzozjBVfDojJceo,54
+aiobmsble-0.2.0.dist-info/top_level.txt,sha256=YHBVzg45mJ3vPz0sl_TpMB0edMqqhD61kwJj4EPAk9g,10
+aiobmsble-0.2.0.dist-info/RECORD,,

{aiobmsble-0.1.0.dist-info → aiobmsble-0.2.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.4.0)
+Generator: setuptools (80.9.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

aiobmsble-0.1.0.dist-info/RECORD

@@ -1,10 +0,0 @@
-aiobmsble/__init__.py,sha256=qEmiX9i7aKK7lYl7zrTgNFblb3-WJYTG22tTmAO_uC4,1541
-aiobmsble/__main__.py,sha256=ycvwDkcph4M1UzsBGJzkQWkLS6CW5sPfEG9QK-Q691I,2102
-aiobmsble/basebms.py,sha256=ZHG34fmDQ5wz58GpS7yI09ICdot7iyvdhPg6zt9U6vw,10699
-aiobmsble/utils.py,sha256=BGcwcfOpS5KW942J7uHRrBkmh9rdMW64OvDRyHIP9lQ,2535
-aiobmsble-0.1.0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-aiobmsble-0.1.0.dist-info/METADATA,sha256=THqATDPH5bBlgIb363ZpqCkOh5S4FPYkQSPnPDW4xdE,4395
-aiobmsble-0.1.0.dist-info/WHEEL,sha256=DnLRTWE75wApRYVsjgc6wsVswC54sMSJhAEd4xhDpBk,91
-aiobmsble-0.1.0.dist-info/entry_points.txt,sha256=HSC_C3nQikc3nk0a6mcG92RuIM7wAzozjBVfDojJceo,54
-aiobmsble-0.1.0.dist-info/top_level.txt,sha256=YHBVzg45mJ3vPz0sl_TpMB0edMqqhD61kwJj4EPAk9g,10
-aiobmsble-0.1.0.dist-info/RECORD,,