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

aiobmsble/bms/dpwrcore_bms.py

@@ -0,0 +1,211 @@
+"""Module to support D-powercore Smart BMS.
+
+Project: aiobmsble, https://pypi.org/p/aiobmsble/
+License: Apache-2.0, http://www.apache.org/licenses/
+"""
+
+from enum import IntEnum
+from string import hexdigits
+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 Cmd(IntEnum):
+    """BMS operation codes."""
+
+    UNLOCKACC = 0x32
+    UNLOCKREJ = 0x33
+    LEGINFO1 = 0x60
+    LEGINFO2 = 0x61
+    CELLVOLT = 0x62
+    UNLOCK = 0x64
+    UNLOCKED = 0x65
+    GETINFO = 0xA0
+
+
+class BMS(BaseBMS):
+    """D-powercore Smart BMS class implementation."""
+
+    _PAGE_LEN: Final[int] = 20
+    _MAX_CELLS: Final[int] = 32
+    _FIELDS: Final[tuple[BMSdp, ...]] = (
+        BMSdp("voltage", 6, 2, False, lambda x: x / 10, Cmd.LEGINFO1),
+        BMSdp("current", 8, 2, True, lambda x: x, Cmd.LEGINFO1),
+        BMSdp("battery_level", 14, 1, False, lambda x: x, Cmd.LEGINFO1),
+        BMSdp("cycle_charge", 12, 2, False, lambda x: x / 1000, Cmd.LEGINFO1),
+        BMSdp(
+            "temperature",
+            12,
+            2,
+            False,
+            lambda x: round(x * 0.1 - 273.15, 1),
+            Cmd.LEGINFO2,
+        ),
+        BMSdp(
+            "cell_count", 6, 1, False, lambda x: min(x, BMS._MAX_CELLS), Cmd.CELLVOLT
+        ),
+        BMSdp("cycles", 8, 2, False, lambda x: x, Cmd.LEGINFO2),
+        BMSdp("problem_code", 15, 1, False, lambda x: x & 0xFF, Cmd.LEGINFO1),
+    )
+    _CMDS: Final[set[Cmd]] = {Cmd(field.idx) for field in _FIELDS}
+
+    def __init__(self, ble_device: BLEDevice, reconnect: bool = False) -> None:
+        """Intialize private BMS members."""
+        super().__init__(ble_device, reconnect)
+        assert self._ble_device.name is not None  # required for unlock
+        self._data_final: dict[int, bytearray] = {}
+
+    @staticmethod
+    def matcher_dict_list() -> list[MatcherPattern]:
+        """Provide BluetoothMatcher definition."""
+        return [
+            {
+                "local_name": pattern,
+                "service_uuid": BMS.uuid_services()[0],
+                "connectable": True,
+            }
+            for pattern in ("DXB-*", "TBA-*")
+        ]
+
+    @staticmethod
+    def device_info() -> dict[str, str]:
+        """Return device information for the battery management system."""
+        return {"manufacturer": "D-powercore", "model": "Smart BMS"}
+
+    @staticmethod
+    def uuid_services() -> list[str]:
+        """Return list of 128-bit UUIDs of services required by BMS."""
+        return [normalize_uuid_str("fff0")]
+
+    @staticmethod
+    def uuid_rx() -> str:
+        """Return 16-bit UUID of characteristic that provides notification/read property."""
+        return "fff4"
+
+    @staticmethod
+    def uuid_tx() -> str:
+        """Return 16-bit UUID of characteristic that provides write property."""
+        return "fff3"
+
+    @staticmethod
+    def _calc_values() -> frozenset[BMSvalue]:
+        return frozenset(
+            {
+                "battery_charging",
+                "cycle_capacity",
+                "delta_voltage",
+                "power",
+                "runtime",
+            }
+        )
+
+    async def _notification_handler(
+        self, _sender: BleakGATTCharacteristic, data: bytearray
+    ) -> None:
+        self._log.debug("RX BLE data: %s", data)
+
+        if len(data) != BMS._PAGE_LEN:
+            self._log.debug("invalid page length (%i)", len(data))
+            return
+
+        # ignore ACK responses
+        if data[0] & 0x80:
+            self._log.debug("ignore acknowledge message")
+            return
+
+        # acknowledge received frame
+        await self._await_reply(
+            bytes([data[0] | 0x80]) + data[1:], wait_for_notify=False
+        )
+
+        size: Final[int] = data[0]
+        page: Final[int] = data[1] >> 4
+        maxpg: Final[int] = data[1] & 0xF
+
+        if page == 1:
+            self._data.clear()
+
+        self._data += data[2 : size + 2]
+
+        self._log.debug("(%s): %s", "start" if page == 1 else "cnt.", data)
+
+        if page == maxpg:
+            if (crc := BMS._crc(self._data[3:-4])) != int.from_bytes(
+                self._data[-4:-2], byteorder="big"
+            ):
+                self._log.debug(
+                    "incorrect checksum: 0x%X != 0x%X",
+                    int.from_bytes(self._data[-4:-2], byteorder="big"),
+                    crc,
+                )
+                self._data.clear()
+                self._data_final = {}  # reset invalid data
+                return
+
+            self._data_final[self._data[3]] = self._data.copy()
+            self._data_event.set()
+
+    @staticmethod
+    def _crc(data: bytearray) -> int:
+        return sum(data) + 8
+
+    @staticmethod
+    def _cmd(cmd: Cmd, data: bytes) -> bytes:
+        frame: bytearray = bytearray([cmd.value, 0x00, 0x00]) + data
+        checksum: Final[int] = BMS._crc(frame)
+        frame = (
+            bytearray([0x3A, 0x03, 0x05])
+            + frame
+            + bytes([(checksum >> 8) & 0xFF, checksum & 0xFF, 0x0D, 0x0A])
+        )
+        frame = bytearray([len(frame) + 2, 0x11]) + frame
+        frame += bytes(BMS._PAGE_LEN - len(frame))
+
+        return bytes(frame)
+
+    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()
+
+        # unlock BMS if not TBA version
+        if self.name.startswith("TBA-"):
+            return
+
+        if not all(c in hexdigits for c in self.name[-4:]):
+            self._log.debug("unable to unlock BMS")
+            return
+
+        pwd = int(self.name[-4:], 16)
+        await self._await_reply(
+            BMS._cmd(
+                Cmd.UNLOCK,
+                bytes([(pwd >> 8) & 0xFF, pwd & 0xFF]),
+            ),
+            wait_for_notify=False,
+        )
+
+    async def _async_update(self) -> BMSsample:
+        """Update battery status information."""
+        for request in BMS._CMDS:
+            await self._await_reply(self._cmd(request, b""))
+
+        if not BMS._CMDS.issubset(set(self._data_final.keys())):
+            raise ValueError("incomplete response set")
+
+        result: BMSsample = BMS._decode_data(BMS._FIELDS, self._data_final)
+        result["cell_voltages"] = BMS._cell_voltages(
+            self._data_final[Cmd.CELLVOLT],
+            cells=result.get("cell_count", 0),
+            start=7,
+        )
+
+        self._data_final.clear()
+        return result

