Are you tired of not knowing how much battery your Bluetooth headset has left? Well, worry no more! With this Python script, you can easily fetch the battery charge level of your Bluetooth headsets. It’s time to take control of your wireless listening experience.

How to Get Started

Before you dive into checking your headset’s battery level, make sure you have Python 3.6 or newer installed on your system. Once you’re all set, you have four options to choose from:

Option 1: Install from PyPI

This option is for those who prefer the convenience of package installation from PyPI. If you’re using Ubuntu/Debian based distros, ensure you have the BlueZ and Python libraries and header files installed. For OpenSUSE users, make sure to install bluez, bluez-devel, python3-devel, and python3-pybluez. Then, simply use pip to install the script.

You can input addresses for as many devices as you want, separated by a space. The dependency pybluez will be installed automatically, but if it’s not, you can install it manually.

Option 2: Download the Repository

If you’re more inclined towards a direct approach, you can download this repository. Before doing so, ensure that you have python-pybluez, python3-pybluez, or python3-bluez installed on your system.

Option 3: Docker

For those who prefer containerization, this option is for you. Start by making sure you have Docker installed on your system. Clone the repository using the git clone command, and then proceed to build and run the program. It’s as simple as that!

Option 4: AUR

If you’re an Arch or Manjaro user with AUR access enabled, you can easily install this library. The dependency pybluez will be installed automatically, but in case it’s not, you can manually install it using the command pip3 install git+https://github.com/pybluez/pybluez@master.

Library Usage

This script can also be used as a library for more advanced integration. To use it, simply install it using pip or AUR, or require it in your Pipfile. From there, you can query the battery state of your Bluetooth headsets with ease. Don’t forget to handle any potential errors that may occur in a wireless system.

Integrations

To make your life even easier, there are two handy integrations available:

GNOME Extension

If you’re a GNOME desktop environment user, you can seamlessly integrate this program with your setup using the GNOME extension. It’s all about simplifying your user experience.

Budgie Applet

For Budgie desktop environment users, there’s a special Budgie extension designed to integrate this program flawlessly. Take your wireless audio control to the next level.

Finding Your MAC Address

Not sure how to find the MAC address of your Bluetooth device? No worries! There are various utilities available to help you. One such utility, included in the BlueZ package, can provide you with a list of all the devices it knows about, even if they’re not currently available. Look for the 1st and 3rd devices listed, as those are typically headsets. If you want to see the devices that are actually connected, use the command provided. Armed with your MAC address, you can now query the battery of all connected devices.

Troubleshooting Tips

Encountering issues? We’ve got you covered. Here are a few tips to get things back on track:

• If the script doesn’t work, try setting the port number manually. Add a dot at the end of the MAC address, followed by the desired port number (e.g., 00:00:00:00:00:00.3). Test different port numbers from 1 to 30, waiting a few seconds between each try.

• If manual port number assignment doesn’t solve the problem, make sure to disconnect your device first and then try again. Sometimes a fresh start is all you need.

• Keep in mind that this script doesn’t guarantee support for every Bluetooth device. If you’re still experiencing difficulties, don’t hesitate to open a new issue for discussion or check out existing ones for more information.

Tested on Various Systems

Rest assured, this script has been put through its paces and successfully tested on the following systems:

• 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)

Special Thanks

I would like to express my heartfelt gratitude to everyone who contributed to this project. Your contributions, whether big or small, have made this script what it is today. Special thanks go out to the following individuals:

• @clst: For spreading the word!
• @bhepple: For your research on fixing an important bug
• @balsoft: For thinking outside the box and finding my big mistake
• @martin-beran: For simplifying the process of setting the port number
• @Bobo1239: For adding support for Samsung Galaxy Buds
• @keystroke3: For enabling multiple device support in the script
• @jadia: For adding Docker container support
• @cheriimoya: For refactoring the code and providing NixOS packages
• @MichalW: For creating the GNOME shell extension
• @GaLaXy102: For rewriting the code, making it cleaner, and turning it into a library

And lastly, to everyone else who contributed by pointing out issues, helping with code and testing, thank you from the bottom of my heart. This project is a labor of love, and your support means the world to me. ❤️

Remember, this project is released under the GPL-3.0 or newer license. For more information, please refer to the LICENSE file.

Now, go forth and enjoy your Bluetooth headsets without the worry of running out of battery. Happy listening!