107

How can I check the battery level of a connected bluetooth device? The device shows the battery level on Android so I'm assuming the device supports the GATT-based Battery Service. However, by entering "menu gatt" in bluetoothctl and then listing the GATT attributes of the device with "list-attributes [dev]", nothing shows up.

A similar question was posted to SO but the OP seems to have found a solution that doesn't work for me. When I run "info [dev]" in bluetoothctl I don't see the UUID for Battery Service.

I would prefer a solution that runs on the command line and is distro-agnostic.

Please let me know if this question should be posted on SuperUser instead.

21
  • What type of device are we talking about? Battery level can be reported via many different profiles over Bluetooth, not only via LE GATT service... can you use a BLE explore app or the like to browse the GATT services and confirm what it actually supports? Mar 3, 2018 at 8:40
  • Can you recommend a BLE explore app? Is there a way to know what type of device is connected from a command line tool (eg bluetoothctl)?
    – Ricardo
    Mar 4, 2018 at 22:44
  • I check the contents of /sys/class/power_supply, as explained in this other answer. Sep 4, 2018 at 11:20
  • 2
    @DamianNadales my /sys/class/power_supply only contains AC and BAT0.
    – Ricardo
    Sep 4, 2018 at 23:01
  • 4
    How does one access the A2DP bluetooth profile? How do I check whether the battery information is available through that profile?
    – Ricardo
    May 28, 2019 at 22:21

14 Answers 14

40

For me running this in terminal worked:

upower --dump
1
  • 30
    Thanks Yash for your suggestion. Unfortunately this doesn't work for my setup. Only the laptop's battery battery_BAT0, the line power line_power_AC, and the mysterious /org/freedesktop/UPower/devices/DisplayDevice device show up in the output.
    – Ricardo
    Oct 4, 2019 at 23:19
38

This might be a bit late to the party but for me this Python project has worked fine:

https://github.com/TheWeirdDev/Bluetooth_Headset_Battery_Level

I only had to change the port in line 57 to 3 for my no-name X5 headset. If it hangs or errors with "connection refused" try a different port.

The Python program uses AT commands via RFCOMM and should work while Pulseaudio is using the A2DP sink (mine reconnects). Python 3 is needed as 2 doesn't have BT-Serial sockets. Windows will probably not work as it lacks bluez. It basically does the same thing as the Pulseaudio hack here: https://stackoverflow.com/a/56390625/920122

If you want to look at the commands as they are exchanged, try my debug fork: https://github.com/clst/Bluetooth_Headset_Battery_Level

5
  • 2
    Hey @clst, thanks for the answer! It looks promising! You mean the port in line 56 of the original code and 58 in your fork? The one that says s.connect((BT_ADDRESS, 3))? I tried with all the numbers from 1 to 11 and didn't work. Should I continue trying with more port numbers? Do you know what's the range of numbers in which the port may lie?
    – Ricardo
    Jan 30, 2020 at 2:27
  • 4
    I tried again, this time after disconnecting from the device with bluetoothctl. It works!! :) I'm using your fork and port number 3. The only caveat is that I can't use this while listening to music, as I have to disconnect from the device to use the python script.
    – Ricardo
    Jan 30, 2020 at 2:36
  • 1
    Yeah, those port numbers are device specific and there is no common practice so you would have to try them. If the RFCOMM works while the device is doing other things (like A2DP) is also device specific. Until someone codes a robust auto detect system this is the best we have :)
    – clst
    Jan 31, 2020 at 13:12
  • @clst do you know if this approach can be used to get battery level of apple watch and apple pencil over bluetooth as well?
    – Jack Chen
    May 8, 2020 at 20:45
  • I have no idea. Since this is an Apple proprietary protocol it might. I have no Apple hardware so I can't be much help.
    – clst
    May 16, 2020 at 0:32
28

You don't see Battery Level in the list of GATT characteristics since Bluez v5.48 because this specific GATT characteristic was moved into DBUS org.bluez.Battery1 interface.