aiobmsble/bms/dummy_bms.py

@@ -0,0 +1,93 @@
+"""Module to support Dummy BMS.
+
+Project: aiobmsble, https://pypi.org/p/aiobmsble/
+License: Apache-2.0, http://www.apache.org/licenses/
+"""
+
+from bleak.backends.characteristic import BleakGATTCharacteristic
+from bleak.backends.device import BLEDevice
+from bleak.uuids import normalize_uuid_str
+
+from aiobmsble import BMSsample, BMSvalue, MatcherPattern
+from aiobmsble.basebms import BaseBMS
+
+
+class BMS(BaseBMS):
+    """Dummy BMS implementation."""
+
+    # _HEAD: Final[bytes] = b"\x55"  # beginning of frame
+    # _TAIL: Final[bytes] = b"\xAA"  # end of frame
+    # _FRAME_LEN: Final[int] = 10  # length of frame, including SOF and checksum
+
+    def __init__(self, ble_device: BLEDevice, reconnect: bool = False) -> None:
+        """Initialize BMS."""
+        super().__init__(ble_device, reconnect)
+
+    @staticmethod
+    def matcher_dict_list() -> list[MatcherPattern]:
+        """Provide BluetoothMatcher definition."""
+        return [{"local_name": "dummy", "connectable": True}]  # TODO
+
+    @staticmethod
+    def device_info() -> dict[str, str]:
+        """Return device information for the battery management system."""
+        return {"manufacturer": "Dummy Manufacturer", "model": "dummy model"}  # TODO
+
+    @staticmethod
+    def uuid_services() -> list[str]:
+        """Return list of 128-bit UUIDs of services required by BMS."""
+        return [normalize_uuid_str("0000")]  # TODO: change service UUID here!
+
+    @staticmethod
+    def uuid_rx() -> str:
+        """Return 16-bit UUID of characteristic that provides notification/read property."""
+        return "0000"  # TODO: change RX characteristic UUID here!
+
+    @staticmethod
+    def uuid_tx() -> str:
+        """Return 16-bit UUID of characteristic that provides write property."""
+        return "0000"  # TODO: change TX characteristic UUID here!
+
+    @staticmethod
+    def _calc_values() -> frozenset[BMSvalue]:
+        return frozenset(
+            {"power", "battery_charging"}
+        )  # 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)
+
+        # *******************************************************
+        # # TODO: Do things like checking correctness of frame here
+        # # and store it into a instance variable, e.g. self._data
+        # # Below are some examples of how to do it
+        # # Have a look at the BMS base class for function to use,
+        # # take a look at other implementations for more  details
+        # *******************************************************
+
+        # if not data.startswith(BMS._HEAD):
+        #     self._log.debug("incorrect SOF")
+        #     return
+
+        # if (crc := crc_sum(self._data[:-1])) != self._data[-1]:
+        #     self._log.debug("invalid checksum 0x%X != 0x%X", self._data[-1], crc)
+        #     return
+
+        # self._data = data.copy()
+        # self._data_event.set()
+
+    async def _async_update(self) -> BMSsample:
+        """Update battery status information."""
+        self._log.debug("replace with command to UUID %s", BMS.uuid_tx())
+        # await self._await_reply(b"<some_command>")
+
+        # # TODO: parse data from self._data here
+
+        return {
+            "voltage": 12,
+            "current": 1.5,
+            "temperature": 27.182,
+        }  # TODO: fixed values, replace parsed data

