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

aiobmsble/bms/renogy_pro_bms.py

@@ -0,0 +1,109 @@
+"""Module to support Renogy Pro 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 BMSdp, MatcherPattern
+from aiobmsble.bms.renogy_bms import BMS as RenogyBMS
+
+
+class BMS(RenogyBMS):
+    """Renogy Pro battery class implementation."""
+
+    HEAD: bytes = b"\xff\x03"  # SOP, read fct (x03)
+    FIELDS: tuple[BMSdp, ...] = (
+        BMSdp("voltage", 5, 2, False, lambda x: x / 10),
+        BMSdp("current", 3, 2, True, lambda x: x / 10),
+        BMSdp("design_capacity", 11, 4, False, lambda x: x // 1000),
+        BMSdp("cycle_charge", 7, 4, False, lambda x: x / 1000),
+        BMSdp("cycles", 15, 2, False, lambda x: x),
+    )
+
+    def __init__(self, ble_device: BLEDevice, reconnect: bool = False) -> None:
+        """Intialize private BMS members."""
+        super().__init__(ble_device, reconnect)
+        self._char_write_handle: int = -1
+
+    @staticmethod
+    def matcher_dict_list() -> list[MatcherPattern]:
+        """Provide BluetoothMatcher definition."""
+        return [
+            {
+                "local_name": "RNGRBP*",
+                "manufacturer_id": 0xE14C,
+                "connectable": True,
+            },
+        ]
+
+    @staticmethod
+    def device_info() -> dict[str, str]:
+        """Return device information for the battery management system."""
+        return {"manufacturer": "Renogy", "model": "Bluetooth battery pro"}
+
+    async def _init_connection(
+        self, char_notify: BleakGATTCharacteristic | int | str | None = None
+    ) -> None:
+        """Initialize RX/TX characteristics and protocol state."""
+        char_notify_handle: int = -1
+        self._char_write_handle = -1
+        assert char_notify is None, "char_notify not used for Renogy Pro BMS"
+
+        for service in self._client.services:
+            self._log.debug(
+                "service %s (#%i): %s",
+                service.uuid,
+                service.handle,
+                service.description,
+            )
+            for char in service.characteristics:
+                self._log.debug(
+                    "characteristic %s (#%i): %s",
+                    char.uuid,
+                    char.handle,
+                    char.properties,
+                )
+                if (
+                    service.uuid == BMS.uuid_services()[0]
+                    and char.uuid == normalize_uuid_str(BMS.uuid_tx())
+                    and any(
+                        prop in char.properties
+                        for prop in ("write", "write-without-response")
+                    )
+                ):
+                    self._char_write_handle = char.handle
+                if (
+                    service.uuid == BMS.uuid_services()[1]
+                    and char.uuid == normalize_uuid_str(BMS.uuid_rx())
+                    and "notify" in char.properties
+                ):
+                    char_notify_handle = char.handle
+
+        if char_notify_handle == -1 or self._char_write_handle == -1:
+            self._log.debug("failed to detect characteristics.")
+            await self._client.disconnect()
+            raise ConnectionError(f"Failed to detect characteristics from {self.name}.")
+        self._log.debug(
+            "using characteristics handle #%i (notify), #%i (write).",
+            char_notify_handle,
+            self._char_write_handle,
+        )
+
+        await super()._init_connection(char_notify_handle)
+
+    async def _await_reply(
+        self,
+        data: bytes,
+        char: int | str | None = None,
+        wait_for_notify: bool = True,
+        max_size: int = 0,
+    ) -> None:
+        """Send data to the BMS and wait for valid reply notification."""
+
+        await super()._await_reply(
+            data, self._char_write_handle, wait_for_notify, max_size
+        )

aiobmsble/bms/roypow_bms.py

@@ -0,0 +1,190 @@
+"""Module to support RoyPow 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):
+    """RoyPow BMS implementation."""
+
+    _HEAD: Final[bytes] = b"\xea\xd1\x01"
+    _TAIL: Final[int] = 0xF5
+    _BT_MODULE_MSG: Final[bytes] = b"AT+STAT\r\n"  # AT cmd from BLE module
+    _MIN_LEN: Final[int] = len(_HEAD) + 1
+    _FIELDS: Final[tuple[BMSdp, ...]] = (
+        BMSdp("battery_level", 7, 1, False, lambda x: x, 0x4),
+        BMSdp("voltage", 47, 2, False, lambda x: x / 100, 0x4),
+        BMSdp(
+            "current",
+            6,
+            3,
+            False,
+            lambda x: (x & 0xFFFF) * (-1 if (x >> 16) & 0x1 else 1) / 100,
+            0x3,
+        ),
+        BMSdp("problem_code", 9, 3, False, lambda x: x, 0x3),
+        BMSdp(
+            "cycle_charge",
+            24,
+            4,
+            False,
+            lambda x: ((x & 0xFFFF0000) | (x & 0xFF00) >> 8 | (x & 0xFF) << 8) / 1000,
+            0x4,
+        ),
+        BMSdp("runtime", 30, 2, False, lambda x: x * 60, 0x4),
+        BMSdp("temp_sensors", 13, 1, False, lambda x: x, 0x3),
+        BMSdp("cycles", 9, 2, False, lambda x: x, 0x4),
+    )
+    _CMDS: Final[set[int]] = set({field.idx for field in _FIELDS})
+
+    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_len: int = 0
+
+    @staticmethod
+    def matcher_dict_list() -> list[MatcherPattern]:
+        """Provide BluetoothMatcher definition."""
+        return [
+            {
+                "service_uuid": BMS.uuid_services()[0],
+                "manufacturer_id": manufacturer_id,
+                "connectable": True,
+            }
+            for manufacturer_id in (0x01A8, 0x0B31, 0x8AFB)
+        ]
+
+    @staticmethod
+    def device_info() -> dict[str, str]:
+        """Return device information for the battery management system."""
+        return {"manufacturer": "RoyPow", "model": "SmartBMS"}
+
+    @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 "ffe1"
+
+    @staticmethod
+    def _calc_values() -> frozenset[BMSvalue]:
+        return frozenset(
+            {
+                "battery_charging",
+                "cycle_capacity",
+                "delta_voltage",
+                "power",
+                "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)."""
+        if not (data := data.removeprefix(BMS._BT_MODULE_MSG)):
+            self._log.debug("filtering AT cmd")
+            return
+
+        if (
+            data.startswith(BMS._HEAD)
+            and not self._data.startswith(BMS._HEAD)
+            and len(data) > len(BMS._HEAD)
+        ):
+            self._exp_len = data[len(BMS._HEAD)]
+            self._data.clear()
+
+        self._data += data
+        self._log.debug(
+            "RX BLE data (%s): %s", "start" if data == self._data else "cnt.", data
+        )
+
+        if not self._data.startswith(BMS._HEAD):
+            self._data.clear()
+            return
+
+        # verify that data is long enough
+        if len(self._data) < BMS._MIN_LEN + self._exp_len:
+            return
+
+        end_idx: Final[int] = BMS._MIN_LEN + self._exp_len - 1
+        if self._data[end_idx] != BMS._TAIL:
+            self._log.debug("incorrect EOF: %s", self._data)
+            self._data.clear()
+            return
+
+        if (crc := BMS._crc(self._data[len(BMS._HEAD) : end_idx - 1])) != self._data[
+            end_idx - 1
+        ]:
+            self._log.debug(
+                "invalid checksum 0x%X != 0x%X", self._data[end_idx - 1], crc
+            )
+            self._data.clear()
+            return
+
+        self._data_final[self._data[5]] = self._data.copy()
+        self._data.clear()
+        self._data_event.set()
+
+    @staticmethod
+    def _crc(frame: bytearray) -> int:
+        """Calculate XOR of all frame bytes."""
+        crc: int = 0
+        for b in frame:
+            crc ^= b
+        return crc
+
+    @staticmethod
+    def _cmd(cmd: bytes) -> bytes:
+        """Assemble a RoyPow BMS command."""
+        data: Final[bytearray] = bytearray([len(cmd) + 2, *cmd])
+        return bytes([*BMS._HEAD, *data, BMS._crc(data), BMS._TAIL])
+
+    async def _async_update(self) -> BMSsample:
+        """Update battery status information."""
+
+        self._data.clear()
+        self._data_final.clear()
+        for cmd in range(2, 5):
+            await self._await_reply(BMS._cmd(bytes([0xFF, cmd])))
+
+        result: BMSsample = BMS._decode_data(BMS._FIELDS, self._data_final)
+
+        # remove remaining runtime if battery is charging
+        if result.get("runtime") == 0xFFFF * 60:
+            result.pop("runtime", None)
+
+        result["cell_voltages"] = BMS._cell_voltages(
+            self._data_final.get(0x2, bytearray()),
+            cells=max(0, (len(self._data_final.get(0x2, bytearray())) - 11) // 2),
+            start=9,
+        )
+        result["temp_values"] = BMS._temp_values(
+            self._data_final.get(0x3, bytearray()),
+            values=result.get("temp_sensors", 0),
+            start=14,
+            size=1,
+            signed=False,
+            offset=40,
+        )
+
+        return result

aiobmsble/bms/seplos_bms.py

@@ -0,0 +1,249 @@
+"""Module to support Seplos V3 Smart BMS.
+
+Project: aiobmsble, https://pypi.org/p/aiobmsble/
+License: Apache-2.0, http://www.apache.org/licenses/
+"""
+
+from collections.abc import Callable
+from typing import Any, Final
+
+from bleak.backends.characteristic import BleakGATTCharacteristic
+from bleak.backends.device import BLEDevice
+from bleak.uuids import normalize_uuid_str
+
+from aiobmsble import BMSdp, BMSpackvalue, BMSsample, BMSvalue, MatcherPattern
+from aiobmsble.basebms import BaseBMS, crc_modbus
+
+
+class BMS(BaseBMS):
+    """Seplos V3 Smart BMS class implementation."""
+
+    CMD_READ: Final[list[int]] = [0x01, 0x04]
+    HEAD_LEN: Final[int] = 3
+    CRC_LEN: Final[int] = 2
+    PIA_LEN: Final[int] = 0x11
+    PIB_LEN: Final[int] = 0x1A
+    EIA_LEN: Final[int] = PIB_LEN
+    EIB_LEN: Final[int] = 0x16
+    EIC_LEN: Final[int] = 0x5
+    _TEMP_START: Final[int] = HEAD_LEN + 32
+    QUERY: Final[dict[str, tuple[int, int, int]]] = {
+        # name: cmd, reg start, length
+        "EIA": (0x4, 0x2000, EIA_LEN),
+        "EIB": (0x4, 0x2100, EIB_LEN),
+        "EIC": (0x1, 0x2200, EIC_LEN),
+    }
+    PQUERY: Final[dict[str, tuple[int, int, int]]] = {
+        "PIA": (0x4, 0x1000, PIA_LEN),
+        "PIB": (0x4, 0x1100, PIB_LEN),
+    }
+    _FIELDS: Final[tuple[BMSdp, ...]] = (
+        BMSdp("temperature", 20, 2, True, lambda x: x / 10, EIB_LEN),  # avg. ctemp
+        BMSdp("voltage", 0, 4, False, lambda x: BMS._swap32(x) / 100, EIA_LEN),
+        BMSdp("current", 4, 4, True, lambda x: BMS._swap32(x, True) / 10, EIA_LEN),
+        BMSdp("cycle_charge", 8, 4, False, lambda x: BMS._swap32(x) / 100, EIA_LEN),
+        BMSdp("pack_count", 44, 2, False, lambda x: x, EIA_LEN),
+        BMSdp("cycles", 46, 2, False, lambda x: x, EIA_LEN),
+        BMSdp("battery_level", 48, 2, False, lambda x: x / 10, EIA_LEN),
+        BMSdp("problem_code", 1, 9, False, lambda x: x & 0xFFFF00FF00FF0000FF, EIC_LEN),
+    )  # Protocol Seplos V3
+    _PFIELDS: Final[list[tuple[BMSpackvalue, int, bool, Callable[[int], Any]]]] = [
+        ("pack_voltages", 0, False, lambda x: x / 100),
+        ("pack_currents", 2, True, lambda x: x / 100),
+        ("pack_battery_levels", 10, False, lambda x: x / 10),
+        ("pack_cycles", 14, False, lambda x: x),
+    ]  # Protocol Seplos V3
+    _CMDS: Final[set[int]] = {field[2] for field in QUERY.values()} | {
+        field[2] for field in PQUERY.values()
+    }
+
+    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._pack_count: int = 0  # number of battery packs
+        self._pkglen: int = 0  # expected packet length
+
+    @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 {f"SP{num}?B*" for num in range(10)} | {"CSY*"}
+        ]
+
+    @staticmethod
+    def device_info() -> dict[str, str]:
+        """Return device information for the battery management system."""
+        return {"manufacturer": "Seplos", "model": "Smart BMS V3"}
+
+    # setup UUIDs
+    #    serv 0000fff0-0000-1000-8000-00805f9b34fb
+    # 	 char 0000fff1-0000-1000-8000-00805f9b34fb (#16): ['read', 'notify']
+    # 	 char 0000fff2-0000-1000-8000-00805f9b34fb (#20): ['read', 'write-without-response', 'write']
+    @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({"power", "battery_charging", "cycle_capacity", "runtime"})
+
+    def _notification_handler(
+        self, _sender: BleakGATTCharacteristic, data: bytearray
+    ) -> None:
+        """Retrieve BMS data update."""
+
+        if (
+            len(data) > BMS.HEAD_LEN + BMS.CRC_LEN
+            and data[0] <= self._pack_count
+            and data[1] & 0x7F in BMS.CMD_READ  # include read errors
+            and data[2] >= BMS.HEAD_LEN + BMS.CRC_LEN
+        ):
+            self._data = bytearray()
+            self._pkglen = data[2] + BMS.HEAD_LEN + BMS.CRC_LEN
+        elif (  # error message
+            len(data) == BMS.HEAD_LEN + BMS.CRC_LEN
+            and data[0] <= self._pack_count
+            and data[1] & 0x80
+        ):
+            self._log.debug("RX error: %X", data[2])
+            self._data = bytearray()
+            self._pkglen = BMS.HEAD_LEN + BMS.CRC_LEN
+
+        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) < self._pkglen:
+            return
+
+        if (crc := crc_modbus(self._data[: self._pkglen - 2])) != int.from_bytes(
+            self._data[self._pkglen - 2 : self._pkglen], "little"
+        ):
+            self._log.debug(
+                "invalid checksum 0x%X != 0x%X",
+                int.from_bytes(self._data[self._pkglen - 2 : self._pkglen], "little"),
+                crc,
+            )
+            self._data = bytearray()
+            return
+
+        if self._data[2] >> 1 not in BMS._CMDS or self._data[1] & 0x80:
+            self._log.debug(
+                "unknown message: %s, length: %s", self._data[0:2], self._data[2]
+            )
+            self._data = bytearray()
+            return
+
+        if len(self._data) != self._pkglen:
+            self._log.debug(
+                "wrong data length (%i!=%s): %s",
+                len(self._data),
+                self._pkglen,
+                self._data,
+            )
+
+        self._data_final[self._data[0] << 8 | self._data[2] >> 1] = self._data
+        self._data = bytearray()
+        self._data_event.set()
+
+    async def _init_connection(
+        self, char_notify: BleakGATTCharacteristic | int | str | None = None
+    ) -> None:
+        """Initialize RX/TX characteristics."""
+        await super()._init_connection()
+        self._pack_count = 0
+        self._pkglen = 0
+
+    @staticmethod
+    def _swap32(value: int, signed: bool = False) -> int:
+        """Swap high and low 16bit in 32bit integer."""
+
+        value = ((value >> 16) & 0xFFFF) | (value & 0xFFFF) << 16
+        if signed and value & 0x80000000:
+            value = -0x100000000 + value
+        return value
+
+    @staticmethod
+    def _cmd(device: int, cmd: int, start: int, count: int) -> bytes:
+        """Assemble a Seplos BMS command."""
+        assert device >= 0x00 and (device <= 0x10 or device in (0xC0, 0xE0))
+        assert cmd in (0x01, 0x04)  # allow only read commands
+        assert start >= 0 and count > 0 and start + count <= 0xFFFF
+        frame: bytearray = bytearray([device, cmd])
+        frame += int.to_bytes(start, 2, byteorder="big")
+        frame += int.to_bytes(count * (0x10 if cmd == 0x1 else 0x1), 2, byteorder="big")
+        frame += int.to_bytes(crc_modbus(frame), 2, byteorder="little")
+        return bytes(frame)
+
+    async def _async_update(self) -> BMSsample:
+        """Update battery status information."""
+        for block in BMS.QUERY.values():
+            await self._await_reply(BMS._cmd(0x0, *block))
+
+        data: BMSsample = BMS._decode_data(
+            BMS._FIELDS, self._data_final, offset=BMS.HEAD_LEN
+        )
+
+        self._pack_count = min(data.get("pack_count", 0), 0x10)
+
+        for pack in range(1, 1 + self._pack_count):
+            for block in BMS.PQUERY.values():
+                await self._await_reply(self._cmd(pack, *block))
+
+            for key, idx, sign, func in BMS._PFIELDS:
+                data.setdefault(key, []).append(
+                    func(
+                        int.from_bytes(
+                            self._data_final[pack << 8 | BMS.PIA_LEN][
+                                BMS.HEAD_LEN + idx : BMS.HEAD_LEN + idx + 2
+                            ],
+                            byteorder="big",
+                            signed=sign,
+                        )
+                    )
+                )
+
+            pack_cells: list[float] = BMS._cell_voltages(
+                self._data_final[pack << 8 | BMS.PIB_LEN], cells=16, start=BMS.HEAD_LEN
+            )
+            # update per pack delta voltage
+            data["delta_voltage"] = max(
+                data.get("delta_voltage", 0),
+                round(max(pack_cells) - min(pack_cells), 3),
+            )
+            # add individual cell voltages
+            data.setdefault("cell_voltages", []).extend(pack_cells)
+            # add temperature sensors (4x cell temperature + 4 reserved)
+            data.setdefault("temp_values", []).extend(
+                BMS._temp_values(
+                    self._data_final[pack << 8 | BMS.PIB_LEN],
+                    values=4,
+                    start=BMS._TEMP_START,
+                    signed=False,
+                    offset=2731,
+                    divider=10,
+                )
+            )
+
+        self._data_final.clear()
+
+        return data