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

aiobmsble/bms/ej_bms.py

@@ -0,0 +1,237 @@
+"""Module to support E&J Technology BMS.
+
+Project: aiobmsble, https://pypi.org/p/aiobmsble/
+License: Apache-2.0, http://www.apache.org/licenses/
+"""
+
+from enum import IntEnum
+from string import hexdigits
+from typing import Final, Literal
+
+from bleak.backends.characteristic import BleakGATTCharacteristic
+from bleak.backends.device import BLEDevice
+
+from aiobmsble import BMSdp, BMSsample, BMSvalue, MatcherPattern
+from aiobmsble.basebms import BaseBMS
+
+
+class Cmd(IntEnum):
+    """BMS operation codes."""
+
+    RT = 0x2
+    CAP = 0x10
+
+
+class BMS(BaseBMS):
+    """E&J Technology BMS implementation."""
+
+    _BT_MODULE_MSG: Final[bytes] = bytes([0x41, 0x54, 0x0D, 0x0A])  # BLE module message
+    _IGNORE_CRC: Final[str] = "libattU"
+    _HEAD: Final[bytes] = b"\x3a"
+    _TAIL: Final[bytes] = b"\x7e"
+    _MAX_CELLS: Final[int] = 16
+    _FIELDS: Final[tuple[BMSdp, ...]] = (
+        BMSdp(
+            "current", 89, 8, False, lambda x: ((x >> 16) - (x & 0xFFFF)) / 100, Cmd.RT
+        ),
+        BMSdp("battery_level", 123, 2, False, lambda x: x, Cmd.RT),
+        BMSdp("cycle_charge", 15, 4, False, lambda x: x / 10, Cmd.CAP),
+        BMSdp(
+            "temperature", 97, 2, False, lambda x: x - 40, Cmd.RT
+        ),  # only 1st sensor relevant
+        BMSdp("cycles", 115, 4, False, lambda x: x, Cmd.RT),
+        BMSdp(
+            "problem_code", 105, 4, False, lambda x: x & 0x0FFC, Cmd.RT
+        ),  # mask status bits
+    )
+
+    def __init__(self, ble_device: BLEDevice, reconnect: bool = False) -> None:
+        """Initialize BMS."""
+        super().__init__(ble_device, reconnect)
+        self._data_final: bytearray = bytearray()
+
+    @staticmethod
+    def matcher_dict_list() -> list[MatcherPattern]:
+        """Provide BluetoothMatcher definition."""
+        return (
+            [  # Lithtech Energy (2x), Volthium
+                MatcherPattern(local_name=pattern, connectable=True)
+                for pattern in ("L-12V???AH-*", "LT-12V-*", "V-12V???Ah-*")
+            ]
+            + [  # Fliteboard, Electronix battery
+                {
+                    "local_name": "libatt*",
+                    "manufacturer_id": 21320,
+                    "connectable": True,
+                },
+                {"local_name": "SV12V*", "manufacturer_id": 33384, "connectable": True},
+                {"local_name": "LT-24*", "manufacturer_id": 22618, "connectable": True},
+            ]
+            + [  # LiTime
+                MatcherPattern(  # LiTime based on ser#
+                    local_name="LT-12???BG-A0[0-6]*",
+                    manufacturer_id=m_id,
+                    connectable=True,
+                )
+                for m_id in (33384, 22618)
+            ]
+        )
+
+    @staticmethod
+    def device_info() -> dict[str, str]:
+        """Return device information for the battery management system."""
+        return {"manufacturer": "E&J Technology", "model": "Smart BMS"}
+
+    @staticmethod
+    def uuid_services() -> list[str]:
+        """Return list of 128-bit UUIDs of services required by BMS."""
+        return ["6e400001-b5a3-f393-e0a9-e50e24dcca9e"]
+
+    @staticmethod
+    def uuid_rx() -> str:
+        """Return 128-bit UUID of characteristic that provides notification/read property."""
+        return "6e400003-b5a3-f393-e0a9-e50e24dcca9e"
+
+    @staticmethod
+    def uuid_tx() -> str:
+        """Return 128-bit UUID of characteristic that provides write property."""
+        return "6e400002-b5a3-f393-e0a9-e50e24dcca9e"
+
+    @staticmethod
+    def _calc_values() -> frozenset[BMSvalue]:
+        return frozenset(
+            {
+                "battery_charging",
+                "cycle_capacity",
+                "delta_voltage",
+                "power",
+                "runtime",
+                "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)."""
+
+        if data.startswith(BMS._BT_MODULE_MSG):
+            self._log.debug("filtering AT cmd")
+            if not (data := data.removeprefix(BMS._BT_MODULE_MSG)):
+                return
+
+        if data.startswith(BMS._HEAD):  # check for beginning of frame
+            self._data.clear()
+
+        self._data += data
+
+        self._log.debug(
+            "RX BLE data (%s): %s", "start" if data == self._data else "cnt.", data
+        )
+
+        exp_frame_len: Final[int] = (
+            int(self._data[7:11], 16)
+            if len(self._data) > 10
+            and all(chr(c) in hexdigits for c in self._data[7:11])
+            else 0xFFFF
+        )
+
+        if not self._data.startswith(BMS._HEAD) or (
+            not self._data.endswith(BMS._TAIL) and len(self._data) < exp_frame_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 len(self._data) != exp_frame_len:
+            self._log.debug(
+                "incorrect frame length %i != %i",
+                len(self._data),
+                exp_frame_len,
+            )
+            self._data.clear()
+            return
+
+        if not self.name.startswith(BMS._IGNORE_CRC) and (
+            crc := BMS._crc(self._data[1:-3])
+        ) != int(self._data[-3:-1], 16):
+            # libattU firmware uses no CRC, so we ignore it
+            self._log.debug(
+                "invalid checksum 0x%X != 0x%X", int(self._data[-3:-1], 16), crc
+            )
+            self._data.clear()
+            return
+
+        self._log.debug(
+            "address: 0x%X, command 0x%X, version: 0x%X, length: 0x%X",
+            int(self._data[1:3], 16),
+            int(self._data[3:5], 16) & 0x7F,
+            int(self._data[5:7], 16),
+            len(self._data),
+        )
+        self._data_final = self._data.copy()
+        self._data_event.set()
+
+    @staticmethod
+    def _crc(data: bytearray) -> int:
+        return (sum(data) ^ 0xFF) & 0xFF
+
+    @staticmethod
+    def _cell_voltages(
+        data: bytearray,
+        *,
+        cells: int,
+        start: int,
+        size: int = 2,
+        byteorder: Literal["little", "big"] = "big",
+        divider: int = 1000,
+    ) -> list[float]:
+        """Return cell voltages from status message."""
+        return [
+            (value / divider)
+            for idx in range(cells)
+            if (value := int(data[start + size * idx : start + size * (idx + 1)], 16))
+        ]
+
+    @staticmethod
+    def _conv_data(data: dict[int, bytearray]) -> BMSsample:
+        result: BMSsample = {}
+        for field in BMS._FIELDS:
+            result[field.key] = field.fct(
+                int(data[field.idx][field.pos : field.pos + field.size], 16)
+            )
+        return result
+
+    async def _async_update(self) -> BMSsample:
+        """Update battery status information."""
+        raw_data: dict[int, bytearray] = {}
+
+        # query real-time information and capacity
+        for cmd in (b":000250000E03~", b":001031000E05~"):
+            await self._await_reply(cmd)
+            rsp: int = int(self._data_final[3:5], 16) & 0x7F
+            raw_data[rsp] = self._data_final
+            if rsp == Cmd.RT and len(self._data_final) == 0x8C:
+                # handle metrisun version
+                self._log.debug("single frame protocol detected")
+                raw_data[Cmd.CAP] = bytearray(15) + self._data_final[125:]
+                break
+
+        if len(raw_data) != len(list(Cmd)) or not all(
+            len(value) > 0 for value in raw_data.values()
+        ):
+            return {}
+
+        return self._conv_data(raw_data) | {
+            "cell_voltages": BMS._cell_voltages(
+                raw_data[Cmd.RT], cells=BMS._MAX_CELLS, start=25, size=4
+            )
+        }

aiobmsble/bms/felicity_bms.py

@@ -0,0 +1,143 @@
+"""Module to support Felicity BMS.
+
+Project: aiobmsble, https://pypi.org/p/aiobmsble/
+License: Apache-2.0, http://www.apache.org/licenses/
+"""
+
+from collections.abc import Callable
+from json import JSONDecodeError, loads
+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 BMSsample, BMSvalue, MatcherPattern
+from aiobmsble.basebms import BaseBMS
+
+
+class BMS(BaseBMS):
+    """Felicity BMS implementation."""
+
+    _HEAD: Final[bytes] = b"{"
+    _TAIL: Final[bytes] = b"}"
+    _CMD_PRE: Final[bytes] = b"wifilocalMonitor:"  # CMD prefix
+    _CMD_BI: Final[bytes] = b"get dev basice infor"
+    _CMD_DT: Final[bytes] = b"get Date"
+    _CMD_RT: Final[bytes] = b"get dev real infor"
+    _FIELDS: Final[list[tuple[BMSvalue, str, Callable[[list], Any]]]] = [
+        ("voltage", "Batt", lambda x: x[0][0] / 1000),
+        ("current", "Batt", lambda x: x[1][0] / 10),
+        (
+            "cycle_charge",
+            "BatsocList",
+            lambda x: (int(x[0][0]) * int(x[0][2])) / 1e7,
+        ),
+        ("battery_level", "BatsocList", lambda x: x[0][0] / 100),
+    ]
+
+    def __init__(self, ble_device: BLEDevice, reconnect: bool = False) -> None:
+        """Initialize BMS."""
+        super().__init__(ble_device, reconnect)
+        self._data_final: dict = {}
+
+    @staticmethod
+    def matcher_dict_list() -> list[MatcherPattern]:
+        """Provide BluetoothMatcher definition."""
+        return [
+            {"local_name": pattern, "connectable": True} for pattern in ("F07*", "F10*")
+        ]
+
+    @staticmethod
+    def device_info() -> dict[str, str]:
+        """Return device information for the battery management system."""
+        return {"manufacturer": "Felicity Solar", "model": "LiFePo4 battery"}
+
+    @staticmethod
+    def uuid_services() -> list[str]:
+        """Return list of 128-bit UUIDs of services required by BMS."""
+        return [normalize_uuid_str("6e6f736a-4643-4d44-8fa9-0fafd005e455")]
+
+    @staticmethod
+    def uuid_rx() -> str:
+        """Return 128-bit UUID of characteristic that provides notification/read property."""
+        return "49535458-8341-43f4-a9d4-ec0e34729bb3"
+
+    @staticmethod
+    def uuid_tx() -> str:
+        """Return 128-bit UUID of characteristic that provides write property."""
+        return "49535258-184d-4bd9-bc61-20c647249616"
+
+    @staticmethod
+    def _calc_values() -> frozenset[BMSvalue]:
+        return frozenset(
+            {
+                "battery_charging",
+                "cycle_capacity",
+                "delta_voltage",
+                "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)."""
+
+        if data.startswith(BMS._HEAD):
+            self._data = bytearray()
+
+        self._data += data
+        self._log.debug(
+            "RX BLE data (%s): %s", "start" if data == self._data else "cnt.", data
+        )
+
+        if not data.endswith(BMS._TAIL):
+            return
+
+        try:
+            self._data_final = loads(self._data)
+        except (JSONDecodeError, UnicodeDecodeError):
+            self._log.debug("JSON decode error: %s", self._data)
+            return
+
+        if (ver := self._data_final.get("CommVer", 0)) != 1:
+            self._log.debug("Unknown protocol version (%i)", ver)
+            return
+
+        self._data_event.set()
+
+    @staticmethod
+    def _conv_data(data: dict) -> BMSsample:
+        result: BMSsample = {}
+        for key, itm, func in BMS._FIELDS:
+            result[key] = func(data.get(itm, []))
+        return result
+
+    @staticmethod
+    def _conv_cells(data: dict) -> list[float]:
+        return [(value / 1000) for value in data.get("BatcelList", [])[0]]
+
+    @staticmethod
+    def _conv_temp(data: dict) -> list[float]:
+        return [
+            (value / 10) for value in data.get("BtemList", [])[0] if value != 0x7FFF
+        ]
+
+    async def _async_update(self) -> BMSsample:
+        """Update battery status information."""
+
+        await self._await_reply(BMS._CMD_PRE + BMS._CMD_RT)
+
+        return (
+            BMS._conv_data(self._data_final)
+            | {"temp_values": BMS._conv_temp(self._data_final)}
+            | {"cell_voltages": BMS._conv_cells(self._data_final)}
+            | {
+                "problem_code": int(
+                    self._data_final.get("Bwarn", 0) + self._data_final.get("Bfault", 0)
+                )
+            }
+        )

aiobmsble/bms/jbd_bms.py

@@ -0,0 +1,207 @@
+"""Module to support JBD 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
+
+
+class BMS(BaseBMS):
+    """JBD Smart BMS class implementation."""
+
+    HEAD_RSP: Final[bytes] = bytes([0xDD])  # header for responses
+    HEAD_CMD: Final[bytes] = bytes([0xDD, 0xA5])  # read header for commands
+    TAIL: Final[int] = 0x77  # tail for command
+    INFO_LEN: Final[int] = 7  # minimum frame size
+    BASIC_INFO: Final[int] = 23  # basic info data length
+    _FIELDS: Final[tuple[BMSdp, ...]] = (
+        BMSdp("temp_sensors", 26, 1, False, lambda x: x),  # count is not limited
+        BMSdp("voltage", 4, 2, False, lambda x: x / 100),
+        BMSdp("current", 6, 2, True, lambda x: x / 100),
+        BMSdp("battery_level", 23, 1, False, lambda x: x),
+        BMSdp("cycle_charge", 8, 2, False, lambda x: x / 100),
+        BMSdp("cycles", 12, 2, False, lambda x: x),
+        BMSdp("problem_code", 20, 2, False, lambda x: x),
+    )  # general protocol v4
+
+    def __init__(self, ble_device: BLEDevice, reconnect: bool = False) -> None:
+        """Intialize private BMS members."""
+        super().__init__(ble_device, reconnect)
+        self._valid_reply: int = 0x00
+        self._data_final: bytearray = bytearray()
+
+    @staticmethod
+    def matcher_dict_list() -> list[MatcherPattern]:
+        """Provide BluetoothMatcher definition."""
+        return [
+            MatcherPattern(
+                local_name=pattern,
+                service_uuid=BMS.uuid_services()[0],
+                connectable=True,
+            )
+            for pattern in (
+                "JBD-*",
+                "SP0?S*",
+                "SP1?S*",
+                "SP2?S*",
+                "AP2?S*",
+                "GJ-*",  # accurat batteries
+                "SX1*",  # Supervolt v3
+                "DP04S*",  # ECO-WORTHY, DCHOUSE
+                "ECO-LFP*",  # ECO-WORTHY rack (use m_id?)
+                "121?0*",  # Eleksol, Ultimatron
+                "12200*",
+                "12300*",
+                "SBL-*",  # SBL
+                "LT40AH",  # LionTron
+                "PKT*",  # Perfektium
+                "gokwh*",
+                "OGR-*",  # OGRPHY
+                "DWC*",  # Vatrer
+                "DXD*",  # Vatrer
+                "xiaoxiang*",  # xiaoxiang BMS
+                "AL12-*",  # Aolithium
+                "BS20*",  # BasenGreen
+                "BT  LP*",  # LANPWR
+            )
+        ] + [
+            MatcherPattern(
+                service_uuid=BMS.uuid_services()[0],
+                manufacturer_id=m_id,
+                connectable=True,
+            )
+            for m_id in (0x0211, 0x3E70, 0xC1A4)
+            # Liontron, LISMART1240LX/LISMART1255LX,
+            # LionTron XL19110253 / EPOCH batteries 12.8V 460Ah - 12460A-H
+        ]
+
+    @staticmethod
+    def device_info() -> dict[str, str]:
+        """Return device information for the battery management system."""
+        return {"manufacturer": "Jiabaida", "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 basic info (0x3) or cell block info (0x4)
+        if (
+            data.startswith(self.HEAD_RSP)
+            and len(self._data) > self.INFO_LEN
+            and data[1] in (0x03, 0x04)
+            and data[2] == 0x00
+            and len(self._data) >= self.INFO_LEN + self._data[3]
+        ):
+            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.INFO_LEN
+            or len(self._data) < BMS.INFO_LEN + self._data[3]
+        ):
+            return
+
+        # check correct frame ending
+        frame_end: Final[int] = BMS.INFO_LEN + self._data[3] - 1
+        if self._data[frame_end] != BMS.TAIL:
+            self._log.debug("incorrect frame end (length: %i).", len(self._data))
+            return
+
+        if (crc := BMS._crc(self._data[2 : frame_end - 2])) != int.from_bytes(
+            self._data[frame_end - 2 : frame_end], "big"
+        ):
+            self._log.debug(
+                "invalid checksum 0x%X != 0x%X",
+                int.from_bytes(self._data[frame_end - 2 : frame_end], "big"),
+                crc,
+            )
+            return
+
+        if len(self._data) != BMS.INFO_LEN + self._data[3]:
+            self._log.debug("wrong data length (%i): %s", len(self._data), self._data)
+
+        if self._data[1] != self._valid_reply:
+            self._log.debug("unexpected response (type 0x%X)", self._data[1])
+            return
+
+        self._data_final = self._data
+        self._data_event.set()
+
+    @staticmethod
+    def _crc(frame: bytearray) -> int:
+        """Calculate JBD frame CRC."""
+        return 0x10000 - sum(frame)
+
+    @staticmethod
+    def _cmd(cmd: bytes) -> bytes:
+        """Assemble a JBD BMS command."""
+        frame = bytearray([*BMS.HEAD_CMD, cmd[0], 0x00])
+        frame.extend([*BMS._crc(frame[2:4]).to_bytes(2, "big"), BMS.TAIL])
+        return bytes(frame)
+
+    async def _await_cmd_resp(self, cmd: int) -> None:
+        msg: Final[bytes] = BMS._cmd(bytes([cmd]))
+        self._valid_reply = msg[2]
+        await self._await_reply(msg)
+        self._valid_reply = 0x00
+
+    async def _async_update(self) -> BMSsample:
+        """Update battery status information."""
+        data: BMSsample = {}
+        await self._await_cmd_resp(0x03)
+        data = BMS._decode_data(BMS._FIELDS, self._data_final)
+        data["temp_values"] = BMS._temp_values(
+            self._data_final,
+            values=data.get("temp_sensors", 0),
+            start=27,
+            signed=False,
+            offset=2731,
+            divider=10,
+        )
+
+        await self._await_cmd_resp(0x04)
+        data["cell_voltages"] = BMS._cell_voltages(
+            self._data_final, cells=self._data_final[3] // 2, start=4, byteorder="big"
+        )
+
+        return data