From the command line:

  1. Connect to your target BLE device with bluetoothctl
  2. And then request DBUS by running: dbus-send --print-reply=literal --system --dest=org.bluez /org/bluez/hci0/dev_<mac_address_of_your_ble_peripheral> org.freedesktop.DBus.Properties.Get string:"org.bluez.Battery1" string:"Percentage"

In my case with my BLE peripheral with the following MAC address C3:41:A6:C8:93:42:

$ dbus-send --print-reply=literal --system --dest=org.bluez \
    /org/bluez/hci0/dev_C3_41_A6_C8_93_42 org.freedesktop.DBus.Properties.Get \
    string:"org.bluez.Battery1" string:"Percentage"
   variant       byte 94

Note: You could potentially scan and connect to your device using Bluez DBUS API.

9
  • 23
    When following these instructions, I get this error $ dbus-send --print-reply=literal --system --dest=org.bluez /org/bluez/hci0/dev_E9_09_EF_A6_24_70 org.freedesktop.DBus.Properties.Get string:"org.bluez.Battery1" string:"Percentage" Error org.freedesktop.DBus.Error.InvalidArgs: No such interface 'org.bluez.Battery1'
    – Ricardo
    Mar 11, 2019 at 21:06
  • 3
    I have just tried 5.50 from the Bluez sources and it also work for me. Are you sure your device expose battery service? Can you run this command: dbus-send --system --print-reply --dest=org.bluez /org/bluez/hci0/dev_E9_09_EF_A6_24_70 org.freedesktop.DBus.Introspectable.Introspect
    – OlivierM
    Apr 15, 2019 at 7:16
  • 1
    Hi, I'm having the same problem as @Ricardo, I'm using bluez 5.50-6 on Archlinux and I also don't have the org.bluez.Battery1 interface; my introspect output is gist.github.com/Terseus/d78e6ca711cef914e52bffd757d40c5b
    – Terseus
    May 29, 2019 at 7:33
  • 1
    @Terseus, same as Ricardo. Your device use A2DP (Advanced Audio Distribution Profile), your batterz information might be accessible through this profile. See my comment: stackoverflow.com/questions/49078659/…
    – OlivierM
    May 29, 2019 at 12:17
  • 1
    I got rid of the No such interface 'org.bluez.Battery1' issue, after enabling experimental features on the bluetooth daemon. Got that fix from stackoverflow.com/a/49125875/589216. I'm currently on bluetoothd version 5.64 on Ubuntu 22.04.3. It now even shows up in KDE's "battery-panel".
    – andred
    Oct 13, 2023 at 6:04
22

This is such a great question, ahead of development and tools that are available at the moment.

The short answer (in October 2018)

you have to write it yourself! It won't be a one liner in the terminal. I am going to write this for myself in Python, but C has a little more documentation, so if you are skilled with C go for it.

The long answer, but it's more a recommended starting point:

  1. Tony D: https://youtu.be/5fQR2PHMDWE?t=4644 managed to use bluetoothctl to read attributes and send data to a bluetooth device. Definitely check the video information, you will find great links and references: https://learn.adafruit.com/introduction-to-bluetooth-low-energy/gatt
  2. Szymon Janc: https://youtu.be/VMDyebKT5c4 developer and contributer to the LINUX Bluetooth Stack
  3. Definitely check out how this question is answered on Mobile devices. For Android it's the BAS (Battery Service): https://android.stackexchange.com/questions/106073/displaying-bluetooth-gadgets-battery-status-on-the-phone

    On Android 8.0.1

