aiobmsble 0.1.0__py3-none-any.whl → 0.2.1__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