ITADN
patman15/aiobmsble
代码 动态 Issues22 合并请求42 版本23
patman15/aiobmsble · 文件 下载 ZIP
文件最后提交记录最后更新时间
README.md
以下内容由 AI 翻译，如有问题请点此提交 issue 反馈

GitHub Release Python Version License

Aiobmsble

需要 Python 3 并使用 asyncio 和 Bleak

通过蓝牙 LE 查询电池管理系统的异步库

本库旨在从使用蓝牙 LE 的电池管理系统中查询数据。在任何 Python 环境中（安装必要的依赖项后）均可独立使用。它旨在支持 BMS_BLE-HA 集成，该集成旨在使 BMS 数据可用于 Home Assistant，但希望也能用于其他用例。

功能

  • 支持自动检测兼容的 BLE BMS
  • 自动检测兼容的 BLE 写入模式
  • 使用 asyncio 进行异步操作
  • 支持任意数量的电池并行
  • 100% 测试覆盖率以及针对 BLE 数据的模糊测试

[!CAUTION] 本库不得用于安全相关操作！无法保证数据的正确性或可用性（参见许可证的保修条款）， 因为该实现主要基于公开可用的信息或未经验证的供应商规范。 此外，蓝牙连接的问题，例如干扰，可能导致数值不可用或不正确。

请勿依赖这些数值来控制防止电池损坏、过热（火灾）或类似情况的动作。

支持的设备

支持设备列表 在相关 Home Assistant 集成 的仓库中维护。 有关每个 BMS 支持的数据详情，请参阅 BMS 数据表：

  • ✓ 表示该字段可直接从 BMS 获取。
  • . 表示该字段并非原生可用，但计算所需的所有字段均可用。
  • 空白表示该字段完全不可用。

API 文档

该项目使用 pdoc 生成 API 文档。您可以使用 开发安装 在本地生成，然后运行命令

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

该命令将在 /docs 文件夹中本地生成文档。

用法

为了识别所有可被库访问和支持的设备，请在 安装 后从命令行运行

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

使用 JSON 广播数据返回 BMS 类型，例如来自 Home Assistant Bluetooth Advertisement Monitor。

从您的 Python 代码

如果您需要参考以将代码包含到您的库中，请参阅 __main__.py。

从脚本

此示例也可以在相应的 文件夹 中作为 示例 找到。

"""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

测试

对于集成测试（使用 pytest），该库提供了可用于验证 BMS 检测的广播数据。在您的测试中，您可以使用

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():
        ...

安装

如果您尚未安装，请先安装 python 和 pip，然后运行：

pip3 install pip --upgrade
pip3 install wheel

用于生产环境：

pip3 install aiobmsble

这将安装最新版本的库及其所有 python 依赖项。

用于开发环境：

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

这将为您提供来自 main 分支的最新库代码。

故障排除

如果您在使用该库时遇到问题，请启用调试日志。您还可以从命令行运行 aiobmsble -v 以查询所有可访问的已知 BMS。

如果您遇到需要帮助的问题

  • 请使用 aiobmsble -v -l debug.log 记录调试日志，
  • 打开一个 issue，详细描述您的问题/疑问并附上日志，或者
  • 打开一个 bug，如果您认为观察到的行为是库的异常行为，包括对发生情况的详细描述以及您的预期，
  • 并将 debug.log 作为附件 添加到 issue 中。

致谢

@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, @ryanalden, @hflocki, @danilos2k, @hlathome

感谢帮助改进该库。

参考资料