{"id":13599753,"url":"https://github.com/TheWeirdDev/Bluetooth_Headset_Battery_Level","last_synced_at":"2025-04-10T17:32:11.550Z","repository":{"id":37572168,"uuid":"211669942","full_name":"TheWeirdDev/Bluetooth_Headset_Battery_Level","owner":"TheWeirdDev","description":"A python script to get battery level from Bluetooth headsets","archived":false,"fork":false,"pushed_at":"2024-04-21T13:01:28.000Z","size":122,"stargazers_count":772,"open_issues_count":26,"forks_count":80,"subscribers_count":15,"default_branch":"master","last_synced_at":"2025-03-11T20:34:21.002Z","etag":null,"topics":["at-command","battery","battery-level","battery-percentage","bluetooth","bluetooth-devices","bluetooth-headphones","bluetooth-headsets","bluetooth-socket","bluetooth-speaker","bluez","headphones","headset","linux","pybluez","python","python-script","socket"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TheWeirdDev.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-09-29T13:48:25.000Z","updated_at":"2025-02-22T13:00:47.000Z","dependencies_parsed_at":"2023-01-31T08:40:12.678Z","dependency_job_id":"5387c67c-a936-4060-8988-479275f7b96f","html_url":"https://github.com/TheWeirdDev/Bluetooth_Headset_Battery_Level","commit_stats":{"total_commits":98,"total_committers":19,"mean_commits":5.157894736842105,"dds":"0.34693877551020413","last_synced_commit":"63145192bcd1cdddfecb1aedf2e85ee635337a45"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheWeirdDev%2FBluetooth_Headset_Battery_Level","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheWeirdDev%2FBluetooth_Headset_Battery_Level/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheWeirdDev%2FBluetooth_Headset_Battery_Level/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheWeirdDev%2FBluetooth_Headset_Battery_Level/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TheWeirdDev","download_url":"https://codeload.github.com/TheWeirdDev/Bluetooth_Headset_Battery_Level/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248261994,"owners_count":21074229,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["at-command","battery","battery-level","battery-percentage","bluetooth","bluetooth-devices","bluetooth-headphones","bluetooth-headsets","bluetooth-socket","bluetooth-speaker","bluez","headphones","headset","linux","pybluez","python","python-script","socket"],"created_at":"2024-08-01T17:01:10.738Z","updated_at":"2025-04-10T17:32:11.538Z","avatar_url":"https://github.com/TheWeirdDev.png","language":"Python","readme":"# 🔋🎧 Bluetooth Headset Battery Level\n\nThis is a python script to fetch the battery charge level of some Bluetooth headsets.\n\nYou need python 3.6 or newer to run the script.\n\nTable of Contents\n=================\n\n* [How to run](#️-how-to-run)\n    * [Option 1: Install from PyPI](#option-1-install-from-pypi)\n    * [Option 2: Download this repository](#option-2-download-this-repository)\n    * [Option 3: Docker](#option-3-docker)\n    * [Option 4: AUR](#option-4-aur)\n* [Library usage](#library-usage)\n* [GNOME Extension](#gnome-extension)\n* [Budgie Applet](#budgie-applet)\n* [Finding MAC address](#finding-mac-address)\n* [It didn't work?](#it-didnt-work)\n* [Still doesn't work?](#still-doesnt-work)\n* [Tested on](#tested-on)\n* [Thanks](#-thanks)\n* [License](#-license)\n\n# ▶️ How to run\n\n### There are four options:\n\n### Option 1: Install from PyPI\nPlease ensure you have the BlueZ and python libraries and header files if you are using Ubuntu/Debian based distros:\n```console\nsudo apt install libbluetooth-dev python3-dev\n```\n\nIf you are using *OpenSUSE*, you will need to install `bluez`, `bluez-devel`, `python3-devel`, `python3-pybluez`\n\nThen, install with pip:\n```console\npip3 install bluetooth_battery\n\nbluetooth_battery BT_MAC_ADDRESS_1 ...\n```\n\n**You can input addresses for as many devices as you want separated by space.**\n\n_the dependency `pybluez` should be installed automatically, but if not, you may need to install it manually_\n\n--------\n\n### Option 2: Download this repository\n\n```console\ncd Bluetooth_Headset_Battery_Level\nchmod +x bluetooth_battery.py\n\n./bluetooth_battery.py BT_MAC_ADDRESS_1 ...\n```\n\n_make sure you have `python-pybluez` or `python3-pybluez` or `python3-bluez` installed on your system._\n\n--------\n\n### Option 3: Docker\n\nYou must have docker installed on your system.\nClone the repository using `git clone` command. Then run:\n\n```console\ncd Bluetooth_Headset_Battery_Level\ndocker build -t bluetooth_battery_level .\n```\n\nOnce the build is complete you can use the below command to run the program:\n\n```console\ndocker run --rm -ti --privileged --net=host bluetooth_battery_level \"BT_MAC_ADDRESS\"\n```\n\n--------\n\n### Option 4: AUR\n\nYou must have AUR access enabled on your Arch or Manjaro machine.\nYou can install this library using\n\n```console\nyay -S python-bluetooth-battery\n```\n\n_the dependency `pybluez` should be installed automatically, but if not, you may need to install it manually_  \nThis can be done with `pip3 install git+https://github.com/pybluez/pybluez@master`.\n\n--------\n\n## Library usage\n\nTo use this as a library, simply install it using pip or AUR (see above) or require it in your Pipfile.  \nYou can then\n```python\nfrom bluetooth_battery import BatteryStateQuerier, BatteryQueryError, BluetoothError\n                                                   # only for error handling\n```\nand query the Battery State as follows:\n```python\n# Autodetects SPP port\nquery = BatteryStateQuerier(\"11:22:33:44:55:66\")\n# or with given port\nquery = BatteryStateQuerier(\"11:22:33:44:55:66\", \"4\")\n\nresult = int(query)  # returns integer between 0 and 100\n# or\nresult = str(query)  # returns \"0%\"..\"100%\"\n# or\nresult = query.query()  # returns a dictonary, e.g. {'overall': 100, 'left': 100, 'right': 100, 'case': 87}\n```\n\nAs errors can occur in a wireless system, you probably want to handle them:\n\n```python\ntry:\n    query = BatteryStateQuerier(\"11:22:33:44:55:66\")  # Can raise BluetoothError when autodetecting port\n    str(query)                                        # Can raise BluetoothError when device is down or port is wrong\n                                                      # Can raise BatteryQueryError when the device is unsupported\nexcept BluetoothError as e:\n    # Handle device is offline\n    ...\nexcept BatteryQueryError as e:\n    # Handle device is unsupported\n    ...\n```\n\n## GNOME Extension\n\nThere is also a GNOME extension for integrating this program with GNOME desktop environment:\nhttps://extensions.gnome.org/extension/3991/bluetooth-battery/\n\n## Budgie Applet\n\nThere is also a Budgie extension for integrating this program with Budgie desktop environment:\nhttps://github.com/GaLaXy102/budgie-bluetooth-battery-applet\n\n## Finding MAC address\n\nThere 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.\n```\n$ bluetoothctl devices\nDevice E8:AB:FA:XX:XX:XX iTeknic IK-BH002\nDevice D0:77:14:XX:XX:XX Barak's Moto X4\nDevice E8:AB:FA:XX:XX:XX iTeknic IK-BH002\n```\nThe 1st and 3rd would be relevant here, as those are headsets.\n\nThis shows devices that are actually connected.\n```console\n$ bluetoothctl info\nDevice E8:AB:FA:XX:XX:XX (public)\n\tName: iTeknic IK-BH002\n\t...\n```\nSo you can use\n```console\nbluetooth_battery.py $(bluetoothctl info | awk '/^Device/ {print $2}')\n```\nto query the battery of all connected devices.\n\n## It didn't work?\n\nYou 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`\n\nTry port numbers `1 to 30` to find the one that works for your device. (wait a few seconds between each try)\n\nIf that didn't work, **disconnect your device first**, and then try again.\n\n## Still doesn't work?\n\nPlease consider that this script doesn't guarantee to support every bluetooth device.\n\nYou can open a new issue for discussion or check the existing ones for more information.\n\n## Tested on\n\n- [x] ArchLinux (5.6.14)\n- [x] Manjaro (5.14.10)\n- [x] NixOS 20.09 (20.09.2386.ae1b121d9a6)\n- [x] Debian GNU/Linux (bullseye 5.9)\n- [x] Ubuntu/Linux (Focal Fossa 20.04.1)\n- [x] openSUSE (Leap 15.3)\n\n# 🤝 Thanks\n\nSpecial thanks to:\n\n[@clst](https://github.com/clst): For spreading the word!\n\n[@bhepple](https://github.com/bhepple): For his research on fixing the important bug\n\n[@balsoft](https://github.com/balsoft): For thinking outside the box (finding my big mistake)\n\n[@martin-beran](https://github.com/martin-beran): For making it easy to set the port number\n\n[@Bobo1239](https://github.com/Bobo1239): For adding support for Samsung galaxy buds\n\n[@keystroke3](https://github.com/keystroke3): For adding multiple device support to the script\n\n[@jadia](https://github.com/jadia): For docker container support\n\n[@cheriimoya](https://github.com/cheriimoya): For refactoring the code and providing NixOS packages\n\n[@MichalW](https://github.com/MichalW): For making the GNOME shell extension\n\n[@GaLaXy102](https://github.com/GaLaXy102): For re-writing the code, making it cleaner and usable as a library\n\n[@drinkcat](https://github.com/drinkcat): For adding support for Nearby/FastPair protocol\n\n❤️ And everyone else that pointed out the issues or helped me with writing the code or testing it.\n\n# 📜 License\n\nThis project is a free software licensed under GPL-3.0 or newer. For more information see [LICENSE](LICENSE)\n","funding_links":[],"categories":["Python","linux"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FTheWeirdDev%2FBluetooth_Headset_Battery_Level","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FTheWeirdDev%2FBluetooth_Headset_Battery_Level","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FTheWeirdDev%2FBluetooth_Headset_Battery_Level/lists"}