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

aiobmsble/__init__.py

@@ -1,4 +1,8 @@
-"""Package for battery management systems (BMS) via Bluetooth LE."""
+"""Package for battery management systems (BMS) via Bluetooth LE (aiobmsble).
+
+Project: aiobmsble, https://pypi.org/p/aiobmsble/
+License: Apache-2.0, http://www.apache.org/licenses/
+"""
 
 from collections.abc import Callable
 from enum import IntEnum

aiobmsble/__main__.py

@@ -1,4 +1,8 @@
-"""Example function for package usage."""
+"""Example script for aiobmsble package usage.
+
+Project: aiobmsble, https://pypi.org/p/aiobmsble/
+License: Apache-2.0, http://www.apache.org/licenses/
+"""
 
 import argparse
 import asyncio

aiobmsble/basebms.py

@@ -1,4 +1,8 @@
-"""Base class defintion for battery management systems (BMS)."""
+"""Base class defintion for battery management systems (BMS).
+
+Project: aiobmsble, https://pypi.org/p/aiobmsble/
+License: Apache-2.0, http://www.apache.org/licenses/
+"""
 
 from abc import ABC, abstractmethod
 import asyncio
@@ -79,6 +83,11 @@ class BaseBMS(ABC):
         self._data: bytearray = bytearray()
         self._data_event: Final[asyncio.Event] = asyncio.Event()
 
+    @classmethod
+    def get_bms_module(cls) -> str:
+        """Return BMS module name, e.g. aiobmsble.bms.dummy_bms."""
+        return cls.__module__
+
     @staticmethod
     @abstractmethod
     def matcher_dict_list() -> list[MatcherPattern]:

aiobmsble/bms/__init__.py

@@ -0,0 +1,5 @@
+"""Package for battery management systems (BMS) plugins.
+
+Project: aiobmsble, https://pypi.org/p/aiobmsble/
+License: Apache-2.0, http://www.apache.org/licenses/
+"""

aiobmsble/bms/abc_bms.py

