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

aiobmsble/bms/ogt_bms.py

@@ -0,0 +1,218 @@
+"""Module to support Offgridtec Smart Pro BMS.
+
+Project: aiobmsble, https://pypi.org/p/aiobmsble/
+License: Apache-2.0, http://www.apache.org/licenses/
+"""
+
+from collections.abc import Callable
+from string import digits, hexdigits
+from typing import Any, Final, NamedTuple
+
+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):
+    """Offgridtec LiFePO4 Smart Pro type A and type B BMS implementation."""
+
+    _IDX_NAME: Final = 0
+    _IDX_LEN: Final = 1
+    _IDX_FCT: Final = 2
+    # magic crypt sequence of length 16
+    _CRYPT_SEQ: Final[list[int]] = [2, 5, 4, 3, 1, 4, 1, 6, 8, 3, 7, 2, 5, 8, 9, 3]
+
+    class _Response(NamedTuple):
+        valid: bool
+        reg: int
+        value: int
+
+    def __init__(self, ble_device: BLEDevice, reconnect: bool = False) -> None:
+        """Intialize private BMS members."""
+        super().__init__(ble_device, reconnect)
+        self._type: str = (
+            self.name[9]
+            if len(self.name) >= 10 and set(self.name[10:]).issubset(digits)
+            else "?"
+        )
+        self._key: int = (
+            sum(BMS._CRYPT_SEQ[int(c, 16)] for c in (f"{int(self.name[10:]):0>4X}"))
+            if self._type in "AB"
+            else 0
+        ) + (5 if (self._type == "A") else 8)
+        self._log.info(
+            "%s type: %c, ID: %s, key: 0x%X",
+            self.device_id(),
+            self._type,
+            self.name[10:],
+            self._key,
+        )
+        self._exp_reply: int = 0x0
+        self._response: BMS._Response = BMS._Response(False, 0, 0)
+        self._REGISTERS: dict[int, tuple[BMSvalue, int, Callable[[int], Any]]]
+        if self._type == "A":
+            self._REGISTERS = {
+                # SOC (State of Charge)
+                2: ("battery_level", 1, lambda x: x),
+                4: ("cycle_charge", 3, lambda x: x / 1000),
+                8: ("voltage", 2, lambda x: x / 1000),
+                # MOS temperature
+                12: ("temperature", 2, lambda x: round(x * 0.1 - 273.15, 1)),
+                # 3rd byte of current is 0 (should be 1 as for B version)
+                16: ("current", 3, lambda x: x / 100),
+                24: ("runtime", 2, lambda x: x * 60),
+                44: ("cycles", 2, lambda x: x),
+                # Type A batteries have no cell voltage registers
+            }
+            self._HEADER = "+RAA"
+        elif self._type == "B":
+            self._REGISTERS = {
+                # MOS temperature
+                8: ("temperature", 2, lambda x: round(x * 0.1 - 273.15, 1)),
+                9: ("voltage", 2, lambda x: x / 1000),
+                10: ("current", 3, lambda x: x / 1000),
+                # SOC (State of Charge)
+                13: ("battery_level", 1, lambda x: x),
+                15: ("cycle_charge", 3, lambda x: x / 1000),
+                18: ("runtime", 2, lambda x: x * 60),
+                23: ("cycles", 2, lambda x: x),
+            }
+            # add cell voltage registers, note: need to be last!
+            self._HEADER = "+R16"
+        else:
+            self._REGISTERS = {}
+            self._log.exception("unkown device type '%c'", self._type)
+
+    @staticmethod
+    def matcher_dict_list() -> list[MatcherPattern]:
+        """Return a list of Bluetooth matchers."""
+        return [
+            {
+                "local_name": "SmartBat-[AB]*",
+                "service_uuid": BMS.uuid_services()[0],
+                "connectable": True,
+            }
+        ]
+
+    @staticmethod
+    def device_info() -> dict[str, str]:
+        """Return a dictionary of device information."""
+        return {"manufacturer": "Offgridtec", "model": "LiFePo4 Smart Pro"}
+
+    @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 "fff6"
+
+    @staticmethod
+    def _calc_values() -> frozenset[BMSvalue]:
+        return frozenset(
+            {"cycle_capacity", "power", "battery_charging", "delta_voltage"}
+        )
+
+    def _notification_handler(
+        self, _sender: BleakGATTCharacteristic, data: bytearray
+    ) -> None:
+        self._log.debug("RX BLE data: %s", data)
+
+        self._response = self._ogt_response(data)
+
+        # check that descrambled message is valid
+        if not self._response.valid:
+            self._log.debug("response data is invalid")
+            return
+
+        if self._response.reg not in (-1, self._exp_reply):
+            self._log.debug("wrong register response")
+            return
+
+        self._exp_reply = -1
+        self._data_event.set()
+
+    def _ogt_response(self, resp: bytearray) -> _Response:
+        """Descramble a response from the BMS."""
+
+        try:
+            msg: Final[str] = bytearray(
+                (resp[x] ^ self._key) for x in range(len(resp))
+            ).decode(encoding="ascii")
+        except UnicodeDecodeError:
+            return BMS._Response(False, -1, 0)
+
+        self._log.debug("response: %s", msg.rstrip("\r\n"))
+        # verify correct response
+        if len(msg) < 8 or not msg.startswith("+RD,"):
+            return BMS._Response(False, -1, 0)
+        if msg[4:7] == "Err":
+            return BMS._Response(True, -1, 0)
+        if not msg.endswith("\r\n") or not all(c in hexdigits for c in msg[4:-2]):
+            return BMS._Response(False, -1, 0)
+
+        # 16-bit value in network order (plus optional multiplier for 24-bit values)
+        # multiplier has 1 as minimum due to current value in A type battery
+        signed: bool = len(msg) > 12
+        value: int = int.from_bytes(
+            bytes.fromhex(msg[6:10]), byteorder="little", signed=signed
+        ) * (max(int(msg[10:12], 16), 1) if signed else 1)
+        return BMS._Response(True, int(msg[4:6], 16), value)
+
+    def _ogt_command(self, reg: int, length: int) -> bytes:
+        """Put together an scambled query to the BMS."""
+
+        cmd: Final[str] = f"{self._HEADER}{reg:0>2X}{length:0>2X}"
+        self._log.debug("command: %s", cmd)
+
+        return bytes(ord(cmd[i]) ^ self._key for i in range(len(cmd)))
+
+    async def _async_update(self) -> BMSsample:
+        """Update battery status information."""
+        result: BMSsample = {}
+
+        for reg in list(self._REGISTERS):
+            self._exp_reply = reg
+            await self._await_reply(
+                data=self._ogt_command(reg, self._REGISTERS[reg][BMS._IDX_LEN])
+            )
+            if self._response.reg < 0:
+                raise TimeoutError
+
+            name, _length, func = self._REGISTERS[self._response.reg]
+            result[name] = func(self._response.value)
+            self._log.debug(
+                "decoded data: reg: %s (#%i), raw: %i, value: %f",
+                name,
+                reg,
+                self._response.value,
+                result.get(name),
+            )
+
+        # read cell voltages for type B battery
+        if self._type == "B":
+            for cell_reg in range(16):
+                self._exp_reply = 63 - cell_reg
+                await self._await_reply(data=self._ogt_command(63 - cell_reg, 2))
+                if self._response.reg < 0:
+                    self._log.debug("cell count: %i", cell_reg)
+                    break
+                result.setdefault("cell_voltages", []).append(
+                    self._response.value / 1000
+                )
+
+        # remove remaining runtime if battery is charging
+        if result.get("runtime") == 0xFFFF * 60:
+            del result["runtime"]
+
+        return result

