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

aiobmsble/bms/seplos_v2_bms.py

@@ -0,0 +1,205 @@
+"""Module to support Seplos v2 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_xmodem
+
+
+class BMS(BaseBMS):
+    """Seplos v2 BMS implementation."""
+
+    _HEAD: Final[bytes] = b"\x7e"
+    _TAIL: Final[bytes] = b"\x0d"
+    _CMD_VER: Final[int] = 0x10  # TX protocol version
+    _RSP_VER: Final[int] = 0x14  # RX protocol version
+    _MIN_LEN: Final[int] = 10
+    _MAX_SUBS: Final[int] = 0xF
+    _CELL_POS: Final[int] = 9
+    _PRB_MAX: Final[int] = 8  # max number of alarm event bytes
+    _PRB_MASK: Final[int] = ~0x82FFFF  # ignore byte 7-8 + byte 6 (bit 7,2)
+    _PFIELDS: Final[tuple[BMSdp, ...]] = (  # Seplos V2: single machine data
+        BMSdp("voltage", 2, 2, False, lambda x: x / 100),
+        BMSdp("current", 0, 2, True, lambda x: x / 100),  # /10 for 0x62
+        BMSdp("cycle_charge", 4, 2, False, lambda x: x / 100),  # /10 for 0x62
+        BMSdp("cycles", 13, 2, False, lambda x: x),
+        BMSdp("battery_level", 9, 2, False, lambda x: x / 10),
+    )
+    _GSMD_LEN: Final[int] = _CELL_POS + max((dp.pos + dp.size) for dp in _PFIELDS) + 3
+    _CMDS: Final[list[tuple[int, bytes]]] = [(0x51, b""), (0x61, b"\x00"), (0x62, b"")]
+
+    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 = BMS._MIN_LEN
+        self._exp_reply: set[int] = set()
+
+    @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 ("BP0?", "BP1?", "BP2?")
+        ]
+
+    @staticmethod
+    def device_info() -> dict[str, str]:
+        """Return device information for the battery management system."""
+        return {"manufacturer": "Seplos", "model": "Smart BMS V2"}
+
+    @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(
+            {
+                "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 (
+            len(data) > BMS._MIN_LEN
+            and data.startswith(BMS._HEAD)
+            and len(self._data) >= self._exp_len
+        ):
+            self._exp_len = BMS._MIN_LEN + int.from_bytes(data[5:7])
+            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) < self._exp_len:
+            return
+
+        if not self._data.endswith(BMS._TAIL):
+            self._log.debug("incorrect frame end: %s", self._data)
+            return
+
+        if self._data[1] != BMS._RSP_VER:
+            self._log.debug("unknown frame version: V%.1f", self._data[1] / 10)
+            return
+
+        if self._data[4]:
+            self._log.debug("BMS reported error code: 0x%X", self._data[4])
+            return
+
+        if (crc := crc_xmodem(self._data[1:-3])) != int.from_bytes(self._data[-3:-1]):
+            self._log.debug(
+                "invalid checksum 0x%X != 0x%X",
+                crc,
+                int.from_bytes(self._data[-3:-1]),
+            )
+            return
+
+        self._log.debug(
+            "address: 0x%X, function: 0x%X, return: 0x%X",
+            self._data[2],
+            self._data[3],
+            self._data[4],
+        )
+
+        self._data_final[self._data[3]] = self._data
+        try:
+            self._exp_reply.remove(self._data[3])
+            self._data_event.set()
+        except KeyError:
+            self._log.debug("unexpected reply: 0x%X", self._data[3])
+
+    async def _init_connection(
+        self, char_notify: BleakGATTCharacteristic | int | str | None = None
+    ) -> None:
+        """Initialize protocol state."""
+        await super()._init_connection()
+        self._exp_len = BMS._MIN_LEN
+
+    @staticmethod
+    def _cmd(cmd: int, address: int = 0, data: bytearray = bytearray()) -> bytes:
+        """Assemble a Seplos V2 BMS command."""
+        assert cmd in (0x47, 0x51, 0x61, 0x62, 0x04)  # allow only read commands
+        frame = bytearray([*BMS._HEAD, BMS._CMD_VER, address, 0x46, cmd])
+        frame += len(data).to_bytes(2, "big", signed=False) + data
+        frame += int.to_bytes(crc_xmodem(frame[1:]), 2, byteorder="big") + BMS._TAIL
+        return bytes(frame)
+
+    async def _async_update(self) -> BMSsample:
+        """Update battery status information."""
+
+        for cmd, data in BMS._CMDS:
+            self._exp_reply.add(cmd)
+            await self._await_reply(BMS._cmd(cmd, data=bytearray(data)))
+
+        result: BMSsample = {}
+        result["cell_count"] = self._data_final[0x61][BMS._CELL_POS]
+        result["temp_sensors"] = self._data_final[0x61][
+            BMS._CELL_POS + result["cell_count"] * 2 + 1
+        ]
+        ct_blk_len: Final[int] = (result["cell_count"] + result["temp_sensors"]) * 2 + 2
+
+        if (BMS._GSMD_LEN + ct_blk_len) > len(self._data_final[0x61]):
+            raise ValueError("message too short to decode data")
+
+        result |= BMS._decode_data(
+            BMS._PFIELDS, self._data_final[0x61], offset=BMS._CELL_POS + ct_blk_len
+        )
+
+        # get extention pack count from parallel data (main pack)
+        result["pack_count"] = self._data_final[0x51][42]
+
+        # get alarms from parallel data (main pack)
+        alarm_evt: Final[int] = min(self._data_final[0x62][46], BMS._PRB_MAX)
+        result["problem_code"] = (
+            int.from_bytes(self._data_final[0x62][47 : 47 + alarm_evt], byteorder="big")
+            & BMS._PRB_MASK
+        )
+
+        result["cell_voltages"] = BMS._cell_voltages(
+            self._data_final[0x61],
+            cells=self._data_final[0x61][BMS._CELL_POS],
+            start=10,
+        )
+        result["temp_values"] = BMS._temp_values(
+            self._data_final[0x61],
+            values=result["temp_sensors"],
+            start=BMS._CELL_POS + result.get("cell_count", 0) * 2 + 2,
+            signed=False,
+            offset=2731,
+            divider=10,
+        )
+
+        self._data_final.clear()
+
+        return result

aiobmsble/bms/tdt_bms.py

@@ -0,0 +1,199 @@
+"""Module to support TDT 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):
+    """TDT BMS implementation."""
+
+    _UUID_CFG: Final[str] = "fffa"
+    _HEAD: Final[int] = 0x7E
+    _CMD_HEADS: list[int] = [0x7E, 0x1E]  # alternative command head
+    _TAIL: Final[int] = 0x0D
+    _CMD_VER: Final[int] = 0x00
+    _RSP_VER: Final[frozenset[int]] = frozenset({0x00, 0x04})
+    _CELL_POS: Final[int] = 0x8
+    _INFO_LEN: Final[int] = 10  # minimal frame length
+    _FIELDS: Final[tuple[BMSdp, ...]] = (
+        BMSdp("voltage", 2, 2, False, lambda x: x / 100, 0x8C),
+        BMSdp(
+            "current",
+            0,
+            2,
+            False,
+            lambda x: (x & 0x3FFF) / 10 * (-1 if x >> 15 else 1),
+            0x8C,
+        ),
+        BMSdp("cycle_charge", 4, 2, False, lambda x: x / 10, 0x8C),
+        BMSdp("battery_level", 13, 1, False, lambda x: x, 0x8C),
+        BMSdp("cycles", 8, 2, False, lambda x: x, 0x8C),
+    )  # problem code is not included in the list, but extra
+    _CMDS: Final[list[int]] = [*list({field.idx for field in _FIELDS}), 0x8D]
+
+    def __init__(self, ble_device: BLEDevice, reconnect: bool = False) -> None:
+        """Initialize BMS."""
+        super().__init__(ble_device, reconnect)
+        self._data_final: dict[int, bytearray] = {}
+        self._cmd_heads: list[int] = BMS._CMD_HEADS
+        self._exp_len: int = 0
+
+    @staticmethod
+    def matcher_dict_list() -> list[MatcherPattern]:
+        """Provide BluetoothMatcher definition."""
+        return [{"manufacturer_id": 54976, "connectable": True}]
+
+    @staticmethod
+    def device_info() -> dict[str, str]:
+        """Return device information for the battery management system."""
+        return {"manufacturer": "TDT", "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(
+            {
+                "battery_charging",
+                "cycle_capacity",
+                "delta_voltage",
+                "power",
+                "runtime",
+                "temperature",
+            }
+        )  # calculate further values from BMS provided set ones
+
+    async def _init_connection(
+        self, char_notify: BleakGATTCharacteristic | int | str | None = None
+    ) -> None:
+        await self._await_reply(
+            data=b"HiLink", char=BMS._UUID_CFG, wait_for_notify=False
+        )
+        if (
+            ret := int.from_bytes(await self._client.read_gatt_char(BMS._UUID_CFG))
+        ) != 0x1:
+            self._log.debug("error unlocking BMS: %X", ret)
+
+        await super()._init_connection()
+
+    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) > BMS._INFO_LEN
+            and data[0] == BMS._HEAD
+            and len(self._data) >= self._exp_len
+        ):
+            self._exp_len = BMS._INFO_LEN + int.from_bytes(data[6:8])
+            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) < max(BMS._INFO_LEN, self._exp_len):
+            return
+
+        if self._data[-1] != BMS._TAIL:
+            self._log.debug("frame end incorrect: %s", self._data)
+            return
+
+        if self._data[1] not in BMS._RSP_VER:
+            self._log.debug("unknown frame version: V%.1f", self._data[1] / 10)
+            return
+
+        if self._data[4]:
+            self._log.debug("BMS reported error code: 0x%X", self._data[4])
+            return
+
+        if (crc := crc_modbus(self._data[:-3])) != int.from_bytes(
+            self._data[-3:-1], "big"
+        ):
+            self._log.debug(
+                "invalid checksum 0x%X != 0x%X",
+                int.from_bytes(self._data[-3:-1], "big"),
+                crc,
+            )
+            return
+        self._data_final[self._data[5]] = self._data
+        self._data_event.set()
+
+    @staticmethod
+    def _cmd(cmd: int, data: bytearray = bytearray(), cmd_head: int = _HEAD) -> bytes:
+        """Assemble a TDT BMS command."""
+        assert cmd in (0x8C, 0x8D, 0x92)  # allow only read commands
+
+        frame = bytearray([cmd_head, BMS._CMD_VER, 0x1, 0x3, 0x0, cmd])
+        frame += len(data).to_bytes(2, "big", signed=False) + data
+        frame += crc_modbus(frame).to_bytes(2, "big") + bytes([BMS._TAIL])
+
+        return bytes(frame)
+
+    async def _async_update(self) -> BMSsample:
+        """Update battery status information."""
+
+        for head in self._cmd_heads:
+            try:
+                for cmd in BMS._CMDS:
+                    await self._await_reply(BMS._cmd(cmd, cmd_head=head))
+                self._cmd_heads = [head]  # set to single head for further commands
+                break
+            except TimeoutError:
+                ...  # try next command head
+        else:
+            raise TimeoutError
+
+        result: BMSsample = {"cell_count": self._data_final[0x8C][BMS._CELL_POS]}
+        result["temp_sensors"] = self._data_final[0x8C][
+            BMS._CELL_POS + result["cell_count"] * 2 + 1
+        ]
+
+        result["cell_voltages"] = BMS._cell_voltages(
+            self._data_final[0x8C],
+            cells=result.get("cell_count", 0),
+            start=BMS._CELL_POS + 1,
+        )
+        result["temp_values"] = BMS._temp_values(
+            self._data_final[0x8C],
+            values=result["temp_sensors"],
+            start=BMS._CELL_POS + result.get("cell_count", 0) * 2 + 2,
+            signed=False,
+            offset=2731,
+            divider=10,
+        )
+        idx: Final[int] = result.get("cell_count", 0) + result.get("temp_sensors", 0)
+
+        result |= BMS._decode_data(
+            BMS._FIELDS, self._data_final, offset=BMS._CELL_POS + idx * 2 + 2
+        )
+        result["problem_code"] = int.from_bytes(
+            self._data_final[0x8D][BMS._CELL_POS + idx + 6 : BMS._CELL_POS + idx + 8]
+        )
+
+        self._data_final.clear()
+
+        return result