@@ -0,0 +1,168 @@
+"""Module to support ABC BMS.
+
+Project: aiobmsble, https://pypi.org/p/aiobmsble/
+License: Apache-2.0, http://www.apache.org/licenses/
+"""
+
+import contextlib
+from typing import Final
+
+from bleak.backends.characteristic import BleakGATTCharacteristic
+from bleak.backends.device import BLEDevice
+from bleak.uuids import normalize_uuid_str
+
+from aiobmsble import BMSdp, BMSsample, BMSvalue, MatcherPattern
+from aiobmsble.basebms import BaseBMS, crc8
+
+
+class BMS(BaseBMS):
+    """ABC BMS implementation."""
+
+    _HEAD_CMD: Final[int] = 0xEE
+    _HEAD_RESP: Final[bytes] = b"\xcc"
+    _INFO_LEN: Final[int] = 0x14
+    _EXP_REPLY: Final[dict[int, set[int]]] = {  # wait for these replies
+        0xC0: {0xF1},
+        0xC1: {0xF0, 0xF2},
+        0xC2: {0xF0, 0xF3, 0xF4},  # 4 cells per F4 message
+        0xC3: {0xF5, 0xF6, 0xF7, 0xF8, 0xFA},
+        0xC4: {0xF9},
+    }
+    _FIELDS: Final[tuple[BMSdp, ...]] = (
+        BMSdp("temp_sensors", 4, 1, False, lambda x: x, 0xF2),
+        BMSdp("voltage", 2, 3, False, lambda x: x / 1000, 0xF0),
+        BMSdp("current", 5, 3, True, lambda x: x / 1000, 0xF0),
+        # ("design_capacity", 8, 3, False, lambda x: x / 1000, 0xF0),
+        BMSdp("battery_level", 16, 1, False, lambda x: x, 0xF0),
+        BMSdp("cycle_charge", 11, 3, False, lambda x: x / 1000, 0xF0),
+        BMSdp("cycles", 14, 2, False, lambda x: x, 0xF0),
+        BMSdp(  # only first bit per byte is used
+            "problem_code",
+            2,
+            16,
+            False,
+            lambda x: sum(((x >> (i * 8)) & 1) << i for i in range(16)),
+            0xF9,
+        ),
+    )
+    _RESPS: Final[set[int]] = {field.idx for field in _FIELDS} | {0xF4}  # cell voltages
+
+    def __init__(self, ble_device: BLEDevice, reconnect: bool = False) -> None:
+        """Initialize BMS."""
+        super().__init__(ble_device, reconnect)
+        self._data_final: dict[int, bytearray] = {}
+        self._exp_reply: set[int] = set()
+
+    @staticmethod
+    def matcher_dict_list() -> list[MatcherPattern]:
+        """Provide BluetoothMatcher definition."""
+        return [
+            {
+                "local_name": pattern,
+                "service_uuid": normalize_uuid_str("fff0"),
+                "connectable": True,
+            }
+            for pattern in ("ABC-*", "SOK-*")  # "NB-*", "Hoover",
+        ]
+
+    @staticmethod
+    def device_info() -> dict[str, str]:
+        """Return device information for the battery management system."""
+        return {"manufacturer": "Chunguang Song", "model": "ABC BMS"}
+
+    @staticmethod
+    def uuid_services() -> list[str]:
+        """Return list of 128-bit UUIDs of services required by BMS."""
+        return [normalize_uuid_str("ffe0")]
+
+    @staticmethod
+    def uuid_rx() -> str:
+        """Return 16-bit UUID of characteristic that provides notification/read property."""
+        return "ffe1"
+
+    @staticmethod
+    def uuid_tx() -> str:
+        """Return 16-bit UUID of characteristic that provides write property."""
+        return "ffe2"
+
+    @staticmethod
+    def _calc_values() -> frozenset[BMSvalue]:
+        return frozenset(
+            {
+                "battery_charging",
+                "cycle_capacity",
+                "delta_voltage",
+                "power",
+                "runtime",
+                "temperature",
+            }
+        )  # calculate further values from BMS provided set ones
+
+    def _notification_handler(
+        self, _sender: BleakGATTCharacteristic, data: bytearray
+    ) -> None:
+        """Handle the RX characteristics notify event (new data arrives)."""
+        self._log.debug("RX BLE data: %s", data)
+
+        if not data.startswith(BMS._HEAD_RESP):
+            self._log.debug("Incorrect frame start")
+            return
+
+        if len(data) != BMS._INFO_LEN:
+            self._log.debug("Incorrect frame length")
+            return
+
+        if (crc := crc8(data[:-1])) != data[-1]:
+            self._log.debug("invalid checksum 0x%X != 0x%X", data[-1], crc)
+            return
+
+        if data[1] == 0xF4 and 0xF4 in self._data_final:
+            # expand cell voltage frame with all parts
+            self._data_final[0xF4] = bytearray(self._data_final[0xF4][:-2] + data[2:])
+        else:
+            self._data_final[data[1]] = data.copy()
+
+        self._exp_reply.discard(data[1])
+
+        if not self._exp_reply:  # check if all expected replies are received
+            self._data_event.set()
+
+    @staticmethod
+    def _cmd(cmd: bytes) -> bytes:
+        """Assemble a ABC BMS command."""
+        frame = bytearray([BMS._HEAD_CMD, cmd[0], 0x00, 0x00, 0x00])
+        frame.append(crc8(frame))
+        return bytes(frame)
+
+    async def _async_update(self) -> BMSsample:
+        """Update battery status information."""
+        self._data_final.clear()
+        for cmd in (0xC1, 0xC2, 0xC4):
+            self._exp_reply.update(BMS._EXP_REPLY[cmd])
+            with contextlib.suppress(TimeoutError):
+                await self._await_reply(BMS._cmd(bytes([cmd])))
+
+        # check all repsonses are here, 0xF9 is not mandatory (not all BMS report it)
+        self._data_final.setdefault(0xF9, bytearray())
+        if not BMS._RESPS.issubset(set(self._data_final.keys())):
+            self._log.debug("Incomplete data set %s", self._data_final.keys())
+            raise TimeoutError("BMS data incomplete.")
+
+        result: BMSsample = BMS._decode_data(
+            BMS._FIELDS, self._data_final, byteorder="little"
+        )
+        return result | {
+            "cell_voltages": BMS._cell_voltages(  # every second value is the cell idx
+                self._data_final[0xF4],
+                cells=(len(self._data_final[0xF4]) - 4) // 2,
+                start=3,
+                byteorder="little",
+                size=2,
+            )[::2],
+            "temp_values": BMS._temp_values(
+                self._data_final[0xF2],
+                start=5,
+                values=result.get("temp_sensors", 0),
+                byteorder="little",
+            ),
+        }

