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.
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-devIf 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
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.
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"You must have AUR access enabled on your Arch or Manjaro machine. You can install this library using
yay -S python-bluetooth-batterythe dependency pybluez should be installed automatically, but if not, you may need to install it manually
This can be done with pip3 install git+https://github.com/pybluez/pybluez@master.
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
# only for error handlingand query the Battery State as follows:
# Autodetects SPP port
query = BatteryStateQuerier("11:22:33:44:55:66")
# or with given port
query = BatteryStateQuerier("11:22:33:44:55:66", "4")
result = int(query) # returns integer between 0 and 100
# or
result = str(query) # returns "0%".."100%"
# or
result = query.query() # returns a dictonary, e.g. {'overall': 100, 'left': 100, 'right': 100, 'case': 87}As errors can occur in a wireless system, you probably want to handle them:
try:
query = BatteryStateQuerier("11:22:33:44:55:66") # Can raise BluetoothError when autodetecting port
str(query) # Can raise BluetoothError when device is down or port is wrong
# Can raise BatteryQueryError when the device is unsupported
except BluetoothError as e:
# Handle device is offline
...
except BatteryQueryError as e:
# Handle device is unsupported
...There is also a GNOME extension for integrating this program with GNOME desktop environment: https://extensions.gnome.org/extension/3991/bluetooth-battery/
There is also a Budgie extension for integrating this program with Budgie desktop environment: https://github.com/GaLaXy102/budgie-bluetooth-battery-applet
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-BH002The 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.
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.
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.
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
@drinkcat: For adding support for Nearby/FastPair protocol
❤️ And everyone else that pointed out the issues or helped me with writing the code or testing it.
This project is a free software licensed under GPL-3.0 or newer. For more information see LICENSE