Here is the best setup (I think so :D) for K-series Keychron keyboards on Linux.
Note: many newer Keychron keyboards use QMK as firmware and most tips here do not apply to them. Maybe the ones related to Bluetooth can be useful, but everything related to Apple's keyboard module (hid_apple) on Linux, won't work. As far as I know, all QMK-based boards use the hid_generic module instead. Examples of QMK-based boards are: Q, Q-Pro, V, K-Pro, etc.
Most of these commands have been tested on Ubuntu 20.04 and should also work on most Debian-based distributions. If a command happens not to work for you, take a look in the comment section.
Older Keychron keyboards (those not based on QMK) use the hid_apple driver on Linux, even in the Windows/Android mode, both in Bluetooth and Wired modes.
By default, this driver uses the F-keys as multimedia shortcuts and you have to press Fn + the key to get the usual F1 through F12 keys.
In order to change this, you need to change the fnmode parameter for the hid_apple kernel module.
Here's some documentation on it, but a quick summary can be found below:
- 0 =
disabled: Disable the 'fn' key. Pressing 'fn'+'F8' will behave like you only press 'F8'- 1 =
fkeyslast: Function keys are used as last key. Pressing 'F8' key will act as a special key. Pressing 'fn'+'F8' will behave like a F8.- 2 =
fkeysfirst: Function keys are used as first key. Pressing 'F8' key will behave like a F8. Pressing 'fn'+'F8' will act as special key (play/pause).
You can temporarily set the value (for testing, for example) by doing:
# replace <value> below with 0, 1 or 2
# example: echo 2 | sudo tee /sys/module/hid_apple/parameters/fnmode
echo <value> | sudo tee /sys/module/hid_apple/parameters/fnmodeTest how the keyboard behaves after each value. Pick the one the works for you. Once you have found the value that works for you, you can make the change permanent:
- Create the file
/etc/modprobe.d/hid_apple.conf - Add this line to the file:
options hid_apple fnmode=<value>, replacing<value>with the one that worked for you in the previous step (0, 1 or 2) - Save the file
- Run
sudo update-initramfs -u - Reboot
Here's a script, for convenience:
# replace <value> below with the one that worked for you in the previous step (0, 1 or 2)
# example: echo "options hid_apple fnmode=2 | sudo tee /etc/modprobe.d/hid_apple.conf"
# this will erase any pre-existing contents from /etc/modprobe.d/hid_apple.conf
echo "options hid_apple fnmode=<value>" | sudo tee /etc/modprobe.d/hid_apple.conf
# the "-k all" part is not always needed, but it's better to do that for all kernels anyway
sudo update-initramfs -u -k all
sudo systemctl rebootIf get stuck with numpad mode: Double hit F6 or fn + F6.
If your keyboard takes too long to connect to your computer over Bluetooth (for example, when you press a key and wakes it up), you can enable the Bluetooth fast connect. This usually makes the keyboard connect in less than 1 second.
Some users have reported issues with Bluetooth headphones such as popping audio and general instability, but I haven't experienced anything like that.
- Edit the file /etc/bluetooth/main.conf
- Uncomment FastConnectable config and set it to true:
FastConnectable = true - Uncomment
ReconnectAttempts=7(set the value to whatever number that you want) - Uncomment
ReconnectIntervals=1, 2, 3
If your keyboard just won't reconnect after sleep, it might be because your Bluetooth card or dongle was automatically suspended by the operating system.
You can disable the auto suspend feature for USB Bluetooth dongles by changing the settings for the btusb module.
Note: you might need to target a different module if your Bluetooth controller is somehow using some other module. The options and values themselves might change as well. You need to check the documentation for the module your Bluetooth controller uses. Most USB Bluetooth dongles (and sometimes internal cards that are wired to the USB bus) use btusb. Please check if the btusb module is used by your controller first.
# Disable autosuspend for btusb to make the bluetooth keyboard work again
# this will erase any pre-existing contents from /etc/modprobe.d/btusb_disable_autosuspend.conf
echo "options btusb enable_autosuspend=n" | sudo tee /etc/modprobe.d/btusb_disable_autosuspend.conf
sudo update-initramfs -uNow reboot your computer, or run:
sudo modprobe -r btusb
sudo systemctl restart bluetooth
sudo modprobe btusbWhen your computer wakes up from sleep mode, the Bluetooth controller might not turn on automatically. In order to force it to do so, we can create a script that will be executed every time the computer comes back from sleep mode.
Note: just like in the previous step, this script assumes your Bluetooth controller uses the btusb module.
# Unload the btusb module, restart the bluetooth service and reload the module again
# post = after the computer wakes up
sudo tee /lib/systemd/system-sleep/bt << EOT
#!/bin/sh
case $1 in
post)
modprobe -r btusb
sleep 1
service bluetooth restart
sleep 1
modprobe btusb
;;
esac
EOT
# Now let's make the script executable
sudo chmod +x /lib/systemd/system-sleep/btIf the steps above haven't done it for you, try checking kurgol/keychron. Currently, it only mentions K2 and K6 keyboards, but the tips should work for most Keychron boards.
In August 2024 I had a problem with bluetooth, which I solved myself, but the solution might help others too, so I post it here:
After some Linux-Update, bluetooth did not connect, or it apeared it is connecting and immediately disconnecting. I found that the cause was a Security Fix for a security issue, which prevented my Keychron Keyboard K8 pro from connecting by bluetooth. USB still worked.
A workaraound which helped me (running Mint 22 which is based on Ubuntu 24.04) described there: en: https://ubuntu.com/security/CVE-2023-45866 , and it is:
The workaround introduces the security leak again, which did not matter in my case, but you should know about, and it might matter in your case. This is the description of the security-Issue : https://github.com/skysafe/reblog/blob/main/cve-2024-0230/README.md .