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

aiobmsble/bms/cbtpwr_vb_bms.py

@@ -0,0 +1,184 @@
+"""Module to support CBT Power VB series BMS."""
+
+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, lrc_modbus
+
+
+class BMS(BaseBMS):
+    """CBT Power VB series battery class implementation."""
+
+    _HEAD: Final[bytes] = b"\x7e"
+    _TAIL: Final[bytes] = b"\x0d"
+    _CMD_VER: Final[int] = 0x11  # TX protocol version
+    _RSP_VER: Final[int] = 0x22  # RX protocol version
+    _LEN_POS: Final[int] = 9
+    _MIN_LEN: Final[int] = _LEN_POS + 3 + len(_HEAD) + len(_TAIL) + 4
+    _MAX_LEN: Final[int] = 255
+    _CELL_POS: Final[int] = 6
+
+    _FIELDS: Final[tuple[BMSdp, ...]] = (
+        BMSdp("voltage", 2, 2, False, lambda x: x / 10),
+        BMSdp("current", 0, 2, True, lambda x: x / 10),
+        BMSdp("battery_level", 4, 2, False, lambda x: min(x, 100)),
+        BMSdp("cycles", 7, 2, False),
+        BMSdp("problem_code", 15, 6, False, lambda x: x & 0xFFF000FF000F),
+    )
+
+    def __init__(self, ble_device: BLEDevice, reconnect: bool = False) -> None:
+        """Initialize BMS."""
+        super().__init__(ble_device, reconnect)
+        self._exp_len: int = 0
+
+    @staticmethod
+    def matcher_dict_list() -> list[MatcherPattern]:
+        """Provide BluetoothMatcher definition."""
+        return [
+            {  # Creabest
+                "service_uuid": normalize_uuid_str("fff0"),
+                "manufacturer_id": 16963,
+                "connectable": True,
+            },
+        ]
+
+    @staticmethod
+    def device_info() -> dict[str, str]:
+        """Return device information for the battery management system."""
+        return {"manufacturer": "Creabest", "model": "VB series"}
+
+    @staticmethod
+    def uuid_services() -> list[str]:
+        """Return list of 128-bit UUIDs of services required by BMS."""
+        return [
+            normalize_uuid_str("ffe0"),
+            normalize_uuid_str("ffe5"),
+        ]
+
+    @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."""
+        return "ffe9"
+
+    @staticmethod
+    def _calc_values() -> frozenset[BMSvalue]:
+        return frozenset(
+            {
+                "battery_charging",
+                "delta_voltage",
+                "temperature",
+                "power",
+                "runtime",
+                "cycle_capacity",
+                "cycle_charge",
+            }
+        )  # 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 len(data) > BMS._LEN_POS + 4 and data.startswith(BMS._HEAD):
+            self._data = bytearray()
+            try:
+                length: Final[int] = int(data[BMS._LEN_POS : BMS._LEN_POS + 4], 16)
+                self._exp_len = length & 0xFFF
+                if BMS.lencs(length) != length >> 12:
+                    self._exp_len = 0
+                    self._log.debug("incorrect length checksum.")
+            except ValueError:
+                self._exp_len = 0
+
+        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 + BMS._MIN_LEN:
+            return
+
+        if not self._data.endswith(BMS._TAIL):
+            self._log.debug("incorrect EOF: %s", data)
+            self._data.clear()
+            return
+
+        if not all(chr(c) in hexdigits for c in self._data[1:-1]):
+            self._log.debug("incorrect frame encoding.")
+            self._data.clear()
+            return
+
+        if (ver := bytes.fromhex(self._data[1:3].decode())) != BMS._RSP_VER.to_bytes():
+            self._log.debug("unknown response frame version: 0x%X", int.from_bytes(ver))
+            self._data.clear()
+            return
+
+        if (crc := lrc_modbus(self._data[1:-5])) != int(self._data[-5:-1], 16):
+            self._log.debug(
+                "invalid checksum 0x%X != 0x%X", crc, int(self._data[-5:-1], 16)
+            )
+            self._data.clear()
+            return
+
+        self._data = bytearray(
+            bytes.fromhex(self._data.strip(BMS._HEAD + BMS._TAIL).decode())
+        )
+        self._data_event.set()
+
+    @staticmethod
+    def lencs(length: int) -> int:
+        """Calculate the length checksum."""
+        return (sum((length >> (i * 4)) & 0xF for i in range(3)) ^ 0xF) + 1 & 0xF
+
+    @staticmethod
+    def _cmd(cmd: int, dev_id: int = 1, data: bytes = b"") -> bytes:
+        """Assemble a Seplos VB series command."""
+        assert len(data) <= 0xFFF
+        cdat: Final[bytes] = data + int.to_bytes(dev_id)
+        frame = bytearray([BMS._CMD_VER, dev_id, 0x46, cmd])
+        frame.extend(
+            int.to_bytes(len(cdat) * 2 + (BMS.lencs(len(cdat) * 2) << 12), 2, "big")
+        )
+        frame.extend(cdat)
+        frame.extend(
+            int.to_bytes(lrc_modbus(bytearray(frame.hex().upper().encode())), 2, "big")
+        )
+        return BMS._HEAD + frame.hex().upper().encode() + BMS._TAIL
+
+    async def _async_update(self) -> BMSsample:
+        """Update battery status information."""
+
+        await self._await_reply(BMS._cmd(0x42))
+        result: BMSsample = {"cell_count": self._data[BMS._CELL_POS]}
+        temp_pos: Final[int] = BMS._CELL_POS + result.get("cell_count", 0) * 2 + 1
+        result["temp_sensors"] = self._data[temp_pos]
+        result["cell_voltages"] = BMS._cell_voltages(
+            self._data, cells=result.get("cell_count", 0), start=BMS._CELL_POS + 1
+        )
+        result["temp_values"] = BMS._temp_values(
+            self._data,
+            values=result.get("temp_sensors", 0),
+            start=temp_pos + 1,
+            divider=10,
+        )
+
+        result |= BMS._decode_data(
+            BMS._FIELDS, self._data, offset=temp_pos + 2 * result["temp_sensors"] + 1
+        )
+
+        await self._await_reply(BMS._cmd(0x81, 1, b"\x01\x00"), max_size=20)
+        result["design_capacity"] = (
+            int.from_bytes(self._data[6:8], byteorder="big", signed=False) // 10
+        )
+
+        return result

aiobmsble/bms/daly_bms.py

@@ -0,0 +1,164 @@
+"""Module to support Daly Smart BMS."""
+
+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):
+    """Daly Smart BMS class implementation."""
+
+    HEAD_READ: Final[bytes] = b"\xd2\x03"
+    CMD_INFO: Final[bytes] = b"\x00\x00\x00\x3e\xd7\xb9"
+    MOS_INFO: Final[bytes] = b"\x00\x3e\x00\x09\xf7\xa3"
+    HEAD_LEN: Final[int] = 3
+    CRC_LEN: Final[int] = 2
+    MAX_CELLS: Final[int] = 32
+    MAX_TEMP: Final[int] = 8
+    INFO_LEN: Final[int] = 84 + HEAD_LEN + CRC_LEN + MAX_CELLS + MAX_TEMP
+    MOS_TEMP_POS: Final[int] = HEAD_LEN + 8
+    MOS_NOT_AVAILABLE: Final[tuple[str]] = ("DL-FB4C2E0",)
+    _FIELDS: Final[tuple[BMSdp, ...]] = (
+        BMSdp("voltage", 80, 2, False, lambda x: x / 10),
+        BMSdp("current", 82, 2, False, lambda x: (x - 30000) / 10),
+        BMSdp("battery_level", 84, 2, False, lambda x: x / 10),
+        BMSdp("cycle_charge", 96, 2, False, lambda x: x / 10),
+        BMSdp("cell_count", 98, 2, False, lambda x: min(x, BMS.MAX_CELLS)),
+        BMSdp("temp_sensors", 100, 2, False, lambda x: min(x, BMS.MAX_TEMP)),
+        BMSdp("cycles", 102, 2, False, lambda x: x),
+        BMSdp("delta_voltage", 112, 2, False, lambda x: x / 1000),
+        BMSdp("problem_code", 116, 8, False, lambda x: x % 2**64),
+    )
+
+    def __init__(self, ble_device: BLEDevice, reconnect: bool = False) -> None:
+        """Intialize private BMS members."""
+        super().__init__(ble_device, reconnect)
+
+    @staticmethod
+    def matcher_dict_list() -> list[MatcherPattern]:
+        """Provide BluetoothMatcher definition."""
+        return [
+            MatcherPattern(
+                local_name="DL-*",
+                service_uuid=BMS.uuid_services()[0],
+                connectable=True,
+            )
+        ] + [
+            MatcherPattern(
+                manufacturer_id=m_id,
+                connectable=True,
+            )
+            for m_id in (0x102, 0x104, 0x0302, 0x0303)
+        ]
+
+    @staticmethod
+    def device_info() -> dict[str, str]:
+        """Return device information for the battery management system."""
+        return {"manufacturer": "Daly", "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 "fff1"
+
+    @staticmethod
+    def uuid_tx() -> str:
+        """Return 16-bit UUID of characteristic that provides write property."""
+        return "fff2"
+
+    @staticmethod
+    def _calc_values() -> frozenset[BMSvalue]:
+        return frozenset(
+            {
+                "cycle_capacity",
+                "power",
+                "battery_charging",
+                "runtime",
+                "temperature",
+            }
+        )
+
+    def _notification_handler(
+        self, _sender: BleakGATTCharacteristic, data: bytearray
+    ) -> None:
+        self._log.debug("RX BLE data: %s", data)
+
+        if (
+            len(data) < BMS.HEAD_LEN
+            or data[0:2] != BMS.HEAD_READ
+            or data[2] + 1 != len(data) - len(BMS.HEAD_READ) - BMS.CRC_LEN
+        ):
+            self._log.debug("response data is invalid")
+            return
+
+        if (crc := crc_modbus(data[:-2])) != int.from_bytes(
+            data[-2:], byteorder="little"
+        ):
+            self._log.debug(
+                "invalid checksum 0x%X != 0x%X",
+                int.from_bytes(data[-2:], byteorder="little"),
+                crc,
+            )
+            self._data.clear()
+            return
+
+        self._data = data
+        self._data_event.set()
+
+    async def _async_update(self) -> BMSsample:
+        """Update battery status information."""
+        result: BMSsample = {}
+        if (  # do not query devices that do not support MOS temperature, e.g. Bulltron
+            not self.name or not self.name.startswith(BMS.MOS_NOT_AVAILABLE)
+        ):
+            try:
+                # request MOS temperature (possible outcome: response, empty response, no response)
+                await self._await_reply(BMS.HEAD_READ + BMS.MOS_INFO)
+
+                if sum(self._data[BMS.MOS_TEMP_POS :][:2]):
+                    self._log.debug("MOS info: %s", self._data)
+                    result["temp_values"] = [
+                        int.from_bytes(
+                            self._data[BMS.MOS_TEMP_POS :][:2],
+                            byteorder="big",
+                            signed=True,
+                        )
+                        - 40
+                    ]
+            except TimeoutError:
+                self._log.debug("no MOS temperature available.")
+
+        await self._await_reply(BMS.HEAD_READ + BMS.CMD_INFO)
+
+        if len(self._data) != BMS.INFO_LEN:
+            self._log.debug("incorrect frame length: %i", len(self._data))
+            return {}
+
+        result |= BMS._decode_data(BMS._FIELDS, self._data, offset=BMS.HEAD_LEN)
+
+        # add temperature sensors
+        result.setdefault("temp_values", []).extend(
+            BMS._temp_values(
+                self._data,
+                values=result.get("temp_sensors", 0),
+                start=64 + BMS.HEAD_LEN,
+                offset=40,
+            )
+        )
+
+        # get cell voltages
+        result["cell_voltages"] = BMS._cell_voltages(
+            self._data, cells=result.get("cell_count", 0), start=BMS.HEAD_LEN
+        )
+
+        return result

aiobmsble/bms/dpwrcore_bms.py

@@ -0,0 +1,207 @@
+"""Module to support D-powercore Smart BMS."""
+
+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,89 @@
+"""Module to support Dummy BMS."""
+
+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