Bluetooth_Headset_Battery_Level：读取蓝牙耳机电池电量

一个 Python 脚本与库，通过蓝牙 SPP 端口向耳机发送 AT 命令，获取并返回电池电量百分比，支持多设备查询与错误处理。

这个工具是什么

Bluetooth_Headset_Battery_Level 是一个用 Python 编写的脚本，用于获取部分蓝牙耳机的电池充电水平。它要求 Python 3.6 或更高版本，依赖 BlueZ 与 pybluez 等蓝牙库。项目以 GPL-3.0 许可证开源，在 GitHub 上获得 785 星标，最近一次提交在 2024 年 4 月。除命令行脚本外，它也可作为库导入，提供 BatteryStateQuerier 类，支持自动检测 SPP 端口或指定端口，并以整数、字符串或字典形式返回电量结果。README 还提到 GNOME 扩展与 Budgie Applet 两种桌面集成方式。

核心能力

• 通过蓝牙 SPP 端口发送 AT 命令读取耳机电池电量
• 支持一次传入多个设备 MAC 地址进行批量查询
• 可作为 Python 库导入，返回整数、百分比字符串或字典
• 提供 BluetoothError 与 BatteryQueryError 两类异常处理

科研中的典型用法

• 在 Linux 桌面环境中定期查询蓝牙耳机剩余电量，用于状态栏或通知提醒
• 在 Python 程序中调用 BatteryStateQuerier，将电量数据集成到自定义监控脚本
• 通过 Docker 以特权网络模式运行，在容器环境中查询指定 MAC 地址的设备电量

快速上手

安装方式有四种：从 PyPI 执行 pip3 install bluetooth_battery；下载仓库后运行 ./bluetooth_battery.py；使用 Docker 构建镜像后运行；或在 Arch/Manjaro 上通过 AUR 安装 python-bluetooth-battery。Ubuntu/Debian 需先安装 libbluetooth-dev 与 python3-dev。运行命令为 bluetooth_battery BT_MAC_ADDRESS_1 ...，可空格分隔多个地址。可用 bluetoothctl devices 查找设备 MAC 地址。

生态与相近工具

同领域还有 BlueZ 自带的 bluetoothctl 等工具，但 README 未提及其他同类电量查询工具。该项目的特点在于以脚本和库两种形式提供电量查询，并附带 GNOME 扩展与 Budgie Applet 桌面集成。若只需在命令行快速查看电量，可直接使用脚本；若需在 Python 项目中编程调用，则使用其库接口。选择时需注意它依赖 pybluez 与 BlueZ，且仅支持部分蓝牙耳机型号。

项目信息

• 仓库：TheWeirdDev/Bluetooth_Headset_Battery_Level
• 星标：785　·　派生：80
• 主要语言：Python
• 许可证：GPL-3.0
• 最近提交：2024-04-21

本文属于《学科研究工具知识库 · 能源科学》第 5 篇（按 GitHub 星标排序）。收录标准：该学科公开可获取的开源研究工具，星标与活跃度为主要参考，不代表对其性能或适用性的背书；选型前请结合自身场景评估。