🔋🎧 Bluetooth Headset Battery Level
This is a python script to fetch the battery charge level of some Bluetooth headsets.
You need python 3.6 or newer to run the script.
▶️ How to run
There are four options:
Option 1: Install from PyPI
Please ensure you have the BlueZ and python libraries and header files if you are using Ubuntu/Debian based distros:
sudo apt install libbluetooth-dev python3-dev
If you are using OpenSUSE, you will need to install bluez
, bluez-devel
, python3-devel
, python3-pybluez
Then, install with pip:
pip3 install bluetooth_battery
bluetooth_battery BT_MAC_ADDRESS_1 ...
You can input addresses for as many devices as you want separated by space.
the dependency pybluez
should be installed automatically, but if not, you may need to install it manually
Option 2: Download this repository
cd Bluetooth_Headset_Battery_Level
chmod +x bluetooth_battery.py
./bluetooth_battery.py BT_MAC_ADDRESS_1 ...
make sure you have python-pybluez
or python3-pybluez
or python3-bluez
installed on your system.
Option 3: Docker
You must have docker installed on your system.
Clone the repository using git clone
command. Then run:
cd Bluetooth_Headset_Battery_Level
docker build -t bluetooth_battery_level .
Once the build is complete you can use the below command to run the program:
docker run --rm -ti --privileged --net=host bluetooth_battery_level "BT_MAC_ADDRESS"
Option 4: AUR
You must have AUR access enabled on your Arch or Manjaro machine.
You can install this library using
yay -S bluetooth-headset-battery-level-git
Library usage
To use this as a library, simply install it using pip or AUR (see above) or require it in your Pipfile.
You can then
from bluetooth_battery import BatteryStateQuerier, BatteryQueryError, BluetoothError
and query the Battery State as follows:
query = BatteryStateQuerier("11:22:33:44:55:66")
query = BatteryStateQuerier("11:22:33:44:55:66", "4")
result = int(query)
result = str(query)
As errors can occur in a wireless system, you probably want to handle them:
try:
query = BatteryStateQuerier("11:22:33:44:55:66")
str(query)
except BluetoothError as e:
...
except BatteryQueryError as e:
...
GNOME Extension
There is also a GNOME extension for integrating this program with GNOME desktop environment:
https://extensions.gnome.org/extension/3991/bluetooth-battery/
Finding MAC address
There are a variety of utilities that can find the MAC address of your bluetooth device. Here is one, this command is in the bluez
package, and the given argument gets a list of all devices it knows about, even if not currently available.
$ bluetoothctl devices
Device E8:AB:FA:XX:XX:XX iTeknic IK-BH002
Device D0:77:14:XX:XX:XX Barak's Moto X4
Device E8:AB:FA:XX:XX:XX iTeknic IK-BH002
The 1st and 3rd would be relevant here, as those are headsets.
This shows devices that are actually connected.
$ bluetoothctl info
Device E8:AB:FA:XX:XX:XX (public)
Name: iTeknic IK-BH002
...
So you can use
bluetooth_battery.py $(bluetoothctl info | awk '/^Device/ {print $2}')
to query the battery of all connected devices.
It didn't work?
You can set the port number manually by adding a dot at the end of mac address, like this: 00:00:00:00:00:00.3
Try port numbers 1 to 30
to find the one that works for your device. (wait a few seconds between each try)
If that didn't work, disconnect your device first, and then try again.
Still doesn't work?
Please consider that this script doesn't guarantee to support every bluetooth device.
You can open a new issue for discussion or check the existing ones for more information.
Tested on
🤝 Thanks
Special thanks to:
@clst: For spreading the word!
@bhepple: For his research on fixing the important bug
@balsoft: For thinking outside the box (finding my big mistake)
@martin-beran: For making it easy to set the port number
@Bobo1239: For adding support for Samsung galaxy buds
@keystroke3: For adding multiple device support to the script
@jadia: For docker container support
@cheriimoya: For refactoring the code and providing NixOS packages
@MichalW: For making the GNOME shell extension
@GaLaXy102: For re-writing the code, making it cleaner and usable as a library
❤️ And everyone else that pointed out the issues or helped me with writing the code or testing it.
📜 License
This project is a free software licensed under GPL-3.0 or newer. For more information see LICENSE