aiobmsble 0.21.0

Asynchronous Python library to query battery management systems via Bluetooth Low Energy.

Aiobmsble

Requires Python 3 and uses asyncio and Bleak

Asynchronous Library to Query Battery Management Systems via Bluetooth LE

This library is intended to query data from battery management systems that use Bluetooth LE. Stand-alone usage is possible in any Python environment (with necessary dependencies installed). It is developed to support BMS_BLE-HA integration that was written to make BMS data available to Home Assistant, but can be hopefully useful for other use-cases as well.

• Features
• Usage
• Installation
• Troubleshooting
• Thanks to
• References

Features

• Support for autodetecting compatible BLE BMSs
• Automatic detection of compatible BLE write mode
• Asynchronous operation using asyncio
• Any number of batteries in parallel
• 100% test coverage plus fuzz tests for BLE data

[!CAUTION] This library shall not be used for safety relevant operations! The correctness or availability of data cannot be guaranteed (see warranty section of the license), since the implementation is mostly based on openly available information or non-validated vendor specifications. Further, issues with the Bluetooth connection, e.g. disturbances, can lead to unavailable or incorrect values.

Do not rely on the values to control actions that prevent battery damage, overheating (fire), or similar.

Supported Devices

The list of supported devices is maintained in the repository of the related Home Assistant integration. For details about the supported data per BMS, please have a look at BMS data table:

• A ✓ means that the field is directly available from the BMS.
• A . means that the field is not natively available, but all required fields for its calculation are available.
• Empty means that the field is not available at all.

API documentation

The project uses pdoc to generate the API documentation. You can generate it locally using the installation for development and then running the command

pdoc 'aiobmsble' '!aiobmsble.bms' -o docs

which will generate the documentation locally in the /docs folder.

Usage

In order to identify all devices that are reachable and supported by the library, simply run

aiobmsble

from the command line after installation.

aiobmsble --json '{"local_name": "dummy"}'

returns the BMS type using the JSON advertisement data, e.g. from Home Assistant Bluetooth Advertisement Monitor.

From your Python code

In case you need a reference to include the code into your library, please see __main__.py.

From a Script

This example can also be found as an example in the respective folder.

"""Example of using the aiobmsble library to find a BLE device by name and print its sensor data.

Project: aiobmsble, https://pypi.org/p/aiobmsble/
License: Apache-2.0, http://www.apache.org/licenses/
"""

import asyncio
import logging
from typing import Final

from bleak import BleakScanner
from bleak.backends.device import BLEDevice
from bleak.exc import BleakError

from aiobmsble import BMSSample
from aiobmsble.bms.dummy_bms import BMS  # TODO: use the right BMS class for your device

NAME: Final[str] = "BT Device Name"  # TODO: replace with the name of your BLE device

# Configure logging
logging.basicConfig(level=logging.INFO)
logger: logging.Logger = logging.getLogger(__name__)


async def main(dev_name: str) -> None:
    """Find a BLE device by name and update its sensor data."""

    device: BLEDevice | None = await BleakScanner.find_device_by_name(dev_name)
    if device is None:
        logger.error("Device '%s' not found.", dev_name)
        return

    logger.info("Found device: %s (%s)", device.name, device.address)
    try:
        async with BMS(ble_device=device) as bms:
            logger.info("Updating BMS data...")
            data: BMSSample = await bms.async_update()
            logger.info("BMS data: %s", repr(data).replace(", ", ",\n\t"))
    except BleakError as ex:
        logger.error("Failed to update BMS: %s", type(ex).__name__)


if __name__ == "__main__":
    asyncio.run(main(NAME))  # pragma: no cover

Testing

For integration tests (using pytest) the library provides advertisement data that can be used to verify detection of BMSs. For your tests you can use

from aiobmsble.test_data import bms_advertisements

def test_advertisements() -> None:
    """Run some tests with the advertisements"""
    for advertisement, bms_type, _comments in bms_advertisements():
        ...

Installation

Install python and pip if you have not already, then run:

pip3 install pip --upgrade
pip3 install wheel

For Production:

pip3 install aiobmsble

This will install the latest library release and all of it's python dependencies.

For Development:

git clone https://github.com/patman15/aiobmsble.git
cd aiobmsble
pip3 install -e .[dev]

This gives you the latest library code from the main branch.

Troubleshooting

In case you have problems with the library, please enable debug logging. You can also run aiobmsble -v from the command line in order to query all known BMS that are reachable.

In case you have troubles you'd like to have help with

• please record a debug log using aiobmsble -v -l debug.log,
• open an issue with a good description of what your question/issue is and attach the log, or
• open a bug if you think the behaviour you see is misbehaviour of the library, including a good description of what happened, your expectations,
• and put the debug.log as attachment to the issue.

Thanks to

@gkathan, @downset, @gerritb, @Goaheadz, @alros100, @majonessyltetoy, @snipah, @Gruni22, @azisto, @BikeAtor, @Karatzie, @PG248, @SkeLLLa,@romanshypovskyi, @riogrande75, @ebagnoli, @andreas-bulling, @goblinmaks, @andreitoma-github, @hacsler, @ViPeR5000, @edelstahlratte, @nezra, @Fandu21, @rubenclark74, @geierwally1978, @Tulexcorp, @oliviercommelarbre, @shaf, @gavrilov, @SOLAR-RAIDER, @prodisz, @thecodingmax, @daubman, @krahabb, @ardeus-ua, @GlennDC, @hhgerhard-google, @crotwell, @dschenzer, @randyoo, @wilcox97, @darrenjackson72, @nostroff, @ppvadmin @admlaz

for helping with making the library better.

References

• ANT BMS: esphome-ant-bms
• Daly BMS: esp32-smart-bms-simulation
• EG4 BMS: dbus-serialbattery
• Jikong BMS: esphome-jk-bms
• JBD BMS: esphome-jbd-bms
• D-powercore BMS: Strom BMS monitor
• Pro BMS: @daubman
• Redodo BMS: LiTime BMS Bluetooth
• TianPower BMS: esphome-tianpower-bms