aiobmsble/bms/tianpwr_bms.py

@@ -0,0 +1,138 @@
+"""Module to support TianPwr 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):
+    """TianPwr BMS implementation."""
+
+    _HEAD: Final[bytes] = b"\x55"
+    _TAIL: Final[bytes] = b"\xaa"
+    _RDCMD: Final[bytes] = b"\x04"
+    _MAX_CELLS: Final[int] = 16
+    _MAX_TEMP: Final[int] = 6
+    _MIN_LEN: Final[int] = 4
+    _DEF_LEN: Final[int] = 20
+    _FIELDS: Final[tuple[BMSdp, ...]] = (
+        BMSdp("battery_level", 3, 2, False, lambda x: x, 0x83),
+        BMSdp("voltage", 5, 2, False, lambda x: x / 100, 0x83),
+        BMSdp("current", 13, 2, True, lambda x: x / 100, 0x83),
+        BMSdp("problem_code", 11, 8, False, lambda x: x, 0x84),
+        BMSdp("cell_count", 3, 1, False, lambda x: x, 0x84),
+        BMSdp("temp_sensors", 4, 1, False, lambda x: x, 0x84),
+        BMSdp("design_capacity", 5, 2, False, lambda x: x // 100, 0x84),
+        BMSdp("cycle_charge", 7, 2, False, lambda x: x / 100, 0x84),
+        BMSdp("cycles", 9, 2, False, lambda x: x, 0x84),
+    )
+    _CMDS: Final[set[int]] = set({field.idx for field in _FIELDS}) | set({0x87})
+
+    def __init__(self, ble_device: BLEDevice, reconnect: bool = False) -> None:
+        """Initialize BMS."""
+        super().__init__(ble_device, reconnect)
+        self._data_final: dict[int, bytearray] = {}
+
+    @staticmethod
+    def matcher_dict_list() -> list[MatcherPattern]:
+        """Provide BluetoothMatcher definition."""
+        return [{"local_name": "TP_*", "connectable": True}]
+
+    @staticmethod
+    def device_info() -> dict[str, str]:
+        """Return device information for the battery management system."""
+        return {"manufacturer": "TianPwr", "model": "SmartBMS"}
+
+    @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(
+            {
+                "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)."""
+        self._log.debug("RX BLE data: %s", data)
+
+        # verify that data is long enough
+        if len(data) != BMS._DEF_LEN:
+            self._log.debug("incorrect frame length")
+            return
+
+        if not data.startswith(BMS._HEAD):
+            self._log.debug("incorrect SOF.")
+            return
+
+        if not data.endswith(BMS._TAIL):
+            self._log.debug("incorrect EOF.")
+            return
+
+        self._data_final[data[2]] = data.copy()
+        self._data_event.set()
+
+    @staticmethod
+    def _cmd(addr: int) -> bytes:
+        """Assemble a TianPwr BMS command."""
+        return BMS._HEAD + BMS._RDCMD + addr.to_bytes(1) + BMS._TAIL
+
+    async def _async_update(self) -> BMSsample:
+        """Update battery status information."""
+
+        self._data_final.clear()
+        for cmd in BMS._CMDS:
+            await self._await_reply(BMS._cmd(cmd))
+
+        result: BMSsample = BMS._decode_data(BMS._FIELDS, self._data_final)
+
+        for cmd in range(
+            0x88, 0x89 + min(result.get("cell_count", 0), BMS._MAX_CELLS) // 8
+        ):
+            await self._await_reply(BMS._cmd(cmd))
+            result["cell_voltages"] = result.setdefault(
+                "cell_voltages", []
+            ) + BMS._cell_voltages(
+                self._data_final.get(cmd, bytearray()), cells=8, start=3
+            )
+
+        if {0x83, 0x87}.issubset(self._data_final):
+            result["temp_values"] = [
+                int.from_bytes(
+                    self._data_final[0x83][idx : idx + 2], byteorder="big", signed=True
+                )
+                / 10
+                for idx in (7, 11)  # take ambient and mosfet temperature
+            ] + BMS._temp_values(
+                self._data_final.get(0x87, bytearray()),
+                values=min(BMS._MAX_TEMP, result.get("temp_sensors", 0)),
+                start=3,
+                divider=10,
+            )
+
+        return result

