Skip to content

k6.md

Latest commit

 

History

History
436 lines (286 loc) · 12.2 KB

k6.md

File metadata and controls

436 lines (286 loc) · 12.2 KB

Keychron K6 on Linux

This guide covers the original K6 (non-QMK). If you have a K6 Pro, most hid_apple tips here don't apply -- use Keychron Launcher or VIA instead.

Table of Contents

  1. First Steps
  2. Function Keys
  3. Bluetooth
  4. Battery
  5. Sleep
  6. Key Remapping
  7. Numlock
  8. Swapping Cmd and Alt
  9. Backlight / RGB
  10. Firmware
  11. Keychron Launcher / VIA (QMK boards)
  12. Factory Reset
  13. Troubleshooting
  14. en-GB Keymap Quirks
  15. Resources

First Steps

Before anything else:

  1. Set the physical switch on the back of the keyboard to Windows/Android mode. Mac/iOS mode maps modifier keys incorrectly on Linux.
  2. If you're on kernel 5.19 or newer, function keys should work out of the box. The hid_apple driver auto-detects Keychron keyboards and uses fnmode=3 (auto), which behaves like fnmode=2 for Keychron and fnmode=1 for real Apple keyboards. Check your kernel version with uname -r.

Function Keys

The hid_apple kernel module controls how function keys behave. Since kernel 5.19, the default fnmode=3 handles Keychron keyboards correctly. If your function keys aren't working as expected, you can override the behavior.

Check current mode

cat /sys/module/hid_apple/parameters/fnmode

fnmode values

Value Behavior
0 Fn key disabled entirely
1 F-keys are secondary (press Fn to get F1-F12)
2 F-keys are primary (press Fn to get media keys)
3 Auto -- acts like 2 for Keychron, 1 for Apple (default since kernel 5.19)

Temporary change (lost on reboot)

echo 2 | sudo tee /sys/module/hid_apple/parameters/fnmode

Persistent change

Create or edit /etc/modprobe.d/hid_apple.conf:

options hid_apple fnmode=2

Then rebuild your initramfs:

# Debian / Ubuntu
sudo update-initramfs -u

# Arch
sudo mkinitcpio -P

# Fedora
sudo dracut --force

Reboot for the change to take effect.

Alternative: udev rule

If you prefer a udev rule instead of modprobe.d:

sudo tee /etc/udev/rules.d/80-keychron.rules <<'EOF'
SUBSYSTEMS=="input", ATTRS{name}=="Keychron K6", RUN+="/bin/sh -c 'echo 2 > /sys/module/hid_apple/parameters/fnmode'"
EOF
sudo udevadm control --reload-rules && sudo udevadm trigger

Note: The RUN+= command needs /bin/sh -c '...' wrapping. A bare echo | tee won't work in udev because the pipe is a shell construct.

Testing without reboot

sudo rmmod hid_apple && sudo modprobe hid_apple

Warning: If the K6 is your only input device, this will briefly disconnect it. If the second command fails, you'll need a hard reboot.

All hid_apple parameters

ls /sys/module/hid_apple/parameters/
Parameter Default Description
fnmode 3 Function key behavior (see above)
swap_opt_cmd 0 Swap Alt/Option and Super/Command. 0=default, 1=full swap, 2=left-side only
swap_fn_leftctrl 0 Swap Fn and left Ctrl
swap_ctrl_cmd 0 Swap Ctrl and Cmd (kernel 6.1+)
iso_layout -1 -1=auto, 0=ANSI, 1=ISO

Multiple options can be combined in /etc/modprobe.d/hid_apple.conf:

options hid_apple fnmode=2 swap_opt_cmd=1

NixOS

boot.extraModprobeConfig = ''
  options hid_apple fnmode=2
'';

Bluetooth

Pairing

bluetoothctl
power on
agent on
default-agent
scan on
# Put keyboard in pairing mode: Fn + 1/2/3 (hold 4 seconds, light blinks)
pair <MAC>
trust <MAC>
connect <MAC>

Recommended bluetooth config

Edit /etc/bluetooth/main.conf under [General]:

[General]
FastConnectable = true
ReconnectAttempts = 7
ReconnectIntervals = 1, 2, 4
JustWorksRepairing = always
Experimental = true

Note: JustWorksRepairing must be under [General], not [Policy] -- placing it under [Policy] causes a BlueZ error. Experimental = true is needed for battery reporting on some setups.

Restart bluetooth after changes:

sudo systemctl restart bluetooth

Reconnection after suspend/resume

This is the most common Bluetooth issue. Two fixes, apply both:

1. Disable btusb autosuspend

echo "options btusb enable_autosuspend=n" | sudo tee /etc/modprobe.d/btusb_disable_autosuspend.conf

Rebuild initramfs (see Function Keys for your distro's command) and reboot.

2. Systemd sleep hook

Create /lib/systemd/system-sleep/bt-reconnect:

#!/bin/sh
case $1 in
  post)
    modprobe -r btusb
    sleep 1
    service bluetooth restart
    sleep 1
    modprobe btusb
    ;;
esac
sudo chmod +x /lib/systemd/system-sleep/bt-reconnect

CVE-2023-45866: BlueZ security patch breaking keyboards

A BlueZ security update in 2024 set ClassicBondedOnly=true by default, which breaks reconnection for keyboards using "Just Works" pairing (including Keychron).

Symptom: keyboard connects but no input is received.

Fix: edit /etc/bluetooth/input.conf:

ClassicBondedOnly=false

Warning: This reduces Bluetooth security. The proper mitigation is to ensure the keyboard is fully bonded during initial pairing.

Battery

upower

