🔋🎧 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.

Table of Contents

• How to run
  • Option 1: Install from PyPI
  • Option 2: Download this repository
  • Option 3: Docker
  • Option 4: AUR
• Library usage
• GNOME Extension
• Budgie Applet
• Finding MAC address
• It didn't work?
• Still doesn't work?
• Tested on
• Thanks
• License

▶️ 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 python-bluetooth-battery

the 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.

---

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
                                                   # only for error handling

and 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
    ...

GNOME Extension

There is also a GNOME extension for integrating this program with GNOME desktop environment: https://extensions.gnome.org/extension/3991/bluetooth-battery/

Budgie Applet

There is also a Budgie extension for integrating this program with Budgie desktop environment: https://github.com/GaLaXy102/budgie-bluetooth-battery-applet

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

• ArchLinux (5.6.14)
• Manjaro (5.14.10)
• NixOS 20.09 (20.09.2386.ae1b121d9a6)
• Debian GNU/Linux (bullseye 5.9)
• Ubuntu/Linux (Focal Fossa 20.04.1)
• openSUSE (Leap 15.3)

🤝 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

@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.

📜 License

This project is a free software licensed under GPL-3.0 or newer. For more information see LICENSE