4
  • I checked the first video and the guy uses list-attributes in bluetoothctl, which doesn't show anything in my case. That's why I'm thinking maybe there's a non-GATT way to check the battery status? I checked the other links too, except the talk by Szymon Janc which is a bit too long. Please let me know if you're successful in writing a program that reads the battery level of a BLE device.
    – Ricardo
    Oct 23, 2018 at 3:06
  • Don't forget to use sudo when running bluetoothctl. But yeah, there really isn't a comfortable way to do this in Linux, today. That is also the motivation for this python project: github.com/peplin/pygatt#motivation I am not going to go further with my research, of this subject due to lack of time. Use the above git project and example code, if you decide to continue this Path of solving this issue. github.com/peplin/pygatt#example-use I will probably only be able to help again, next year. Good luck!
    – VeRo
    Oct 28, 2018 at 16:16
  • 1
    Thanks @VeRo for the help! I didn't know I was supposed to run bluetoothctl as root (using sudo). I tried that and still nothing shows up when I do list-attributes after connecting to the device. Not sure what should be done to get the attribute listed there or what can be done if the device doesn't list any gatt attributes. Cheers!
    – Ricardo
    Oct 31, 2018 at 2:25
  • 3
    Update by (Kernel Developer) something has to register the battery with the power-supply subsystem using power_supply_register (or the variant prefixed with devm_). For the BT HID devices that happens in drivers/hid/hid-input.c and is based on the HID protocol. Other BT devices do not use HID protocol and need their own handler. AFAIK for other device types the highlevel protocols are implemented in userspace/bluez. That would require something like uinput for power-supply, so that bluez can feed battery information back into the kernel. AFAIK nobody is currently working on that.
    – VeRo
    Feb 3, 2020 at 17:08
9

One possible way (although hacky) is to grep inside the journal:

journalctl -b --user-unit pulseaudio -g "Battery Level" -o cat 

(-b to only show information in the current boot. Clearly information in the previous boots are irrelevant)

On my machine this outputs for example

Battery Level: 70%
Battery Level: 70%
Battery Level: 70%
Battery Level: 70%
Battery Level: 70%
Battery Level: 60%
Battery Level: 60%

Pick the last line (which can be done by appending |tail -n 1).

This solution does not distinguish whether the Bluetooth device is currently connected, or which one is in case there are more than one.


Alternative includes running bluetoothctl disconnect, then use the script in the accepted answer https://stackoverflow.com/a/59709851/5267751 to get the battery level, then run bluetoothctl connect again. This is usually not acceptable if you're currently connected, but it works.


Another alternative, if it works for you, is to use an experimental feature of bluez package. Refer to https://askubuntu.com/a/1420501/996767.

0
6

On Ubuntu 20+, it shows the battery under the devices tab in the power panel

enter image description here

2
  • 1
    That's great news! Hopefully this feature appears soon in KDE as well.
    – Ricardo
    Mar 23, 2022 at 22:45
  • 1
    Can't see that in Ubuntu 22.04, experimental=true has already been set. am I missing anything?
    – Roop Kumar
    Apr 14, 2023 at 12:55
5

Here is a way to get battery level via pulseaudio logs with some hack. My bluetooth headset uses proprietary Apple HFP AT commands, HFP/A2DP protocols are handled by pulseaudio directly. It seems the only way to get those values is through pulse.

3
  • Thanks Vasily and sorry for the long delay. Do you know if there is a way to send those AT commands from the command line (using dbus-send for instance) to obtain the battery level?
    – Ricardo
    Oct 4, 2019 at 23:25
  • You can build pulseaudio yourself and apply mentioned patch. You can modify it: for example, replace pa_log_notice with output to some pipe in /tmp and have app that monitors that pipe. I chose this way. Works for me. That code is triggered only once, when device is paired. You can place it on volume change functions. I think there is a way to add dbus listener to specific command in pulseaudio, so that it will trigger PA to send those AT commands, but this is too compilcated for me. Oct 7, 2019 at 4:38
  • I see. Thanks. I would rather not maintain a fork of pulseaudio.
    – Ricardo
    Oct 7, 2019 at 18:04
4

By default Bluez 'hides' the Battery Service UUID. This is because there is a 'battery plugin' loaded at startup of bluetoothd.

If you don't want the battery plugin to be activated and make the Battery Service UUID visible again to bluetoothctl or any other application, then change the startup command for bluetoothd to be like this: 'bluetoothd -P battery'. That will make sure the battery plugin is not loaded. On a Raspberry Pi the bluetooth.service is located in /lib/systemd/system/bluetooth.service so you need to make the change in that file.

1
  • 3
    Please do not modify packaged unit files (those under /lib or /usr/lib) directly. Systemd offers the systemctl edit interface for modifying units in a way that does not cause issues with package managers. May 30, 2021 at 5:42
2

