Add new sensor for BMS alarms

README.md

@@ -55,6 +55,7 @@ This integration allows to monitor Bluetooth Low Energy (BLE) battery management
 Platform | Description | Unit | Decription | optional Attributes
 -- | -- | -- | -- | --
 `binary_sensor` | battery charging | `bool` | indicates `True` if battery is charging
+`binary_sensor` | problem | `bool` | indicates `True` if the battery is reports an issue or plausibility checks on values fail | problem code
 `sensor` | charge cycles | `#` | lifetime number of charge cycles | package charge cycles
 `sensor` | current | `A` | positive for charging, negative for discharging | balance current, package current
 `sensor` | delta voltage | `V` | maximum difference between any two cells | cell voltages
@@ -178,7 +179,6 @@ Once pairing is done, the integration should automatically detect the BMS.
 
 ## Outlook
 - Clean-up of translations
-- Implement status report of the BMS, e.g. warnings, errors as (single) binary sensor (ok, not ok)
 - Add option to only have temporary connections (lowers reliability, but helps running more devices via [ESPHome Bluetooth proxy][btproxy-url])
 - Add further battery types on [request](https://github.com/patman15/BMS_BLE-HA/issues/new?assignees=&labels=enhancement&projects=&template=feature_request.yml)
 
@@ -193,10 +193,11 @@ for helping with making the integration better.
 - Jikong BMS: [esphome-jk-bms](https://github.com/syssi/esphome-jk-bms)
 - JBD BMS: [esphome-jbd-bms](https://github.com/syssi/esphome-jbd-bms)
 - D-powercore BMS: [Strom BMS monitor](https://github.com/majonessyltetoy/strom)
+- Redodo BMS: [LiTime BMS bluetooth](https://github.com/calledit/LiTime_BMS_bluetooth)
 
 [license-shield]: https://img.shields.io/github/license/patman15/BMS_BLE-HA.svg?style=for-the-badge
 [releases-shield]: https://img.shields.io/github/release/patman15/BMS_BLE-HA.svg?style=for-the-badge
 [releases]: https://github.com//patman15/BMS_BLE-HA/releases
-[effort-shield]: https://img.shields.io/badge/Effort%20spent-338_hours-gold?style=for-the-badge&cacheSeconds=86400
+[effort-shield]: https://img.shields.io/badge/Effort%20spent-369_hours-gold?style=for-the-badge&cacheSeconds=86400
 [install-shield]: https://img.shields.io/badge/dynamic/json?style=for-the-badge&color=green&label=Analytics&suffix=%20Installs&cacheSeconds=15600&url=https://analytics.home-assistant.io/custom_integrations.json&query=$.bms_ble.total
 [btproxy-url]: https://esphome.io/components/bluetooth_proxy

custom_components/bms_ble/binary_sensor.py

@@ -5,22 +5,28 @@
     BinarySensorEntity,
     BinarySensorEntityDescription,
 )
-from homeassistant.const import ATTR_BATTERY_CHARGING
+from homeassistant.const import ATTR_BATTERY_CHARGING, EntityCategory
 from homeassistant.core import HomeAssistant
 from homeassistant.helpers.device_registry import format_mac
 from homeassistant.helpers.entity_platform import AddEntitiesCallback
 from homeassistant.helpers.update_coordinator import CoordinatorEntity
 
 from . import BTBmsConfigEntry
-from .const import DOMAIN
+from .const import ATTR_PROBLEM, DOMAIN, KEY_PROBLEM
 from .coordinator import BTBmsCoordinator
 
 BINARY_SENSOR_TYPES: list[BinarySensorEntityDescription] = [
     BinarySensorEntityDescription(
         key=ATTR_BATTERY_CHARGING,
         translation_key=ATTR_BATTERY_CHARGING,
         device_class=BinarySensorDeviceClass.BATTERY_CHARGING,
-    )
+    ),
+    BinarySensorEntityDescription(
+        key=ATTR_PROBLEM,
+        translation_key=ATTR_PROBLEM,
+        device_class=BinarySensorDeviceClass.PROBLEM,
+        entity_category=EntityCategory.DIAGNOSTIC,
+    ),
 ]
 
 
@@ -58,3 +64,11 @@ def __init__(
     def is_on(self) -> bool | None:  # type: ignore[reportIncompatibleVariableOverride]
         """Handle updated data from the coordinator."""
         return bool(self.coordinator.data.get(self.entity_description.key))
+
+    @property
+    def extra_state_attributes(self) -> dict | None:  # type: ignore[reportIncompatibleVariableOverride]
+        """Return entity specific state attributes, e.g. problem code."""
+        # add cell voltages to delta voltage sensor
+        if self.entity_description.key == ATTR_PROBLEM:
+            return {KEY_PROBLEM: self.coordinator.data.get(self.entity_description.key)}
+        return None

custom_components/bms_ble/const.py

@@ -39,6 +39,7 @@
 ATTR_DELTA_VOLTAGE: Final[str] = "delta_voltage"  # [V]
 ATTR_LQ: Final[str] = "link_quality"  # [%]
 ATTR_POWER: Final[str] = "power"  # [W]
+ATTR_PROBLEM: Final[str] = "problem"  # [bool]
 ATTR_RSSI: Final[str] = "rssi"  # [dBm]
 ATTR_RUNTIME: Final[str] = "runtime"  # [s]
 ATTR_TEMP_SENSORS: Final[str] = "temperature_sensors"  # [°C]
@@ -49,5 +50,6 @@
 KEY_DESIGN_CAP: Final[str] = "design_capacity"  # [Ah]
 KEY_PACK: Final[str] = "pack"  # prefix for pack sensors
 KEY_PACK_COUNT: Final[str] = "pack_count"  # [#]
+KEY_PROBLEM: Final[str] = "problem_code"  # [#]
 KEY_TEMP_SENS: Final[str] = "temp_sensors"  # [#]
 KEY_TEMP_VALUE: Final[str] = "temp#"  # [°C]

custom_components/bms_ble/manifest.json

@@ -145,5 +145,5 @@
     "bleak_retry_connector"
   ],
   "requirements": [],
-  "version": "1.12.0"
+  "version": "1.13.0"
 }

custom_components/bms_ble/plugins/basebms.py

@@ -14,15 +14,18 @@
 
 from custom_components.bms_ble.const import (
     ATTR_BATTERY_CHARGING,
+    ATTR_BATTERY_LEVEL,
     ATTR_CURRENT,
     ATTR_CYCLE_CAP,
     ATTR_CYCLE_CHRG,
     ATTR_DELTA_VOLTAGE,
     ATTR_POWER,
+    ATTR_PROBLEM,
     ATTR_RUNTIME,
     ATTR_TEMPERATURE,
     ATTR_VOLTAGE,
     KEY_CELL_VOLTAGE,
+    KEY_PROBLEM,
     KEY_TEMP_VALUE,
 )
 from homeassistant.components.bluetooth import BluetoothServiceInfoBleak
@@ -36,7 +39,8 @@
 class BaseBMS(metaclass=ABCMeta):
     """Base class for battery management system."""
 
-    BAT_TIMEOUT: float = 10
+    BAT_TIMEOUT = 10
+    MAX_CELL_VOLTAGE: Final[float] = 5.906  # max cell potential
 
     def __init__(
         self,
@@ -139,7 +143,7 @@ def _add_missing_values(data: BMSsample, values: set[str]) -> None:
         data: data dictionary from BMS
         values: list of values to add to the dictionary
         """
-        if not values:
+        if not values or not data:
             return
 
         def can_calc(value: str, using: frozenset[str]) -> bool:
@@ -183,8 +187,27 @@ def can_calc(value: str, using: frozenset[str]) -> bool:
             )
         # calculate temperature (average of all sensors)
         if can_calc(ATTR_TEMPERATURE, frozenset({f"{KEY_TEMP_VALUE}0"})):
-            temp_values = [v for k, v in data.items() if k.startswith(KEY_TEMP_VALUE)]
-            data[ATTR_TEMPERATURE] = round(fmean(temp_values), 3)
+            data[ATTR_TEMPERATURE] = round(
+                fmean([v for k, v in data.items() if k.startswith(KEY_TEMP_VALUE)]),
+                3,
+            )
+
+        # do sanity check on values to set problem state
+        data[ATTR_PROBLEM] = (
+            data.get(ATTR_PROBLEM, False)
+            or bool(data.get(KEY_PROBLEM, False))
+            or (
+                data.get(ATTR_VOLTAGE, 1) <= 0
+                or any(
+                    v <= 0 or v > BaseBMS.MAX_CELL_VOLTAGE
+                    for k, v in data.items()
+                    if k.startswith(KEY_CELL_VOLTAGE)
+                )
+                or data.get(ATTR_DELTA_VOLTAGE, 0) > BaseBMS.MAX_CELL_VOLTAGE
+                or data.get(ATTR_CYCLE_CHRG, 1) <= 0
+                or data.get(ATTR_BATTERY_LEVEL, 0) > 100
+            )
+        )
 
     def _on_disconnect(self, _client: BleakClient) -> None:
         """Disconnect callback function."""

custom_components/bms_ble/plugins/cbtpwr_bms.py

@@ -21,6 +21,7 @@
     ATTR_VOLTAGE,
     KEY_CELL_VOLTAGE,
     KEY_DESIGN_CAP,
+    KEY_PROBLEM,
 )
 from homeassistant.util.unit_conversion import _HRS_TO_SECS
 
@@ -49,6 +50,7 @@ class BMS(BaseBMS):
         (KEY_DESIGN_CAP, 0x15, 4, 2, False, lambda x: x),
         (ATTR_CYCLES, 0x15, 6, 2, False, lambda x: x),
         (ATTR_RUNTIME, 0x0C, 14, 2, False, lambda x: float(x * _HRS_TO_SECS / 100)),
+        (KEY_PROBLEM, 0x21, 4, 4, False, lambda x: x),
     ]
     _CMDS: Final[list[int]] = list({field[1] for field in _FIELDS})
 

custom_components/bms_ble/plugins/daly_bms.py

@@ -21,6 +21,7 @@
     ATTR_VOLTAGE,
     KEY_CELL_COUNT,
     KEY_CELL_VOLTAGE,
+    KEY_PROBLEM,
     KEY_TEMP_SENS,
     KEY_TEMP_VALUE,
 )
@@ -40,15 +41,16 @@ class BMS(BaseBMS):
     MAX_TEMP: Final[int] = 8
     INFO_LEN: Final[int] = 84 + HEAD_LEN + CRC_LEN + MAX_CELLS + MAX_TEMP
     MOS_TEMP_POS: Final[int] = HEAD_LEN + 8
-    _FIELDS: Final[list[tuple[str, int, Callable[[int], int | float]]]] = [
-        (ATTR_VOLTAGE, 80 + HEAD_LEN, lambda x: float(x / 10)),
-        (ATTR_CURRENT, 82 + HEAD_LEN, lambda x: float((x - 30000) / 10)),
-        (ATTR_BATTERY_LEVEL, 84 + HEAD_LEN, lambda x: float(x / 10)),
-        (ATTR_CYCLE_CHRG, 96 + HEAD_LEN, lambda x: float(x / 10)),
-        (KEY_CELL_COUNT, 98 + HEAD_LEN, lambda x: min(x, BMS.MAX_CELLS)),
-        (KEY_TEMP_SENS, 100 + HEAD_LEN, lambda x: min(x, BMS.MAX_TEMP)),
-        (ATTR_CYCLES, 102 + HEAD_LEN, lambda x: x),
-        (ATTR_DELTA_VOLTAGE, 112 + HEAD_LEN, lambda x: float(x / 1000)),
+    _FIELDS: Final[list[tuple[str, int, int, Callable[[int], int | float]]]] = [
+        (ATTR_VOLTAGE, 80 + HEAD_LEN, 2, lambda x: float(x / 10)),
+        (ATTR_CURRENT, 82 + HEAD_LEN, 2, lambda x: float((x - 30000) / 10)),
+        (ATTR_BATTERY_LEVEL, 84 + HEAD_LEN, 2, lambda x: float(x / 10)),
+        (ATTR_CYCLE_CHRG, 96 + HEAD_LEN, 2, lambda x: float(x / 10)),
+        (KEY_CELL_COUNT, 98 + HEAD_LEN, 2, lambda x: min(x, BMS.MAX_CELLS)),
+        (KEY_TEMP_SENS, 100 + HEAD_LEN, 2, lambda x: min(x, BMS.MAX_TEMP)),
+        (ATTR_CYCLES, 102 + HEAD_LEN, 2, lambda x: x),
+        (ATTR_DELTA_VOLTAGE, 112 + HEAD_LEN, 2, lambda x: float(x / 1000)),
+        (KEY_PROBLEM, 116 + HEAD_LEN, 8, lambda x: x),
     ]
 
     def __init__(self, ble_device: BLEDevice, reconnect: bool = False) -> None:
@@ -154,9 +156,11 @@ async def _async_update(self) -> BMSsample:
 
         data |= {
             key: func(
-                int.from_bytes(self._data[idx : idx + 2], byteorder="big", signed=True)
+                int.from_bytes(
+                    self._data[idx : idx + size], byteorder="big", signed=True
+                )
             )
-            for key, idx, func in BMS._FIELDS
+            for key, idx, size, func in BMS._FIELDS
         }
 
         # get temperatures

custom_components/bms_ble/plugins/dpwrcore_bms.py

@@ -22,6 +22,7 @@
     ATTR_VOLTAGE,
     KEY_CELL_COUNT,
     KEY_CELL_VOLTAGE,
+    KEY_PROBLEM,
 )
 
 from .basebms import BaseBMS, BMSsample
@@ -59,6 +60,7 @@ class BMS(BaseBMS):
         ),
         (KEY_CELL_COUNT, Cmd.CELLVOLT, 6, 1, lambda x: min(x, BMS._MAX_CELLS)),
         (ATTR_CYCLES, Cmd.LEGINFO2, 8, 2, lambda x: x),
+        (KEY_PROBLEM, Cmd.LEGINFO1, 15, 1, lambda x: x & 0xFF),
     ]
 
     def __init__(self, ble_device: BLEDevice, reconnect: bool = False) -> None:

custom_components/bms_ble/plugins/ective_bms.py

@@ -22,6 +22,7 @@
     ATTR_TEMPERATURE,
     ATTR_VOLTAGE,
     KEY_CELL_VOLTAGE,
+    KEY_PROBLEM,
 )
 
 from .basebms import BaseBMS, BMSsample
@@ -41,6 +42,7 @@ class BMS(BaseBMS):
         (ATTR_CYCLE_CHRG, 17, 8, False, lambda x: float(x / 1000)),
         (ATTR_CYCLES, 25, 4, False, lambda x: x),
         (ATTR_TEMPERATURE, 33, 4, False, lambda x: round(x * 0.1 - 273.15, 1)),
+        (KEY_PROBLEM, 37, 2, False, lambda x: x),
     ]
 
     def __init__(self, ble_device: BLEDevice, reconnect: bool = False) -> None:

custom_components/bms_ble/plugins/ej_bms.py

@@ -20,6 +20,7 @@
     ATTR_TEMPERATURE,
     ATTR_VOLTAGE,
     KEY_CELL_VOLTAGE,
+    KEY_PROBLEM,
 )
 
 from .basebms import BaseBMS, BMSsample
@@ -45,6 +46,7 @@ class BMS(BaseBMS):
         (ATTR_CYCLE_CHRG, Cmd.CAP, 15, 4, lambda x: float(x) / 10),
         (ATTR_TEMPERATURE, Cmd.RT, 97, 2, lambda x: x - 40),  # only 1st sensor relevant
         (ATTR_CYCLES, Cmd.RT, 115, 4, lambda x: x),
+        (KEY_PROBLEM, Cmd.RT, 105, 4, lambda x: x & 0x0FFC),  # mask status bits
     ]
 
     def __init__(self, ble_device: BLEDevice, reconnect: bool = False) -> None:
@@ -182,6 +184,11 @@ async def _async_update(self) -> BMSsample:
                 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 {
             key: func(int(raw_data[cmd.value][idx : idx + size], 16))
             for key, cmd, idx, size, func in BMS._FIELDS

custom_components/bms_ble/plugins/felicity_bms.py

@@ -21,7 +21,7 @@
     ATTR_TEMPERATURE,
     ATTR_VOLTAGE,
     KEY_CELL_VOLTAGE,
-#    KEY_PROBLEM, # TODO: enable
+    KEY_PROBLEM,
     KEY_TEMP_VALUE,
 )
 
@@ -145,5 +145,8 @@ async def _async_update(self) -> BMSsample:
             BMS._decode_data(self._data_final)
             | BMS._temp_sensors(self._data_final)
             | BMS._cell_voltages(self._data_final)
-#            | {KEY_PROBLEM: self._data_final.get("Bwarn", 0) + self._data_final.get("Bfault", 0)}
+            | {
+                KEY_PROBLEM: self._data_final.get("Bwarn", 0)
+                + self._data_final.get("Bfault", 0)
+            }
         )

custom_components/bms_ble/plugins/jbd_bms.py

@@ -20,6 +20,7 @@
     ATTR_TEMPERATURE,
     ATTR_VOLTAGE,
     KEY_CELL_VOLTAGE,
+    KEY_PROBLEM,
     KEY_TEMP_SENS,
     KEY_TEMP_VALUE,
 )
@@ -41,6 +42,7 @@ class BMS(BaseBMS):
         (ATTR_BATTERY_LEVEL, 23, 1, False, lambda x: x),
         (ATTR_CYCLE_CHRG, 8, 2, False, lambda x: float(x / 100)),
         (ATTR_CYCLES, 12, 2, False, lambda x: x),
+        (KEY_PROBLEM, 20, 2, False, lambda x: x),
     ]  # general protocol v4
 
     def __init__(self, ble_device: BLEDevice, reconnect: bool = False) -> None:

custom_components/bms_ble/plugins/jikong_bms.py

@@ -23,6 +23,7 @@
     ATTR_VOLTAGE,
     KEY_CELL_COUNT,
     KEY_CELL_VOLTAGE,
+    KEY_PROBLEM,
     KEY_TEMP_VALUE,
 )
 
@@ -45,6 +46,7 @@ class BMS(BaseBMS):
             (ATTR_CYCLE_CHRG, 174, 4, False, lambda x: float(x / 1000)),
             (ATTR_CYCLES, 182, 4, False, lambda x: x),
             (ATTR_BALANCE_CUR, 170, 2, True, lambda x: float(x / 1000)),
+            (KEY_PROBLEM, 166, 4, False, lambda x: x),
         ]
     )
 
@@ -283,6 +285,15 @@ async def _async_update(self) -> BMSsample:
             )
 
         data: BMSsample = self._decode_data(self._data_final, self._prot_offset)
+        data.update(
+            {
+                KEY_PROBLEM: (
+                    (int(data[KEY_PROBLEM]) >> 16)
+                    if self._prot_offset
+                    else (int(data[KEY_PROBLEM]) & 0xFFFF)
+                )
+            }
+        )
         data.update(BMS._temp_sensors(self._data_final, self._prot_offset))
         data.update(BMS._cell_voltages(self._data_final, int(data[KEY_CELL_COUNT])))
 

custom_components/bms_ble/plugins/redodo_bms.py

@@ -20,6 +20,7 @@
     ATTR_TEMPERATURE,
     ATTR_VOLTAGE,
     KEY_CELL_VOLTAGE,
+    KEY_PROBLEM,
     KEY_TEMP_VALUE,
 )
 
@@ -39,6 +40,7 @@ class BMS(BaseBMS):
         (ATTR_BATTERY_LEVEL, 90, 2, False, lambda x: x),
         (ATTR_CYCLE_CHRG, 62, 2, False, lambda x: float(x / 100)),
         (ATTR_CYCLES, 96, 4, False, lambda x: x),
+        (KEY_PROBLEM, 76, 4, False, lambda x: x),
     ]
 
     def __init__(self, ble_device: BLEDevice, reconnect: bool = False) -> None: