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

aiobmsble/bms/cbtpwr_bms.py

@@ -0,0 +1,172 @@
+"""Module to support CBT Power Smart 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_sum
+
+
+class BMS(BaseBMS):
+    """CBT Power Smart BMS class implementation."""
+
+    HEAD: Final[bytes] = bytes([0xAA, 0x55])
+    TAIL_RX: Final[bytes] = bytes([0x0D, 0x0A])
+    TAIL_TX: Final[bytes] = bytes([0x0A, 0x0D])
+    MIN_FRAME: Final[int] = len(HEAD) + len(TAIL_RX) + 3  # CMD, LEN, CRC, 1 Byte each
+    CRC_POS: Final[int] = -len(TAIL_RX) - 1
+    LEN_POS: Final[int] = 3
+    CMD_POS: Final[int] = 2
+    CELL_VOLTAGE_CMDS: Final[list[int]] = [0x5, 0x6, 0x7, 0x8]
+    _FIELDS: Final[tuple[BMSdp, ...]] = (
+        BMSdp("voltage", 4, 4, False, lambda x: x / 1000, 0x0B),
+        BMSdp("current", 8, 4, True, lambda x: x / 1000, 0x0B),
+        BMSdp("temperature", 4, 2, True, lambda x: x, 0x09),
+        BMSdp("battery_level", 4, 1, False, lambda x: x, 0x0A),
+        BMSdp("design_capacity", 4, 2, False, lambda x: x, 0x15),
+        BMSdp("cycles", 6, 2, False, lambda x: x, 0x15),
+        BMSdp("runtime", 14, 2, False, lambda x: x * BMS._HRS_TO_SECS / 100, 0x0C),
+        BMSdp("problem_code", 4, 4, False, lambda x: x, 0x21),
+    )
+    _CMDS: Final[list[int]] = list({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)
+
+    @staticmethod
+    def matcher_dict_list() -> list[MatcherPattern]:
+        """Provide BluetoothMatcher definition."""
+        return [
+            {"service_uuid": BMS.uuid_services()[0], "connectable": True},
+            {  # Creabest
+                "service_uuid": normalize_uuid_str("fff0"),
+                "manufacturer_id": 0,
+                "connectable": True,
+            },
+            {
+                "service_uuid": normalize_uuid_str("03c1"),
+                "manufacturer_id": 0x5352,
+                "connectable": True,
+            },
+        ]
+
+    @staticmethod
+    def device_info() -> dict[str, str]:
+        """Return device information for the battery management system."""
+        return {"manufacturer": "CBT Power", "model": "Smart BMS"}
+
+    @staticmethod
+    def uuid_services() -> list[str]:
+        """Return list of services required by BMS."""
+        return [normalize_uuid_str("ffe5"), normalize_uuid_str("ffe0")]
+
+    @staticmethod
+    def uuid_rx() -> str:
+        """Return characteristic that provides notification/read property."""
+        return "ffe4"
+
+    @staticmethod
+    def uuid_tx() -> str:
+        """Return characteristic that provides write property."""
+        return "ffe9"
+
+    @staticmethod
+    def _calc_values() -> frozenset[BMSvalue]:
+        return frozenset(
+            {
+                "power",
+                "battery_charging",
+                "delta_voltage",
+                "cycle_capacity",
+                "temperature",
+            }
+        )
+
+    def _notification_handler(
+        self, _sender: BleakGATTCharacteristic, data: bytearray
+    ) -> None:
+        """Retrieve BMS data update."""
+        self._log.debug("RX BLE data: %s", data)
+
+        # verify that data is long enough
+        if len(data) < BMS.MIN_FRAME or len(data) != BMS.MIN_FRAME + data[BMS.LEN_POS]:
+            self._log.debug("incorrect frame length (%i): %s", len(data), data)
+            return
+
+        if not data.startswith(BMS.HEAD) or not data.endswith(BMS.TAIL_RX):
+            self._log.debug("incorrect frame start/end: %s", data)
+            return
+
+        if (crc := crc_sum(data[len(BMS.HEAD) : len(data) + BMS.CRC_POS])) != data[
+            BMS.CRC_POS
+        ]:
+            self._log.debug(
+                "invalid checksum 0x%X != 0x%X",
+                data[len(data) + BMS.CRC_POS],
+                crc,
+            )
+            return
+
+        self._data = data
+        self._data_event.set()
+
+    @staticmethod
+    def _cmd(cmd: bytes, value: list[int] | None = None) -> bytes:
+        """Assemble a CBT Power BMS command."""
+        value = [] if value is None else value
+        assert len(value) <= 255
+        frame = bytearray([*BMS.HEAD, cmd[0], len(value), *value])
+        frame.append(crc_sum(frame[len(BMS.HEAD) :]))
+        frame.extend(BMS.TAIL_TX)
+        return bytes(frame)
+
+    async def _async_update(self) -> BMSsample:
+        """Update battery status information."""
+        resp_cache: dict[int, bytearray] = {}  # avoid multiple queries
+        for cmd in BMS._CMDS:
+            self._log.debug("request command 0x%X.", cmd)
+            try:
+                await self._await_reply(BMS._cmd(cmd.to_bytes(1)))
+            except TimeoutError:
+                continue
+            if cmd != self._data[BMS.CMD_POS]:
+                self._log.debug(
+                    "incorrect response 0x%X to command 0x%X",
+                    self._data[BMS.CMD_POS],
+                    cmd,
+                )
+            resp_cache[self._data[BMS.CMD_POS]] = self._data.copy()
+
+        voltages: list[float] = []
+        for cmd in BMS.CELL_VOLTAGE_CMDS:
+            try:
+                await self._await_reply(BMS._cmd(cmd.to_bytes(1)))
+            except TimeoutError:
+                break
+            cells: list[float] = BMS._cell_voltages(
+                self._data, cells=5, start=4, byteorder="little"
+            )
+            voltages.extend(cells)
+            if len(voltages) % 5 or len(cells) == 0:
+                break
+
+        data: BMSsample = BMS._decode_data(BMS._FIELDS, resp_cache, byteorder="little")
+
+        # get cycle charge from design capacity and SoC
+        if data.get("design_capacity") and data.get("battery_level"):
+            data["cycle_charge"] = (
+                data.get("design_capacity", 0) * data.get("battery_level", 0) / 100
+            )
+        # remove runtime if not discharging
+        if data.get("current", 0) >= 0:
+            data.pop("runtime", None)
+
+        return data | {"cell_voltages": voltages}

aiobmsble/bms/cbtpwr_vb_bms.py

@@ -0,0 +1,188 @@
+"""Module to support CBT Power VB series BMS.
+
+Project: aiobmsble, https://pypi.org/p/aiobmsble/
+License: Apache-2.0, http://www.apache.org/licenses/
+"""
+
+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,168 @@
+"""Module to support Daly Smart 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):
+    """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