In the bluez version you are using the Gatt attributes may be experimental.If so you need to enable the experimental characteristics by running the bluetoothd deamon by -E keyword Like "/usr/libexec/bluetooth/bluetoothd -E" this worked for me.

23
  • The bluetoothd deamon is run by systemd when you do "systemctl start bluetooth" right? How can I tell systemd to use the -E parameter? I have bluez version 5.48
    – Ricardo
    Mar 8, 2018 at 19:56
  • While executing the 'systemctl start bluetooth' command you are invoking the bluetooth.service ,search for this service in you home directory.Inside the service you can add the -E parameter to the line invoking the bluetoothd.It comes as part of the bluez package.The line would look something like this "ExecStart=/usr/libexec/bluetooth/bluetoothd" add -E parameter to the end of it "ExecStart=/usr/libexec/bluetooth/bluetoothd -E". Mar 15, 2018 at 5:00
  • After adding this keyword when you connect your device using bluetoothctl app it will list the supported services by your bluetooth device.from that you can select-attribute for the "Battery-Level" service and use read command to get the value.There are also ways to get the battery level directly by usinf dbus-send a utilit used to send dbus commands. Mar 15, 2018 at 5:05
  • Thank you very much for your help. I changed the line as you suggested, then did "systemctl deamon-reload" then "systemctl restart bluetooth" (both as root). Then started bluetoothctl, connected the device, "menu gatt", "list-attributes [dev]"... but still nothing. Any ideas what might be going on?
    – Ricardo
    Mar 20, 2018 at 22:42
  • 1
    sudo ls /var/lib/bluetooth/40:xx:xx:xx:xx:xx/E9:xx:xx:xx:xx:xx/ shows there's only the file info in it but no file attributes.
    – Ricardo
    Jun 11, 2018 at 1:50
1

(This answer is specific to headphones/headsets)

I'd been using the Python program from clst's answer for some time and although it worked, it required me to connect, then disconnect and run it again. If I understand the problem correctly, that happens because only one program can open a socket to talk to the bluetooth device, so it ends up fighting with PulseAudio over it.

I've recently found out about hsphfpd.

hsphfpd is specification with some prototype implementation used for connecting Bluetooth devices with HSP and HFP profiles on Linux operating system.

Basically, since only one program can communicate with the headset at once and it wouldn't make sense to implement battery level reporting in an audio server, nor implement audio in a power management software, it moves that functionality to an external daemon. That way, PulseAudio and whatever can both use the headset at the same time. There is a version of PulseAudio patched to use hsphfpd. Even though these are both still prototypes, they seem to work very well.

hsphfpd reports battery status (and other stuff) through DBus, so to get it from the command line, you can just do

dbus-send --system --dest=org.hsphfpd --print-reply /org/hsphfpd/hci0/dev_XX_XX_XX_XX_XX_XX/hsp_hs org.freedesktop.DBus.Properties.Get string:org.hsphfpd.Endpoint string:BatteryLevel

or even call it from a program.

Both of these are available in the AUR, if you use Arch Linux.

5
  • When running dbus-send --system --dest=org.hsphfpd --print-reply /org/hsphfpd/hci0/dev_XX_XX_XX_XX_XX_XX/hsp_hs org.freedesktop.DBus.Properties.Get string:org.hsphfpd.Endpoint string:BatteryLevel I get method return time=1606703580.141858 sender=:1.3546 -> destination=:1.3550 serial=44 reply_serial=2 variant int16 -1
    – Ricardo
    Nov 30, 2020 at 2:34
  • @Ricardo You could try hfp_hf or hfp_ag instead of hsp_hs. If that doesn't work, open pavucontrol and switch to either HFP or HSP (even if they say unavailable), then try again. After this, you can switch back to whatever profile you were using, or else you'll be stuck with very low quality audio. If that still doesn't work, try using QDBusViewer to inspect the org.hsphfpd service and find any alternate paths you may be able to use. Let me know if you manage to make it work.
    – LHLaurini
    Nov 30, 2020 at 13:37
  • When I use hfp_hf I get variant int16 40. I guess that 40 means 40% battery left. Not sure how to verify that as the new setup makes the program in the accepted answer not able to connect to the device. Maybe I'll just wait and see if the number goes down with use. Thanks for the help! When using qdbus --system org.hsphfpd I see that both hfp_hf and hsp_hs are available for this device.
    – Ricardo
    Dec 1, 2020 at 17:24
  • @Ricardo That's correct. As far as I know, hsphfpd uses a similar method from the script from the accepted answer, so the value should be the same. Also, you could also connect to the PropertiesChanged signal to be notified when the battery level changes. Note that it only updates if the Connected property is true.
    – LHLaurini
    Dec 1, 2020 at 17:36
  • Cool. By charging the headphones the number increased to 60. I think it might only be sensitive to 10% increases and decreases. Thanks a lot! This answer is very useful.
    – Ricardo
    Jan 11, 2021 at 2:03
