aiobmsble 0.1.0__tar.gz → 0.2.1__tar.gz

{aiobmsble-0.1.0/aiobmsble.egg-info → aiobmsble-0.2.1}/PKG-INFO

@@ -1,12 +1,14 @@
 Metadata-Version: 2.4
 Name: aiobmsble
-Version: 0.1.0
+Version: 0.2.1
 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.2
 Requires-Dist: asyncio
 Requires-Dist: logging
 Requires-Dist: statistics
@@ -26,6 +28,8 @@ 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: hypothesis; extra == "dev"
 Requires-Dist: mypy; extra == "dev"
 Requires-Dist: ruff; extra == "dev"
 Dynamic: license-file
@@ -35,9 +39,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 +58,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 +66,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.1.0 → aiobmsble-0.2.1}/README.md

@@ -3,9 +3,8 @@
 # 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).
@@ -23,6 +22,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
@@ -30,30 +30,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.1/aiobmsble/__init__.py

@@ -0,0 +1,99 @@
+"""Package for battery management systems (BMS) via Bluetooth LE."""
+
+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",
+    "temperature",
+    "voltage",
+    "cycles",
+    "cycle_capacity",
+    "cycle_charge",
+    "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  # True: battery charging
+    battery_mode: BMSmode  # BMS charging mode
+    battery_level: int | float  # [%]
+    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  # True: problem detected
+    runtime: int  # [s]
+    # 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  # 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 MatcherPattern(TypedDict, total=False):
+    """Optional patterns that can match Bleak advertisement data."""
+
+    local_name: str  # name pattern that supports Unix shell-style wildcards
+    service_uuid: str  # 128-bit UUID that the device must advertise
+    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-0.2.1/aiobmsble/__main__.py

@@ -0,0 +1,93 @@
+"""Example function for package usage."""
+
+import argparse
+import asyncio
+import logging
+from typing import Final
+
+from bleak import BleakScanner
+from bleak.backends.device import BLEDevice
+from bleak.backends.scanner import AdvertisementData
+from bleak.exc import BleakError
+
+from aiobmsble import BMSsample
+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(__package__)
+
+
+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",
+            "-" * 72,
+            ble_dev.name,
+            ble_dev.address,
+            repr(advertisement).replace(", ", ",\n\t"),
+        )
+
+        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()  # pragma: no cover