aiobmsble/bms/pro_bms.py

@@ -0,0 +1,148 @@
+"""Module to support Pro 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
+
+
+class BMS(BaseBMS):
+    """Pro BMS Smart Shunt class implementation."""
+
+    _HEAD: Final[bytes] = bytes([0x55, 0xAA])
+    _MIN_LEN: Final[int] = 5
+    _INIT_RESP: Final[int] = 0x03
+    _RT_DATA: Final[int] = 0x04
+
+    # Commands from btsnoop capture
+    _CMD_INIT: Final[bytes] = bytes.fromhex("55aa0a0101558004077f648e682b")
+    _CMD_ACK: Final[bytes] = bytes.fromhex("55aa070101558040000095")
+    _CMD_DATA_STREAM: Final[bytes] = bytes.fromhex("55aa070101558042000097")
+    # command that triggers data streaming (Function 0x43)
+    _CMD_TRIGGER_DATA: Final[bytes] = bytes.fromhex("55aa0901015580430000120084")
+
+    _FIELDS: Final[tuple[BMSdp, ...]] = (
+        BMSdp("voltage", 8, 2, False, lambda x: x / 100),
+        BMSdp(
+            "current",
+            12,
+            4,
+            False,
+            lambda x: ((x & 0xFFFF) / 1000) * (-1 if (x >> 24) & 0x80 else 1),
+        ),
+        BMSdp("problem_code", 15, 4, False, lambda x: x & 0x7F),
+        BMSdp(
+            "temperature",
+            16,
+            3,
+            False,
+            lambda x: ((x & 0xFFFF) / 10) * (-1 if x >> 16 else 1),
+        ),
+        BMSdp("cycle_charge", 20, 4, False, lambda x: x / 100),
+        BMSdp("battery_level", 24, 1, False, lambda x: x),
+        BMSdp("power", 32, 4, False, lambda x: x / 100),
+    )
+
+    def __init__(self, ble_device: BLEDevice, reconnect: bool = False) -> None:
+        """Initialize private BMS members."""
+        super().__init__(ble_device, reconnect)
+        self._valid_reply: int = BMS._RT_DATA
+
+    @staticmethod
+    def matcher_dict_list() -> list[MatcherPattern]:
+        """Provide BluetoothMatcher definition."""
+        return [
+            MatcherPattern(
+                local_name="Pro BMS",
+                service_uuid=BMS.uuid_services()[0],
+                connectable=True,
+            )
+        ]
+
+    @staticmethod
+    def device_info() -> dict[str, str]:
+        """Return device information for the battery management system."""
+        return {"manufacturer": "Pro BMS", "model": "Smart Shunt"}
+
+    @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", "runtime"})
+
+    def _notification_handler(
+        self, _sender: BleakGATTCharacteristic, data: bytearray
+    ) -> None:
+        self._log.debug("RX BLE data: %s", data)
+
+        if len(data) < BMS._MIN_LEN or not data.startswith(BMS._HEAD):
+            self._log.debug("Invalid packet header")
+            return
+
+        if data[3] != self._valid_reply:
+            self._log.debug("unexpected response (type 0x%X)", data[3])
+            return
+
+        if len(data) != data[2] + BMS._MIN_LEN:
+            self._log.debug("incorrect frame length: %i).", len(self._data))
+            return
+
+        self._data = data
+        self._data_event.set()
+
+    async def _init_connection(
+        self, char_notify: BleakGATTCharacteristic | int | str | None = None
+    ) -> None:
+        """Initialize RX/TX characteristics and protocol state."""
+        await super()._init_connection()
+        self._valid_reply = BMS._INIT_RESP
+
+        # Step 1: Send initialization command and await response
+        await self._await_reply(BMS._CMD_INIT)
+
+        # Step 2: Send ACK command
+        # Step 3: Send data stream command
+        # Step 4: Send trigger data command 0x43 - start RT data stream
+        for cmd in (BMS._CMD_ACK, BMS._CMD_DATA_STREAM, BMS._CMD_TRIGGER_DATA):
+            await self._await_reply(cmd, wait_for_notify=False)
+
+        self._valid_reply = BMS._RT_DATA
+
+    async def _async_update(self) -> BMSsample:
+        """Update battery status information."""
+
+        self._data_event.clear()  # Clear the event to ensure fresh data on each update
+        try:
+            # Wait for new data packet
+            await asyncio.wait_for(self._wait_event(), timeout=BMS.TIMEOUT)
+        except TimeoutError:
+            await self.disconnect()
+            raise
+
+        result: BMSsample = BMS._decode_data(
+            BMS._FIELDS, self._data, byteorder="little"
+        )
+        result["power"] *= -1 if result["current"] < 0 else 1
+        return result

aiobmsble/bms/redodo_bms.py

@@ -0,0 +1,131 @@
+"""Module to support Redodo 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):
+    """Redodo BMS implementation."""
+
+    _HEAD_LEN: Final[int] = 3
+    _MAX_CELLS: Final[int] = 16
+    _MAX_TEMP: Final[int] = 3
+    _FIELDS: Final[tuple[BMSdp, ...]] = (
+        BMSdp("voltage", 12, 2, False, lambda x: x / 1000),
+        BMSdp("current", 48, 4, True, lambda x: x / 1000),
+        BMSdp("battery_level", 90, 2, False, lambda x: x),
+        BMSdp("cycle_charge", 62, 2, False, lambda x: x / 100),
+        BMSdp("cycles", 96, 4, False, lambda x: x),
+        BMSdp("problem_code", 76, 4, False, lambda x: x),
+    )
+
+    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 [
+            {  # patterns required to exclude "BT-ROCC2440"
+                "local_name": pattern,
+                "service_uuid": BMS.uuid_services()[0],
+                "manufacturer_id": 0x585A,
+                "connectable": True,
+            }
+            for pattern in (
+                "R-12*",
+                "R-24*",
+                "RO-12*",
+                "RO-24*",
+                "P-12*",
+                "P-24*",
+                "PQ-12*",
+                "PQ-24*",
+                "L-12*",  # vv *** LiTime *** vv
+                "L-24*",
+                "L-51*",
+                "LT-12???BG-A0[7-9]*",  # LiTime based on ser#
+                "LT-51*",
+            )
+        ]
+
+    @staticmethod
+    def device_info() -> dict[str, str]:
+        """Return device information for the battery management system."""
+        return {"manufacturer": "Redodo", "model": "Bluetooth battery"}
+
+    @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 "ffe2"
+
+    @staticmethod
+    def _calc_values() -> frozenset[BMSvalue]:
+        return frozenset(
+            {
+                "battery_charging",
+                "delta_voltage",
+                "cycle_capacity",
+                "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 len(data) < 3 or not data.startswith(b"\x00\x00"):
+            self._log.debug("incorrect SOF.")
+            return
+
+        if len(data) != data[2] + BMS._HEAD_LEN + 1:  # add header length and CRC
+            self._log.debug("incorrect frame length (%i)", len(data))
+            return
+
+        if (crc := crc_sum(data[:-1])) != data[-1]:
+            self._log.debug("invalid checksum 0x%X != 0x%X", data[len(data) - 1], crc)
+            return
+
+        self._data = data
+        self._data_event.set()
+
+    async def _async_update(self) -> BMSsample:
+        """Update battery status information."""
+        await self._await_reply(b"\x00\x00\x04\x01\x13\x55\xaa\x17")
+
+        result: BMSsample = BMS._decode_data(
+            BMS._FIELDS, self._data, byteorder="little"
+        )
+        result["cell_voltages"] = BMS._cell_voltages(
+            self._data, cells=BMS._MAX_CELLS, start=16, byteorder="little"
+        )
+        result["temp_values"] = BMS._temp_values(
+            self._data, values=BMS._MAX_TEMP, start=52, byteorder="little"
+        )
+
+        return result

aiobmsble/bms/renogy_bms.py

@@ -0,0 +1,152 @@
+"""Module to support Renogy BMS.
+
+Project: aiobmsble, https://pypi.org/p/aiobmsble/
+"""
+
+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):
+    """Renogy battery class implementation."""
+
+    HEAD: bytes = b"\x30\x03"  # SOP, read fct (x03)
+    _CRC_POS: Final[int] = -2
+    _TEMP_POS: Final[int] = 37
+    _CELL_POS: Final[int] = 3
+    FIELDS: tuple[BMSdp, ...] = (
+        BMSdp("voltage", 5, 2, False, lambda x: x / 10),
+        BMSdp("current", 3, 2, True, lambda x: x / 100),
+        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:
+        """Initialize BMS."""
+        super().__init__(ble_device, reconnect)
+
+    @staticmethod
+    def matcher_dict_list() -> list[MatcherPattern]:
+        """Provide BluetoothMatcher definition."""
+        return [
+            {
+                "service_uuid": BMS.uuid_services()[0],
+                "manufacturer_id": 0x9860,
+                "connectable": True,
+            },
+        ]
+
+    @staticmethod
+    def device_info() -> dict[str, str]:
+        """Return device information for the battery management system."""
+        return {"manufacturer": "Renogy", "model": "Bluetooth battery"}
+
+    @staticmethod
+    def uuid_services() -> list[str]:
+        """Return list of 128-bit UUIDs of services required by BMS."""
+        return [normalize_uuid_str("ffd0"), 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 "ffd1"
+
+    @staticmethod
+    def _calc_values() -> frozenset[BMSvalue]:
+        return frozenset(
+            {
+                "power",
+                "battery_charging",
+                "temperature",
+                "cycle_capacity",
+                "battery_level",
+                "runtime",
+                "delta_voltage",
+            }
+        )  # 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) or len(data) < 3:
+            self._log.debug("incorrect SOF")
+            return
+
+        if data[2] + 5 != len(data):
+            self._log.debug("incorrect frame length: %i != %i", len(data), data[2] + 5)
+            return
+
+        if (crc := crc_modbus(data[: BMS._CRC_POS])) != int.from_bytes(
+            data[BMS._CRC_POS :], "little"
+        ):
+            self._log.debug(
+                "invalid checksum 0x%X != 0x%X",
+                crc,
+                int.from_bytes(data[BMS._CRC_POS :], "little"),
+            )
+            return
+
+        self._data = data.copy()
+        self._data_event.set()
+
+    @staticmethod
+    def _read_int16(data: bytearray, pos: int, signed: bool = False) -> int:
+        return int.from_bytes(data[pos : pos + 2], byteorder="big", signed=signed)
+
+    @staticmethod
+    def _cmd(addr: int, words: int) -> bytes:
+        """Assemble a Renogy BMS command (MODBUS)."""
+        frame: bytearray = (
+            bytearray(BMS.HEAD)
+            + int.to_bytes(addr, 2, byteorder="big")
+            + int.to_bytes(words, 2, byteorder="big")
+        )
+
+        frame.extend(int.to_bytes(crc_modbus(frame), 2, byteorder="little"))
+        return bytes(frame)
+
+    async def _async_update(self) -> BMSsample:
+        """Update battery status information."""
+
+        await self._await_reply(self._cmd(0x13B2, 0x7))
+        result: BMSsample = BMS._decode_data(type(self).FIELDS, self._data)
+
+        await self._await_reply(self._cmd(0x1388, 0x22))
+        result["cell_count"] = BMS._read_int16(self._data, BMS._CELL_POS)
+        result["cell_voltages"] = BMS._cell_voltages(
+            self._data,
+            cells=min(16, result.get("cell_count", 0)),
+            start=BMS._CELL_POS + 2,
+            byteorder="big",
+            divider=10,
+        )
+
+        result["temp_sensors"] = BMS._read_int16(self._data, BMS._TEMP_POS)
+        result["temp_values"] = BMS._temp_values(
+            self._data,
+            values=min(16, result.get("temp_sensors", 0)),
+            start=BMS._TEMP_POS + 2,
+            divider=10,
+        )
+
+        await self._await_reply(self._cmd(0x13EC, 0x7))
+        result["problem_code"] = int.from_bytes(self._data[3:-2], byteorder="big") & (
+            ~0xE
+        )
+
+        return result