1

One way to check the battery for my JBL Headset was to issue the command below: (Command issued in Ubuntu 22.04)

pactl link sink

This will show the following, in my case:

Sink #2
    State: RUNNING
    Name: bluez_sink.<MAC>.a2dp_sink
    Description: JBL TUNE710BT
    Driver: module-bluez5-device.c
    Sample Specification: s16le 2ch 44100Hz
    Channel Map: front-left,front-right
    Owner Module: 24
    Mute: no
    Volume: front-left: 32660 /  50% / -18,15 dB,   front-right: 32660 /  50% / -18,15 dB
            balance 0,00
    Base Volume: 65536 / 100% / 0,00 dB
    Monitor Source: bluez_sink.<MAC>.a2dp_sink.monitor
    Latency: 56606 usec, configured 42414 usec
    Flags: HARDWARE HW_VOLUME_CTRL DECIBEL_VOLUME LATENCY 
    Properties:
        bluetooth.protocol = "a2dp_sink"
        bluetooth.codec = "sbc"
        device.description = "JBL TUNE710BT"
        device.string = "<MAC>"
        device.api = "bluez"
        device.class = "sound"
        device.bus = "bluetooth"
        device.form_factor = "headset"
        bluez.path = "/org/bluez/hci0/dev_<MAC>"
        bluez.class = "0x240404"
        bluez.alias = "JBL TUNE710BT"
        bluetooth.battery = "100%"
        device.icon_name = "audio-headset-bluetooth"
        device.intended_roles = "phone"
    Ports:
        headset-output: Headset (type: Headset, priority: 0, available)
    Active Port: headset-output
    Formats:
        pcm

As it' possible to see, exists a Property called bluetooth.battery that shows the battery percentage.


Following the procedure stated in https://askubuntu.com/a/1420501/82644 I could show the battery percentage under Settings > Power and also using upower --dump

Step by Step

  1. Add Experimental = True after [General] to /etc/bluetooth/main.conf
  2. Restart the bluetooth service systemctl restart bluetooth
  3. Connect (or Reconnect) you bluetooth device
  4. Check battery percentage at Settings > Power
sudo cp /etc/bluetooth/main.conf /etc/bluetooth/main.bkp
sed '/General]/a Experimental = True' /etc/bluetooth/main.conf | sudo tee /etc/bluetooth/main.conf
sudo systemctl restart bluetooth

But a WARNING! After doing that, I can't use this python script https://github.com/TheWeirdDev/Bluetooth_Headset_Battery_Level or pactl list sinks anymore.

0

Am posting this today, because today I have tested this method successfully.
I received a tip from @Mr.Newbie
A python solution: Bluetooth Headset Battery Level by @TheWeirdDev

enter image description here

0

install extension for gnome and "Bluetooth battery indicator" Work perfect

1
  • Your answer could be improved with additional supporting information. Please edit to add further details, such as citations or documentation, so that others can confirm that your answer is correct. You can find more information on how to write good answers in the help center.
    – Community Bot
    Jul 6, 2023 at 8:58
-4

As said by @OlivierM above, the UUID is filtered by bluetoothd. You could undo that and export the UUID just as any other service characteristics by removing the following from the export_service() function in src/gatt-client.c

if (gatt_db_service_get_claimed(attr))
     return;

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.