aiobmsble/utils.py

@@ -1,22 +1,26 @@
 """Utilitiy/Support functions for aiobmsble."""
 
 from fnmatch import translate
+from functools import lru_cache
+import importlib
+import pkgutil
 import re
+from types import ModuleType
 
 from bleak.backends.scanner import AdvertisementData
 
-from aiobmsble import AdvertisementPattern
+from aiobmsble import MatcherPattern
 from aiobmsble.basebms import BaseBMS
 
 
-def advertisement_matches(
-    matcher: AdvertisementPattern,
+def _advertisement_matches(
+    matcher: MatcherPattern,
     adv_data: AdvertisementData,
 ) -> bool:
     """Determine whether the given advertisement data matches the specified pattern.
 
     Args:
-        matcher (AdvertisementPattern): A dictionary containing the matching criteria.
+        matcher (MatcherPattern): A dictionary containing the matching criteria.
             Possible keys include:
             - "service_uuid" (str): A specific service 128-bit UUID to match.
             - "service_data_uuid" (str): A specific service data UUID to match.
@@ -56,18 +60,104 @@ def advertisement_matches(
     )
 
 
-def bms_supported(bms: BaseBMS, adv_data: AdvertisementData) -> bool:
+@lru_cache
+def load_bms_plugins() -> set[ModuleType]:
+    """Discover and load all available Battery Management System (BMS) plugin modules.
+
+    This function scans the 'aiobmsble/bms' directory for all Python modules,
+    dynamically imports each discovered module, and returns a set containing
+    the imported module objects required to end with "_bms".
+
+    Returns:
+        set[ModuleType]: A set of imported BMS plugin modules.
+
+    Raises:
+        ImportError: If a module cannot be imported.
+        OSError: If the plugin directory cannot be accessed.
+
+    """
+    return {
+        importlib.import_module(f"aiobmsble.bms.{module_name}")
+        for _, module_name, _ in pkgutil.iter_modules(["aiobmsble/bms"])
+        if module_name.endswith("_bms")
+    }
+
+
+def bms_cls(name: str) -> type[BaseBMS] | None:
+    """Return the BMS class that is defined by the name argument.
+
+    Args:
+        name (str): The name of the BMS type
+
+    Returns:
+        type[BaseBMS] | None: If the BMS class defined by name is found, None otherwise.
+
+    """
+    try:
+        bms_module: ModuleType = importlib.import_module(f"aiobmsble.bms.{name}_bms")
+    except ModuleNotFoundError:
+        return None
+    return bms_module.BMS
+
+
+def bms_matching(
+    adv_data: AdvertisementData, mac_addr: str | None = None
+) -> list[type[BaseBMS]]:
+    """Return the BMS classes that match the given advertisement data.
+
+    Currently the function returns at most one match, but this behaviour might change
+    in the future to multiple entries, if BMSs cannot be distinguished uniquely using
+    their Bluetooth advertisement / OUI (Organizationally Unique Identifier)
+
+    Args:
+        adv_data (AdvertisementData): The advertisement data to match against available BMS plugins.
+        mac_addr (str | None): Optional MAC address to check OUI against
+
+    Returns:
+        list[type[BaseBMS]]: A list of matching BMS class(es) if found, an empty list otherwhise.
+
+    """
+    for bms_module in load_bms_plugins():
+        if bms_supported(bms_module.BMS, adv_data, mac_addr):
+            return [bms_module.BMS]
+    return []
+
+
+def bms_identify(
+    adv_data: AdvertisementData, mac_addr: str | None = None
+) -> type[BaseBMS] | None:
+    """Return the BMS classes that best matches the given advertisement data.
+
+    Args:
+        adv_data (AdvertisementData): The advertisement data to match against available BMS plugins.
+        mac_addr (str | None): Optional MAC address to check OUI against
+
+    Returns:
+        type[BaseBMS] | None: The identified BMS class if a match is found, None otherwhise
+
+    """
+
+    matching_bms: list[type[BaseBMS]] = bms_matching(adv_data, mac_addr)
+    return matching_bms[0] if matching_bms else None
+
+
+def bms_supported(
+    bms: BaseBMS, adv_data: AdvertisementData, mac_addr: str | None = None
+) -> bool:
     """Determine if the given BMS is supported based on advertisement data.
 
     Args:
         bms (BaseBMS): The BMS class to check.
         adv_data (AdvertisementData): The advertisement data to match against.
+        mac_addr (str | None): Optional MAC address to check OUI against
 
     Returns:
         bool: True if the BMS is supported, False otherwise.
 
     """
+    if mac_addr:
+        raise NotImplementedError  # pragma: no cover
     for matcher in bms.matcher_dict_list():
-        if advertisement_matches(matcher, adv_data):
+        if _advertisement_matches(matcher, adv_data):
             return True
     return False