upower --dump | grep keyboard -A 7

Desktop environments with battery indicator support: GNOME (built-in via Settings > Power), KDE Plasma (bluetooth widget), MATE (mate-power-statistics).

bluetoothctl

bluetoothctl info <MAC> | grep Battery

On-keyboard check

Press Fn + B:

  • Green = >70%
  • Blue = >30%
  • Red = <30%

Note: Battery reporting requires Experimental = true in /etc/bluetooth/main.conf (see Bluetooth). Some setups also need the org.bluez.Battery1 D-Bus interface, which is only exposed with experimental features enabled.

Sleep

The keyboard enters auto-sleep after 10 minutes of inactivity.

Toggle auto-sleep: press Fn + S + O (hold 3 seconds). Wait for the backlight to flash as confirmation.

The K6 Pro has a different default (2 hours), configurable sleep timeout via Keychron Launcher, and a separate 10-minute backlight timeout.

Key Remapping

keyd (recommended -- works on X11, Wayland, and TTY)

keyd is a system-wide key remapping daemon that works everywhere. Available in Arch (pacman -S keyd), Debian 13+, Ubuntu 25.04+, Fedora.

sudo systemctl enable --now keyd

Example /etc/keyd/default.conf:

[ids]
*

[main]
capslock = overload(control, esc)

Reload after editing:

sudo keyd reload

xmodmap (X11 only -- does not work on Wayland)

For X11 users, xmodmap still works. Example: bind Shift + Delete to Insert:

xmodmap -pke | grep Delete
# Find the keycode for Delete (usually 119)
xmodmap -e "keycode 119 = Delete Insert Delete NoSymbol Delete"

Add to ~/.bashrc or ~/.xinitrc to persist across reboots.

XKB custom symbols (Wayland-native)

For GNOME Wayland, put custom symbol files in ~/.config/xkb/symbols/ -- no root access or initramfs rebuild needed.

Numlock

If stuck in Numlock mode, double-tap Fn2 + F6 to disable it. Alternatively, open onboard (on-screen keyboard) and toggle "NmLk".

Swapping Cmd and Alt

To swap the left Alt and Cmd keys and use the keyboard in PC mode, add to /etc/modprobe.d/hid_apple.conf:

options hid_apple swap_opt_cmd=1

This also fixes the right AltGr not working on non-US ISO layouts.

Use swap_opt_cmd=2 to swap only the left-side keys (leaving the right side unchanged).

Rebuild initramfs and reboot (see Function Keys for your distro's command).

Backlight / RGB

The original K6 has no software RGB control from Linux. All lighting is controlled via hardware shortcuts on the keyboard.

OpenRGB has experimental Keychron support via a community merge request, but it's not production-ready for the K6.

The K6 Pro with QMK can control per-key RGB via VIA or Keychron Launcher (wired mode only).

SonixQMK (community -- advanced)

QMK-on-K6 is a community project that flashes QMK onto the original K6 RGB (SN32F24x MCU only). This enables software RGB control via VIA.

Warning: Risk of bricking. Permanently disables Bluetooth. The white-backlit K6 is not supported.

Firmware

Original K6 (non-QMK)

Firmware updates still require Windows. Keychron has not engaged with fwupd/LVFS despite community requests -- there are zero Keychron devices in the LVFS catalog.

The firmware page has the latest version and a changelog.

K6 Pro (QMK)

The K6 Pro can be flashed from Linux using Keychron Launcher or QMK Toolbox. See Keychron Launcher / VIA below.

Keychron Launcher / VIA (QMK boards)

For QMK-based Keychron keyboards (K6 Pro, Q series, V series), you can remap keys and update firmware from Linux.

Setup

  1. Find your device IDs:
lsusb | grep -i keychron
  1. Create udev rules at /etc/udev/rules.d/99-keychron.rules:
KERNEL=="hidraw*", SUBSYSTEM=="hidraw", ATTRS{idVendor}=="3434", MODE="0660", GROUP="users", TAG+="uaccess", TAG+="udev-acl"

For firmware flashing, also add the bootloader rule:

SUBSYSTEM=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="df11", MODE="0666", GROUP="users", TAG+="uaccess", TAG+="udev-acl"
  1. Reload udev:
sudo udevadm control --reload-rules && sudo udevadm trigger
  1. Open launcher.keychron.com or usevia.app in Chromium/Chrome (Firefox does not support WebHID).

Warning: The keyboard must be connected via USB cable. Flashing firmware over Bluetooth will brick the keyboard.

Factory Reset

If Bluetooth is completely broken or the keyboard is behaving erratically:

Fn + J + Z (hold 4 seconds) -- backlight flashes to confirm reset.

After reset, re-enter pairing mode: hold Fn + 1 (or 2/3) for 4 seconds.

Troubleshooting

Problem Fix
F-keys act as media keys Check fnmode value (see Function Keys). On kernel 5.19+ this should be automatic.
Keyboard not responding after suspend Apply both btusb autosuspend fix and systemd sleep hook (see Bluetooth)
Connects but no input CVE-2023-45866 fix: set ClassicBondedOnly=false in /etc/bluetooth/input.conf
Wrong modifier keys Set physical switch to Windows/Android mode, and/or use swap_opt_cmd
hid-apple module not loading Check `lsmod
Battery percentage not showing Set Experimental = true in /etc/bluetooth/main.conf and restart bluetooth

en-GB Keymap Quirks

When using the en-GB keymap, some characters useful for programming are hard to find.

The \ | refers to the key above Enter on the K6.

# = "\ |"
\ = AltGr + "\ |"
~ = Shift + "\ |"

The | character has not been reliably located on this layout.

Resources