{"id":5404,"date":"2024-11-04T15:12:05","date_gmt":"2024-11-04T14:12:05","guid":{"rendered":"https:\/\/pmortensen.eu\/world2\/?p=5404"},"modified":"2026-01-31T03:54:24","modified_gmt":"2026-01-31T02:54:24","slug":"the-battery-state-of-a-keychron-qmk-based-keyboard-can-be-displayed-in-the-operating-system","status":"publish","type":"post","link":"https:\/\/pmortensen.eu\/world2\/2024\/11\/04\/the-battery-state-of-a-keychron-qmk-based-keyboard-can-be-displayed-in-the-operating-system\/","title":{"rendered":"The battery state of a wireless Keychron QMK-based keyboard can be displayed in the operating system"},"content":{"rendered":"

The short version: A wireless QMK<\/a>-based Keychron<\/a> keyboard can provide the information about the battery state, e.g. “81%”, to the operating system, just like, for example, a wireless computer mouse. Though the operating system may have to be configured for it to work, and it may not work for all Keychron keyboard models.<\/p>\n

An example is a Keychron V6 Max<\/a> on Ubuntu 22.04<\/a> (Jammy Jellyfish), after making some configuration changes in the operating system (it isn’t necessary to install any additional software). The battery state is shown<\/a> in “Settings”<\/em> → “Power”<\/em>, along with other wireless devices that provide the information, e.g., mice and headsets.<\/p>\n

Introduction<\/h2>\n

On the subreddit<\/a> r\/Keychron<\/a>, questions about displaying the battery state in the operating system for Keychron keyboards, like for other wireless devices, say mice and headphones, is an FAQ<\/a>. But not much real information is usually provided.<\/p>\n

Thus I decided to dig deeper. I couldn’t get it to work at all on Ubuntu 20.04<\/a> (Focal Fossa) using a prescribed way<\/a>, including for mice and headsets for which it was expected to work. The keyboard didn’t provide the “Battery Percentage” line in the output from “info” in ‘bluetoothctl’.<\/p>\n

But using a newer Ubuntu version (Ubuntu 22.04) and the described configuration change, I could get the battery to show in the GUI for both a ‘2.4  GHz<\/a>‘ mouse, two Bluetooth headsets, and a Keychron V6 Max<\/a> keyboard.<\/p>\n

The charge state can be displayed on the Keychron keyboard itself by Fn<\/em><\/strong> + B<\/em><\/strong>, but this is about the information being transferred to the computer and being shown in the GUI.<\/p>\n

The configuration change in Linux<\/h2>\n

It is essentially as in here<\/a>. The value-add here is to test it<\/em><\/strong> on particular versions of Ubuntu, and for particular Keychron keyboards to find out if and where it actually works (or not). Also, caveats and testing steps are provided to be confident it will work (instead of only doing blind configuration changes).<\/p>\n

It can be done as (from the command line<\/a>):<\/p>\n

\r\nsudo vi \/etc\/bluetooth\/main.conf\r\n<\/pre>\n
In file main.conf<\/em>, add a line with this content:<\/p>\n
\r\nExperimental = true\r\n<\/pre>\n
Notes<\/em><\/strong>: <\/p>\n
    \n
  1. The line should be in the “[General]”<\/em> section, not, for example, the “[Policy]”<\/em> section.<\/li>\n
  2. Proficiency in using vi<\/a> or Vim<\/a> is presumed (including quitting it<\/a>…). If not, use some other editor, like Geany<\/a>. But it must be run with administrator privileges (in order to make changes to file main.conf<\/em>), and this may change an application’s normal behaviour… (because it is run as another user)<\/li>\n<\/ol>\n
    Then, from the command line, restart the Bluetooth service in order to apply the change (alternatively, restart the computer):<\/p>\n
    \r\nsudo systemctl restart bluetooth\r\n<\/pre>\n
    Check that the line with “Experimental” is accepted:<\/p>\n
    \r\nsystemctl status bluetooth\r\n<\/pre>\n
    The output should not<\/em><\/strong> contain “Unknown key Experimental for group General”.<\/p>\n
    Note that, despite this 2019-05-03 Stack Overflow answer<\/a>, it actually does work on Ubuntu 22.04 (or at least the ‘dbus-send’ line didn’t work at all (“Error org.freedesktop.DBus.Error.InvalidArgs: No such interface ‘org.bluez.Battery1′”<\/em>)).<\/p>\n
    Test that the battery status information is provided by the device<\/h3>\n
    First power on and pair the Bluetooth devices. And test that they work in normal operation.<\/p>\n
    A gotcha<\/em><\/strong>: Only connect one Bluetooth headset at a time… For testing each headset in turn, power the other headsets off.<\/p>\n
    From the command line, identify the devices (and get their MAC addresses for use in subsequent steps):<\/p>\n
    \r\nbluetoothctl devices\r\n<\/pre>\n
    Sample output:<\/p>\n
    \r\nDevice 20:74:CF:51:62:CA Titanium by AfterShokz\r\nDevice 00:02:3C:9C:29:CF Zen Hybrid (SX:<C@FrxG'fK)\r\nDevice E5:EF:C8:61:40:DF Keychron V6 Max\r\nDevice 6C:93:08:65:8E:E6 Keychron K5 Pro\r\n<\/pre>\n
    Note that this output also contains information about devices connected in the past, so a device’s presence in this list does not<\/em> guarantee it will work (the response may be something like “Device E5:EF:C8:61:40:DF not available”<\/em>). Also note that the MAC addresses may not be stable.<\/p>\n
    Test a device, for example “Keychron V6 Max”, for the presence of the battery state information:<\/p>\n
    \r\necho -e "connect E5:EF:C8:61:40:DF\\ninfo\\n" | bluetoothctl\r\n<\/pre>\n
    It can also be done interactively:<\/p>\n
    \r\nbluetoothctl\r\nconnect E5:EF:C8:61:40:DF\r\ninfo\r\n<\/pre>\n
    Sample output:<\/p>\n
    \r\nDevice E5:EF:C8:61:40:DF (random)\r\n   \tName: Keychron V6 Max\r\n   \tAlias: Keychron V6 Max\r\n   \tAppearance: 0x03c1\r\n   \tIcon: input-keyboard\r\n   \tPaired: yes\r\n   \tTrusted: yes\r\n   \tBlocked: no\r\n   \tConnected: yes\r\n   \tWakeAllowed: no\r\n   \tLegacyPairing: no\r\n   \tUUID: Generic Access Profile    (00001800-0000-1000-8000-00805f9b34fb)\r\n   \tUUID: Generic Attribute Profile (00001801-0000-1000-8000-00805f9b34fb)\r\n   \tUUID: Device Information        (0000180a-0000-1000-8000-00805f9b34fb)\r\n   \tUUID: Battery Service           (0000180f-0000-1000-8000-00805f9b34fb)\r\n   \tUUID: Human Interface Device    (00001812-0000-1000-8000-00805f9b34fb)\r\n   \tUUID: Vendor specific           (00010203-0405-0607-0809-0a0b0c0d1912)\r\n   \tModalias: usb:v3434p0961d0113\r\n   \tManufacturerData Key: 0x0006\r\n   \tManufacturerData Value:\r\n     03 00 80 4b 65 79 63 68 72 6f 6e 20 4b 42        ...Keychron KB\r\n   \tAdvertisingFlags:\r\n     05                                               .\r\n   \tBattery Percentage: 0x56 (86)\r\n<\/pre>\n
    In this case, the output contains a line with “Battery Percentage” (the very last line):<\/p>\n
    \r\n    Battery Percentage: 0x56 (86)\r\n<\/pre>\n
    Which is interpreted as 86%.<\/p>\n
    The output also contains a line with “UUID: Battery Service  (0000180F-0000-1000-8000-00805F9B34FB)”<\/em>.<\/p>\n
    To extract just the battery state information (for MAC address E5:EF:C8:61:40:DF in this example):<\/p>\n
    \r\necho -e "connect E5:EF:C8:61:40:DF\\ninfo\\n" | bluetoothctl | grep "Battery Percentage" \r\n<\/pre>\n
    And with a timestamp (for MAC address E5:EF:C8:61:40:DF in this example):<\/p>\n
    \r\nclear ; echo -n "Time: $(date +%FT%T_%N_ns)" ; echo -e "connect E5:EF:C8:61:40:DF\\ninfo\\n" | bluetoothctl | grep "Battery Percentage" \r\n<\/pre>\n
    Ifs and buts<\/h3>\n
    In the test, it worked on Ubuntu 22.04, but not on Ubuntu 20.04. A reason could be a different version of BlueZ<\/a> (use “bluetoothd -v” or “bluetoothctl -v”):<\/p>\n