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

aiobmsble/bms/ant_bms.py

@@ -0,0 +1,196 @@
+"""Module to support ANT 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):
+    """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,167 @@
+"""Module to support Braun Power 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
+
+
+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

aiobmsble/bms/cbtpwr_bms.py

@@ -0,0 +1,168 @@
+"""Module to support CBT Power 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_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}