aiobmsble/bms/ant_bms.py

@@ -0,0 +1,200 @@
+"""Module to support ANT BMS.
+
+Project: aiobmsble, https://pypi.org/p/aiobmsble/
+License: Apache-2.0, http://www.apache.org/licenses/
+"""
+
+from typing import Final
+
+from bleak.backends.characteristic import BleakGATTCharacteristic
+from bleak.backends.device import BLEDevice
+from bleak.uuids import normalize_uuid_str
+
+from aiobmsble import BMSdp, BMSsample, BMSvalue, MatcherPattern
+from aiobmsble.basebms import BaseBMS, crc_modbus
+
+
+class BMS(BaseBMS):
+    """ANT BMS implementation."""
+
+    _HEAD: Final[bytes] = b"\x7e\xa1"
+    _TAIL: Final[bytes] = b"\xaa\x55"
+    _MIN_LEN: Final[int] = 10  # frame length without data
+    _CMD_STAT: Final[int] = 0x01
+    _CMD_DEV: Final[int] = 0x02
+    _TEMP_POS: Final[int] = 8
+    _MAX_TEMPS: Final[int] = 6
+    _CELL_COUNT: Final[int] = 9
+    _CELL_POS: Final[int] = 34
+    _MAX_CELLS: Final[int] = 32
+    _FIELDS: Final[tuple[BMSdp, ...]] = (
+        BMSdp("voltage", 38, 2, False, lambda x: x / 100),
+        BMSdp("current", 40, 2, True, lambda x: x / 10),
+        BMSdp("design_capacity", 50, 4, False, lambda x: x // 1e6),
+        BMSdp("battery_level", 42, 2, False, lambda x: x),
+        BMSdp(
+            "problem_code",
+            46,
+            2,
+            False,
+            lambda x: ((x & 0xF00) if (x >> 8) not in (0x1, 0x4, 0xB, 0xF) else 0)
+            | ((x & 0xF) if (x & 0xF) not in (0x1, 0x4, 0xB, 0xC, 0xF) else 0),
+        ),
+        BMSdp("cycle_charge", 54, 4, False, lambda x: x / 1e6),
+        BMSdp("delta_voltage", 82, 2, False, lambda x: x / 1000),
+        BMSdp("power", 62, 4, True, lambda x: x / 1),
+    )
+
+    def __init__(self, ble_device: BLEDevice, reconnect: bool = False) -> None:
+        """Initialize BMS."""
+        super().__init__(ble_device, reconnect)
+        self._data_final: bytearray = bytearray()
+        self._valid_reply: int = BMS._CMD_STAT | 0x10  # valid reply mask
+        self._exp_len: int = BMS._MIN_LEN
+
+    @staticmethod
+    def matcher_dict_list() -> list[MatcherPattern]:
+        """Provide BluetoothMatcher definition."""
+        return [
+            {
+                "local_name": "ANT-BLE*",
+                "service_uuid": BMS.uuid_services()[0],
+                "manufacturer_id": 0x2313,
+                "connectable": True,
+            }
+        ]
+
+    @staticmethod
+    def device_info() -> dict[str, str]:
+        """Return device information for the battery management system."""
+        return {"manufacturer": "ANT", "model": "Smart BMS"}
+
+    @staticmethod
+    def uuid_services() -> list[str]:
+        """Return list of 128-bit UUIDs of services required by BMS."""
+        return [normalize_uuid_str("ffe0")]  # change service UUID here!
+
+    @staticmethod
+    def uuid_rx() -> str:
+        """Return 16-bit UUID of characteristic that provides notification/read property."""
+        return "ffe1"
+
+    @staticmethod
+    def uuid_tx() -> str:
+        """Return 16-bit UUID of characteristic that provides write property."""
+        return "ffe1"
+
+    @staticmethod
+    def _calc_values() -> frozenset[BMSvalue]:
+        return frozenset(
+            {"cycle_capacity", "temperature"}
+        )  # calculate further values from BMS provided set ones
+
+    async def _init_connection(
+        self, char_notify: BleakGATTCharacteristic | int | str | None = None
+    ) -> None:
+        """Initialize RX/TX characteristics and protocol state."""
+        await super()._init_connection(char_notify)
+        self._exp_len = BMS._MIN_LEN
+        self._valid_reply = BMS._CMD_DEV | 0x10
+        await self._await_reply(BMS._cmd(BMS._CMD_DEV, 0x026C, 0x20))  # TODO: parse
+        self._valid_reply = BMS._CMD_STAT | 0x10
+
+    def _notification_handler(
+        self, _sender: BleakGATTCharacteristic, data: bytearray
+    ) -> None:
+        """Handle the RX characteristics notify event (new data arrives)."""
+
+        if (
+            data.startswith(BMS._HEAD)
+            and len(self._data) >= self._exp_len
+            and len(data) >= BMS._MIN_LEN
+        ):
+            self._data = bytearray()
+            self._exp_len = data[5] + BMS._MIN_LEN
+
+        self._data += data
+        self._log.debug(
+            "RX BLE data (%s): %s", "start" if data == self._data else "cnt.", data
+        )
+
+        if len(self._data) < self._exp_len:
+            return
+
+        if self._data[2] != self._valid_reply:
+            self._log.debug("unexpected response (type 0x%X)", self._data[2])
+            return
+
+        if len(self._data) != self._exp_len and self._data[2] != BMS._CMD_DEV | 0x10:
+            # length of CMD_DEV is incorrect, so we ignore the length check here
+            self._log.debug(
+                "invalid frame length %d != %d", len(self._data), self._exp_len
+            )
+            return
+
+        if not self._data.endswith(BMS._TAIL):
+            self._log.debug("invalid frame end")
+            return
+
+        if (crc := crc_modbus(self._data[1 : self._exp_len - 4])) != int.from_bytes(
+            self._data[self._exp_len - 4 : self._exp_len - 2], "little"
+        ):
+            self._log.debug(
+                "invalid checksum 0x%X != 0x%X",
+                int.from_bytes(
+                    self._data[self._exp_len - 4 : self._exp_len - 2], "little"
+                ),
+                crc,
+            )
+            return
+
+        self._data_final = self._data.copy()
+        self._data_event.set()
+
+    @staticmethod
+    def _cmd(cmd: int, adr: int, value: int) -> bytes:
+        """Assemble a ANT BMS command."""
+        frame: bytearray = (
+            bytearray([*BMS._HEAD, cmd & 0xFF])
+            + adr.to_bytes(2, "little")
+            + int.to_bytes(value & 0xFF, 1)
+        )
+        frame.extend(int.to_bytes(crc_modbus(frame[1:]), 2, "little"))
+        return bytes(frame) + BMS._TAIL
+
+    @staticmethod
+    def _temp_sensors(data: bytearray, sensors: int, offs: int) -> list[float]:
+        return [
+            float(int.from_bytes(data[idx : idx + 2], byteorder="little", signed=True))
+            for idx in range(offs, offs + sensors * 2, 2)
+        ]
+
+    async def _async_update(self) -> BMSsample:
+        """Update battery status information."""
+        await self._await_reply(BMS._cmd(BMS._CMD_STAT, 0, 0xBE))
+
+        result: BMSsample = {}
+        result["battery_charging"] = self._data_final[7] == 0x2
+        result["cell_count"] = min(self._data_final[BMS._CELL_COUNT], BMS._MAX_CELLS)
+        result["cell_voltages"] = BMS._cell_voltages(
+            self._data_final,
+            cells=result["cell_count"],
+            start=BMS._CELL_POS,
+            byteorder="little",
+        )
+        result["temp_sensors"] = min(self._data_final[BMS._TEMP_POS], BMS._MAX_TEMPS)
+        result["temp_values"] = BMS._temp_sensors(
+            self._data_final,
+            result["temp_sensors"] + 2,  # + MOSFET, balancer temperature
+            BMS._CELL_POS + result["cell_count"] * 2,
+        )
+        result.update(
+            BMS._decode_data(
+                BMS._FIELDS,
+                self._data_final,
+                byteorder="little",
+                offset=(result["temp_sensors"] + result["cell_count"]) * 2,
+            )
+        )
+
+        return result

aiobmsble/bms/braunpwr_bms.py

@@ -0,0 +1,171 @@
+"""Module to support Braun Power BMS.
+
+Project: aiobmsble, https://pypi.org/p/aiobmsble/
+License: Apache-2.0, http://www.apache.org/licenses/
+"""
+
+from typing import Final
+
+from bleak.backends.characteristic import BleakGATTCharacteristic
+from bleak.backends.device import BLEDevice
+from bleak.uuids import normalize_uuid_str
+
+from aiobmsble import BMSdp, BMSsample, BMSvalue, MatcherPattern
+from aiobmsble.basebms import BaseBMS
+
+
+class BMS(BaseBMS):
+    """Braun Power BMS class implementation."""
+
+    _HEAD: Final[bytes] = b"\x7b"  # header for responses
+    _TAIL: Final[int] = 0x7D  # tail for command
+    _MIN_LEN: Final[int] = 4  # minimum frame size
+    _FIELDS: Final[tuple[BMSdp, ...]] = (
+        BMSdp("cell_count", 3, 1, False, lambda x: x, 0x2),
+        BMSdp("temp_sensors", 3, 1, False, lambda x: x, 0x3),
+        BMSdp("voltage", 5, 2, False, lambda x: x / 100, 0x1),
+        BMSdp("current", 13, 2, True, lambda x: x / 100, 0x1),
+        BMSdp("battery_level", 4, 1, False, lambda x: x, 0x1),
+        BMSdp("cycle_charge", 15, 2, False, lambda x: x / 100, 0x1),
+        BMSdp("design_capacity", 17, 2, False, lambda x: x // 100, 0x1),
+        BMSdp("cycles", 23, 2, False, lambda x: x, 0x1),
+        BMSdp("problem_code", 31, 2, False, lambda x: x, 0x1),
+    )
+    _CMDS: Final[set[int]] = {field.idx for field in _FIELDS}
+    _INIT_CMDS: Final[set[int]] = {
+        0x74,  # SW version
+        0xF4,  # BMS program version
+        0xF5,  # BMS boot version
+    }
+
+    def __init__(self, ble_device: BLEDevice, reconnect: bool = False) -> None:
+        """Intialize private BMS members."""
+        super().__init__(ble_device, reconnect)
+        self._data_final: dict[int, bytearray] = {}
+        self._exp_reply: tuple[int] = (0x01,)
+
+    @staticmethod
+    def matcher_dict_list() -> list[MatcherPattern]:
+        """Provide BluetoothMatcher definition."""
+        return [
+            MatcherPattern(
+                local_name=pattern,
+                service_uuid=BMS.uuid_services()[0],
+                manufacturer_id=0x7B,
+                connectable=True,
+            )
+            for pattern in ("HSKS-*", "BL-*")
+        ]
+
+    @staticmethod
+    def device_info() -> dict[str, str]:
+        """Return device information for the battery management system."""
+        return {"manufacturer": "Braun Power", "model": "Smart BMS"}
+
+    @staticmethod
+    def uuid_services() -> list[str]:
+        """Return list of 128-bit UUIDs of services required by BMS."""
+        return [normalize_uuid_str("ff00")]
+
+    @staticmethod
+    def uuid_rx() -> str:
+        """Return 16-bit UUID of characteristic that provides notification/read property."""
+        return "ff01"
+
+    @staticmethod
+    def uuid_tx() -> str:
+        """Return 16-bit UUID of characteristic that provides write property."""
+        return "ff02"
+
+    @staticmethod
+    def _calc_values() -> frozenset[BMSvalue]:
+        return frozenset(
+            {
+                "power",
+                "battery_charging",
+                "cycle_capacity",
+                "runtime",
+                "delta_voltage",
+                "temperature",
+            }
+        )
+
+    def _notification_handler(
+        self, _sender: BleakGATTCharacteristic, data: bytearray
+    ) -> None:
+        # check if answer is a heading of valid response type
+        if (
+            data.startswith(BMS._HEAD)
+            and len(self._data) >= BMS._MIN_LEN
+            and data[1] in {*BMS._CMDS, *BMS._INIT_CMDS}
+            and len(self._data) >= BMS._MIN_LEN + self._data[2]
+        ):
+            self._data = bytearray()
+
+        self._data += data
+        self._log.debug(
+            "RX BLE data (%s): %s", "start" if data == self._data else "cnt.", data
+        )
+
+        # verify that data is long enough
+        if (
+            len(self._data) < BMS._MIN_LEN
+            or len(self._data) < BMS._MIN_LEN + self._data[2]
+        ):
+            return
+
+        # check correct frame ending
+        if self._data[-1] != BMS._TAIL:
+            self._log.debug("incorrect frame end (length: %i).", len(self._data))
+            self._data.clear()
+            return
+
+        if self._data[1] not in self._exp_reply:
+            self._log.debug("unexpected command 0x%02X", self._data[1])
+            self._data.clear()
+            return
+
+        # check if response length matches expected length
+        if len(self._data) != BMS._MIN_LEN + self._data[2]:
+            self._log.debug("wrong data length (%i): %s", len(self._data), self._data)
+            self._data.clear()
+            return
+
+        self._data_final[self._data[1]] = self._data
+        self._data_event.set()
+
+    @staticmethod
+    def _cmd(cmd: int, data: bytes = b"") -> bytes:
+        """Assemble a Braun Power BMS command."""
+        assert len(data) <= 255, "data length must be a single byte."
+        return bytes([*BMS._HEAD, cmd, len(data), *data, BMS._TAIL])
+
+    async def _init_connection(
+        self, char_notify: BleakGATTCharacteristic | int | str | None = None
+    ) -> None:
+        """Connect to the BMS and setup notification if not connected."""
+        await super()._init_connection()
+        for cmd in BMS._INIT_CMDS:
+            self._exp_reply = (cmd,)
+            await self._await_reply(BMS._cmd(cmd))
+
+    async def _async_update(self) -> BMSsample:
+        """Update battery status information."""
+        self._data_final.clear()
+        for cmd in BMS._CMDS:
+            self._exp_reply = (cmd,)
+            await self._await_reply(BMS._cmd(cmd))
+
+        data: BMSsample = BMS._decode_data(BMS._FIELDS, self._data_final)
+        data["cell_voltages"] = BMS._cell_voltages(
+            self._data_final[0x2], cells=data.get("cell_count", 0), start=4
+        )
+        data["temp_values"] = BMS._temp_values(
+            self._data_final[0x3],
+            values=data.get("temp_sensors", 0),
+            start=4,
+            offset=2731,
+            divider=10,
+        )
+
+        return data