aiobmsble/bms/ecoworthy_bms.py

@@ -0,0 +1,155 @@
+"""Module to support ECO-WORTHY BMS.
+
+Project: aiobmsble, https://pypi.org/p/aiobmsble/
+License: Apache-2.0, http://www.apache.org/licenses/
+"""
+
+import asyncio
+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):
+    """ECO-WORTHY BMS implementation."""
+
+    _HEAD: Final[tuple] = (b"\xa1", b"\xa2")
+    _CELL_POS: Final[int] = 14
+    _TEMP_POS: Final[int] = 80
+    _FIELDS_V1: Final[tuple[BMSdp, ...]] = (
+        BMSdp("battery_level", 16, 2, False, lambda x: x, 0xA1),
+        BMSdp("voltage", 20, 2, False, lambda x: x / 100, 0xA1),
+        BMSdp("current", 22, 2, True, lambda x: x / 100, 0xA1),
+        BMSdp("problem_code", 51, 2, False, lambda x: x, 0xA1),
+        BMSdp("design_capacity", 26, 2, False, lambda x: x // 100, 0xA1),
+        BMSdp("cell_count", _CELL_POS, 2, False, lambda x: x, 0xA2),
+        BMSdp("temp_sensors", _TEMP_POS, 2, False, lambda x: x, 0xA2),
+        # ("cycles", 0xA1, 8, 2, False, lambda x: x),
+    )
+    _FIELDS_V2: Final[tuple[BMSdp, ...]] = tuple(
+        BMSdp(
+            *field[:-2],
+            (lambda x: x / 10) if field.key == "current" else field.fct,
+            field.idx,
+        )
+        for field in _FIELDS_V1
+    )
+
+    _CMDS: Final[set[int]] = set({field.idx for field in _FIELDS_V1})
+
+    def __init__(self, ble_device: BLEDevice, reconnect: bool = False) -> None:
+        """Initialize BMS."""
+        super().__init__(ble_device, reconnect)
+        self._mac_head: Final[tuple] = tuple(
+            int(self._ble_device.address.replace(":", ""), 16).to_bytes(6) + head
+            for head in BMS._HEAD
+        )
+        self._data_final: dict[int, bytearray] = {}
+
+    @staticmethod
+    def matcher_dict_list() -> list[MatcherPattern]:
+        """Provide BluetoothMatcher definition."""
+        return [MatcherPattern(local_name="ECO-WORTHY 02_*", connectable=True)] + [
+            MatcherPattern(
+                local_name=pattern,
+                service_uuid=BMS.uuid_services()[0],
+                connectable=True,
+            )
+            for pattern in ("DCHOUSE*", "ECO-WORTHY*")
+        ]
+
+    @staticmethod
+    def device_info() -> dict[str, str]:
+        """Return device information for the battery management system."""
+        return {"manufacturer": "ECO-WORTHY", "model": "BW02"}
+
+    @staticmethod
+    def uuid_services() -> list[str]:
+        """Return list of 128-bit UUIDs of services required by BMS."""
+        return [normalize_uuid_str("fff0")]
+
+    @staticmethod
+    def uuid_rx() -> str:
+        """Return 16-bit UUID of characteristic that provides notification/read property."""
+        return "fff1"
+
+    @staticmethod
+    def uuid_tx() -> str:
+        """Return 16-bit UUID of characteristic that provides write property."""
+        raise NotImplementedError
+
+    @staticmethod
+    def _calc_values() -> frozenset[BMSvalue]:
+        return frozenset(
+            {
+                "battery_charging",
+                "cycle_charge",
+                "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 + self._mac_head):
+            self._log.debug("invalid frame type: '%s'", data[0:1].hex())
+            return
+
+        if (crc := crc_modbus(data[:-2])) != int.from_bytes(data[-2:], "little"):
+            self._log.debug(
+                "invalid checksum 0x%X != 0x%X",
+                int.from_bytes(data[-2:], "little"),
+                crc,
+            )
+            self._data = bytearray()
+            return
+
+        # copy final data without message type and adapt to protocol type
+        shift: Final[bool] = data.startswith(self._mac_head)
+        self._data_final[data[6 if shift else 0]] = (
+            bytearray(2 if shift else 0) + data.copy()
+        )
+        if BMS._CMDS.issubset(self._data_final.keys()):
+            self._data_event.set()
+
+    async def _async_update(self) -> BMSsample:
+        """Update battery status information."""
+
+        self._data_final.clear()
+        self._data_event.clear()  # clear event to ensure new data is acquired
+        await asyncio.wait_for(self._wait_event(), timeout=BMS.TIMEOUT)
+
+        result: BMSsample = BMS._decode_data(
+            (
+                BMS._FIELDS_V1
+                if self._data_final[0xA1].startswith(BMS._HEAD)
+                else BMS._FIELDS_V2
+            ),
+            self._data_final,
+        )
+
+        result["cell_voltages"] = BMS._cell_voltages(
+            self._data_final[0xA2],
+            cells=result.get("cell_count", 0),
+            start=BMS._CELL_POS + 2,
+        )
+        result["temp_values"] = BMS._temp_values(
+            self._data_final[0xA2],
+            values=result.get("temp_sensors", 0),
+            start=BMS._TEMP_POS + 2,
+            divider=10,
+        )
+
+        return result

aiobmsble/bms/ective_bms.py

@@ -0,0 +1,181 @@
+"""Module to support Ective BMS.
+
+Project: aiobmsble, https://pypi.org/p/aiobmsble/
+License: Apache-2.0, http://www.apache.org/licenses/
+"""
+
+import asyncio
+from string import hexdigits
+from typing import Final, Literal
+
+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):
+    """Ective BMS implementation."""
+
+    _HEAD_RSP: Final[tuple[bytes, ...]] = (b"\x5e", b"\x83")  # header for responses
+    _MAX_CELLS: Final[int] = 16
+    _INFO_LEN: Final[int] = 113
+    _CRC_LEN: Final[int] = 4
+    _FIELDS: Final[tuple[BMSdp, ...]] = (
+        BMSdp("voltage", 1, 8, False, lambda x: x / 1000),
+        BMSdp("current", 9, 8, True, lambda x: x / 1000),
+        BMSdp("battery_level", 29, 4, False, lambda x: x),
+        BMSdp("cycle_charge", 17, 8, False, lambda x: x / 1000),
+        BMSdp("cycles", 25, 4, False, lambda x: x),
+        BMSdp("temperature", 33, 4, False, lambda x: round(x * 0.1 - 273.15, 1)),
+        BMSdp("problem_code", 37, 2, False, lambda x: x),
+    )
+
+    def __init__(self, ble_device: BLEDevice, reconnect: bool = False) -> None:
+        """Initialize BMS."""
+        super().__init__(ble_device, reconnect)
+        self._data_final: bytearray = bytearray()
+
+    @staticmethod
+    def matcher_dict_list() -> list[MatcherPattern]:
+        """Provide BluetoothMatcher definition."""
+        return [
+            {
+                "service_uuid": BMS.uuid_services()[0],
+                "connectable": True,
+                "manufacturer_id": m_id,
+            }
+            for m_id in (0, 0xFFFF)
+        ]
+
+    @staticmethod
+    def device_info() -> dict[str, str]:
+        """Return device information for the battery management system."""
+        return {"manufacturer": "Ective", "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")]
+
+    @staticmethod
+    def uuid_rx() -> str:
+        """Return 16-bit UUID of characteristic that provides notification/read property."""
+        return "ffe4"
+
+    @staticmethod
+    def uuid_tx() -> str:
+        """Return 16-bit UUID of characteristic that provides write property."""
+        raise NotImplementedError
+
+    @staticmethod
+    def _calc_values() -> frozenset[BMSvalue]:
+        return frozenset(
+            {
+                "battery_charging",
+                "cycle_capacity",
+                "cycle_charge",
+                "delta_voltage",
+                "power",
+                "runtime",
+            }
+        )  # 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)."""
+
+        if (
+            start := next(
+                (i for i, b in enumerate(data) if bytes([b]) in BMS._HEAD_RSP), -1
+            )
+        ) != -1:  # check for beginning of frame
+            data = data[start:]
+            self._data.clear()
+
+        self._data += data
+        self._log.debug(
+            "RX BLE data (%s): %s", "start" if data == self._data else "cnt.", data
+        )
+
+        if len(self._data) < BMS._INFO_LEN:
+            return
+
+        self._data = self._data[: BMS._INFO_LEN]  # cut off exceeding data
+
+        if not (
+            self._data.startswith(BMS._HEAD_RSP)
+            and set(self._data.decode(errors="replace")[1:]).issubset(hexdigits)
+        ):
+            self._log.debug("incorrect frame coding: %s", self._data)
+            self._data.clear()
+            return
+
+        if (crc := BMS._crc(self._data[1 : -BMS._CRC_LEN])) != int(
+            self._data[-BMS._CRC_LEN :], 16
+        ):
+            self._log.debug(
+                "invalid checksum 0x%X != 0x%X",
+                int(self._data[-BMS._CRC_LEN :], 16),
+                crc,
+            )
+            self._data.clear()
+            return
+
+        self._data_final = self._data.copy()
+        self._data_event.set()
+
+    @staticmethod
+    def _crc(data: bytearray) -> int:
+        return sum(int(data[idx : idx + 2], 16) for idx in range(0, len(data), 2))
+
+    @staticmethod
+    def _cell_voltages(
+        data: bytearray,
+        *,
+        cells: int,
+        start: int,
+        size: int = 2,
+        byteorder: Literal["little", "big"] = "big",
+        divider: int = 1000,
+    ) -> list[float]:
+        """Parse cell voltages from status message."""
+        return [
+            (value / divider)
+            for idx in range(cells)
+            if (
+                value := BMS._conv_int(
+                    data[start + idx * size : start + (idx + 1) * size]
+                )
+            )
+        ]
+
+    @staticmethod
+    def _conv_int(data: bytearray, sign: bool = False) -> int:
+        return int.from_bytes(
+            bytes.fromhex(data.decode("ascii", errors="strict")),
+            byteorder="little",
+            signed=sign,
+        )
+
+    @staticmethod
+    def _conv_data(data: bytearray) -> BMSsample:
+        result: BMSsample = {}
+        for field in BMS._FIELDS:
+            result[field.key] = field.fct(
+                BMS._conv_int(data[field.pos : field.pos + field.size], field.signed)
+            )
+        return result
+
+    async def _async_update(self) -> BMSsample:
+        """Update battery status information."""
+
+        await asyncio.wait_for(self._wait_event(), timeout=BMS.TIMEOUT)
+        return self._conv_data(self._data_final) | {
+            "cell_voltages": BMS._cell_voltages(
+                self._data_final, cells=BMS._MAX_CELLS, start=45, size=4
+            )
+        }