# Computer # Keycron Keyboards # Keychron Mechanical Keyboards Reference Guide This guide details operating modes, Bluetooth pairing, RGB/LED light controls, default hotkeys, QMK/VIA customization, and Sway WM configuration for **Keychron Mechanical Keyboards** (K Series, Q Series, V Series, Pro Series). --- ## 1. Bluetooth Pairing & Switch Control ### Toggle Switches (Side / Rear Panel) * **Mode Switch:** * **BT:** Bluetooth wireless mode. * **OFF:** Turns off battery power (wired USB connection still works). * **Cable:** USB Type-C wired mode (disables Bluetooth radio). * **OS Switch:** * **Mac/iOS:** Maps Option to `Alt` and Command to `Win`. Uses **Layers 0 & 1** in QMK/VIA. * **Win/Android:** Standard Windows/Linux layout. Uses **Layers 2 & 3** in QMK/VIA. ### Bluetooth Device Pairing & Switching Keychron keyboards support up to 3 host devices: * **Pairing Mode:** Hold **`Fn + 1`**, **`Fn + 2`**, or **`Fn + 3`** for **4 seconds** until the number key LED flashes rapidly. Select *Keychron K/Q Keyboard* in your host's Bluetooth menu. * **Switching Devices:** Short-press **`Fn + 1`**, **`Fn + 2`**, or **`Fn + 3`** to switch between paired hosts (takes ~1–2 seconds to re-connect). * **Auto-Sleep / Power Saving:** * Disable Auto-Sleep: Hold **`Fn + S + O`** for **4 seconds** (LED flashes to confirm). * Re-enable Auto-Sleep: Hold **`Fn + S + O`** for **4 seconds**. --- ## 2. LED Light & Backlight Controls Keychron keyboards feature dedicated hardware keys and `Fn` shortcuts to control RGB/White backlighting: ### Basic Backlight Controls * **Toggle Light On/Off:** Press the **Light Effect Key** (top-right bulb icon key) or **`Fn + Light Key`** (or **`Fn + Tab`** on select models). * **Change Light Effect Pattern:** Press **`Fn + Q`** or short-press the **Light Effect Key** to cycle through 18+ RGB animation modes. * **Change Backlight Color:** Press **`Fn + E`** or **`Fn + Right Arrow`** / **`Fn + Left Arrow`** to cycle through static colors. ### Brightness & Speed Adjustments * **Increase Brightness:** **`Fn + W`** or **`Fn + Up Arrow`** (or **`Fn + F6`** in Windows mode). * **Decrease Brightness:** **`Fn + S`** or **`Fn + Down Arrow`** (or **`Fn + F5`** in Windows mode). * **Increase Effect Animation Speed:** **`Fn + =`** (Plus key) or **`Fn + D`**. * **Decrease Effect Animation Speed:** **`Fn + -`** (Minus key) or **`Fn + A`**. --- ## 3. Core Hotkeys & Functional Shortcuts ### Multimedia & Function Keys (`F1` – `F12`) * **Mac Mode (Default):** Top row defaults to media functions (Brightness, Mission Control, Media Play/Pause, Volume). Press **`Fn + F1..F12`** for standard `F` keys. * **Windows Mode:** Top row defaults to standard `F1..F12` keys. Press **`Fn + F1..F12`** for multimedia controls. * **Toggle Function Key Mode:** Hold **`Fn + K + C`** for **4 seconds** to swap top-row default behavior between Media keys and `F1..F12`. ### System Shortcuts & Troubleshooting * **Factory Reset:** Hold **`Fn + J + Z`** for **4 seconds** until the backlight flashes 3 times. * **Battery Level Indicator:** Press **`Fn + B`**. The backlight green/red bar indicates remaining battery percentage. * **Windows Key Lock:** Press **`Fn + Win`** to disable the Windows Start key during gaming. --- ## 4. QMK / VIA Customization Keychron Q Series, V Series, and Pro Series models support real-time remapping via **VIA**: 1. **Access Configurator:** Open **[usevia.app](https://usevia.app)** or [caniusevia.com](https://caniusevia.com) in a WebHID-compatible browser (Chrome/Edge/Brave). 2. **Layer Mapping:** * **Layer 0:** Mac Base (Default Mac keys) * **Layer 1:** Mac Fn (Mac shortcuts & media keys) * **Layer 2:** Windows Base (Default Win/Linux keys) * **Layer 3:** Windows Fn (Windows shortcuts & lighting) 3. **Important Note for Windows/Linux Users:** When the physical switch is set to **Win/Android**, VIA edits must be made on **Layer 2** and **Layer 3** for changes to take effect. 4. **Linux Udev Permissions:** To allow Chrome/Chromium WebHID access to `/dev/hidraw*`, create `/etc/udev/rules.d/50-keychron.rules`: ```text KERNEL=="hidraw*", ATTRS{idVendor}=="3434", MODE="0666", TAG+="uaccess" ``` Reload udev rules: ```bash sudo udevadm control --reload-rules && sudo udevadm trigger ``` --- ## 5. Sway WM / Linux (Arch & Debian) Configuration This section covers setting up Keychron keyboards, function keys (`F1`–`F12`), rotary knobs, and custom buttons under the **Sway** window manager on **Arch Linux** and **Debian / Ubuntu**. ### 5.1 Required Package Installation Install the recommended utilities for audio, brightness, media control, screenshots, and event debugging: **Arch Linux:** ```bash sudo pacman -S --needed \ wireplumber \ pipewire-audio \ brightnessctl \ playerctl \ grim \ slurp \ wl-clipboard \ wev ``` **Debian / Ubuntu:** ```bash sudo apt update && sudo apt install -y \ wireplumber \ pipewire-audio-client-libraries \ brightnessctl \ playerctl \ grim \ slurp \ wl-clipboard \ wev ``` ### 5.2 Kernel Apple/Keychron Driver Options (`hid_apple`) If top-row function keys trigger media keys instead of standard `F1`–`F12` (or vice-versa), configure the `hid_apple` kernel module: Create or edit `/etc/modprobe.d/hid_apple.conf`: ```text options hid_apple fnmode=2 ``` * `fnmode=2`: Top row defaults to standard `F1`–`F12` keys. Hold `Fn` for media functions. * `fnmode=1`: Top row defaults to media functions. Hold `Fn` for standard `F1`–`F12`. Regenerate initramfs and reboot: * **Arch Linux:** ```bash sudo mkinitcpio -P ``` * **Debian / Ubuntu:** ```bash sudo update-initramfs -u ``` ### 5.3 Debugging Key Signals (`wev`) To identify keycodes emitted by the rotary knob or custom PlayStation/macro buttons under Wayland/Sway: ```bash wev ``` Press or turn the control while focusing the `wev` window. Note the reported XKB keysym name (e.g. `XF86AudioRaiseVolume`, `XF86AudioPlay`) or numeric keycode. ### 5.4 Modular Sway Configuration (`include`) Sway natively supports the `include` directive to organize keybindings into dedicated configuration files. Add the `include` directive in `~/.config/sway/config`: ```sway include config.d/* ``` Create `~/.config/sway/config.d/keychron.conf` and populate it with your keyboard bindings: ```sway # ============================================================================== # Keychron Keyboard & Function Key Bindings for Sway # Location: ~/.config/sway/config.d/keychron.conf # ============================================================================== # --- Volume & Rotary Knob Controls --- # Knob Clockwise: Volume Up bindsym XF86AudioRaiseVolume exec wpctl set-volume @DEFAULT_AUDIO_SINK@ 5%+ # Knob Counter-Clockwise: Volume Down bindsym XF86AudioLowerVolume exec wpctl set-volume @DEFAULT_AUDIO_SINK@ 5%- # Knob Click: Mute Audio bindsym XF86AudioMute exec wpctl set-mute @DEFAULT_AUDIO_SINK@ toggle # Microphone Mute (if mapped) bindsym XF86AudioMicMute exec wpctl set-mute @DEFAULT_AUDIO_SOURCE@ toggle # --- Media Playback Controls --- # Play / Pause Toggle bindsym XF86AudioPlay exec playerctl play-pause bindsym XF86AudioPause exec playerctl pause # Next Track bindsym XF86AudioNext exec playerctl next # Previous Track bindsym XF86AudioPrev exec playerctl previous # Stop Playback bindsym XF86AudioStop exec playerctl stop # --- Display & Keyboard Backlight Brightness --- # Screen Brightness Up / Down (F1 / F2 or dedicated keys) bindsym XF86MonBrightnessUp exec brightnessctl set +5% bindsym XF86MonBrightnessDown exec brightnessctl set 5%- # Keyboard LED Backlight (Hardware controlled or software via brightnessctl) bindsym XF86KbdBrightnessUp exec brightnessctl --device='*kbd*' set +10% bindsym XF86KbdBrightnessDown exec brightnessctl --device='*kbd*' set 10%- # --- Screenshots & Special Function Keys --- # Screenshot Key / Keychron Camera Key bindsym Print exec grim -g "$(slurp)" - | wl-copy bindsym XF86SelectiveScreenshot exec grim -g "$(slurp)" - | wl-copy # App Launchers / Search / Calculator Keys bindsym XF86Calculator exec foot -e python3 bindsym XF86Search exec rofi -show drun bindsym XF86Launch1 exec rofi -show drun # --- Custom Knob & PlayStation / Macro Buttons (Remapped via VIA) --- # If remapped in VIA to send unused function keys (F13 - F24): # Example: Rotary Knob mapped to Screen Brightness (F13/F14) bindsym F13 exec brightnessctl set 5%- bindsym F14 exec brightnessctl set +5% # Example: PlayStation / Novelty Macro Buttons (F15 - F18) bindsym F15 exec foot bindsym F16 exec rofi -show drun bindsym F17 exec swaymsg workspace 1 bindsym F18 exec swaymsg workspace 2 ``` ### 5.5 Modifier Combinations with the Rotary Knob You can bind modifier keys (`Ctrl`, `Alt`/`Mod1`, `Shift`, `Super`/`Mod4`) combined with knob rotation or press in `~/.config/sway/config.d/keychron.conf`: ```sway # --- Unmodified Knob Turn: Volume --- bindsym XF86AudioRaiseVolume exec wpctl set-volume @DEFAULT_AUDIO_SINK@ 5%+ bindsym XF86AudioLowerVolume exec wpctl set-volume @DEFAULT_AUDIO_SINK@ 5%- bindsym XF86AudioMute exec wpctl set-mute @DEFAULT_AUDIO_SINK@ toggle # --- Alt + Knob Turn: Screen Brightness --- bindsym Mod1+XF86AudioRaiseVolume exec brightnessctl set +5% bindsym Mod1+XF86AudioLowerVolume exec brightnessctl set 5%- # --- Ctrl + Knob Turn: Track Prev / Next --- bindsym Control+XF86AudioRaiseVolume exec playerctl next bindsym Control+XF86AudioLowerVolume exec playerctl previous bindsym Control+XF86AudioMute exec playerctl play-pause # --- Shift + Knob Turn: Switch Sway Workspaces --- bindsym Shift+XF86AudioRaiseVolume exec swaymsg workspace next bindsym Shift+XF86AudioLowerVolume exec swaymsg workspace prev ``` Reload Sway config after editing: ```bash swaymsg reload ``` ## Keyboards Home Office: Keychron Q6 Pro 2026-08-07 / Gateron Banana [![grey.jpg](https://wiki.drheck.dev/uploads/images/gallery/2026-09/scaled-1680-/grey.jpg)](https://wiki.drheck.dev/uploads/images/gallery/2026-09/grey.jpg) Personal Desktop: Keychron Q6 QMK 2023-11-07 / Gateron G Pro Brown [![desktop.jpg](https://wiki.drheck.dev/uploads/images/gallery/2026-09/scaled-1680-/desktop.jpg)](https://wiki.drheck.dev/uploads/images/gallery/2026-09/desktop.jpg) Studio: Keychron Q6 Pro 2023-11-07 / K Pro Banana [![studio.jpg](https://wiki.drheck.dev/uploads/images/gallery/2026-09/scaled-1680-/studio.jpg)](https://wiki.drheck.dev/uploads/images/gallery/2026-09/studio.jpg) Portable: Keychron C1 87 Key TKL Wired 2025-03-20 / Gateron Brown Work Office: Keychron Q6 QMK 2024-09-06 / Gateron G Pro Brown # arch notes ### install arch-chroot base linux linux-firmware neovim tmux gdm3 sway grub networkmanager git sudo base-devel wl-clipboard amd-ucode intel-ucode iwctl station wlan0 connect arikui.org grub-install --target=x86_64-efi --efi-directory=/boot/efi --bootloader-id=GRUB mkdir -p /boot/grub && grub-mkconfig -o /boot/grub/grub.cfg ### nvidia enable multilib in /etc/pacman.conf sudo pacman -S --needed \ intel-media-driver libva-intel-driver mesa \ nvidia-open nvidia-utils lib32-nvidia-utils \ egl-wayland nvidia-prime mesa-utils edit /etc/modprobe.d/nvidia.conf ``` options nvidia-drm modeset=1 fbdev=1 ``` Edit /etc/mkinitcpio.conf ``` MODULES=(intel_agp i915 nvidia nvidia_modeset nvidia_uvm nvidia_drm) ``` mkinitcpio -P add env vars: ``` mkdir -p ~/.config/environment.d ``` get intel card id ``` $ echo /dev/dri/by-path/"$(ls -1 /dev/dri/by-path/ | grep 00:02.0-card)" /dev/dri/by-path/pci-0000:00:02.0-card ``` edit ~/.config/environment.d/sway.conf use that id as WLR_DRM_DEVICES ``` # Force wlroots to render Sway on the Intel GPU WLR_DRM_DEVICES=/dev/dri/by-path/pci-0000:00:02.0-card # Prevent invisible mouse cursor glitches on NVIDIA Wayland sessions WLR_NO_HARDWARE_CURSORS=1 # Enable Wayland support in EGL/Vulkan apps XDG_SESSION_TYPE=wayland GBM_BACKEND=nvidia-drm __GLX_VENDOR_LIBRARY_NAME=nvidia ``` verify ``` $ glxinfo | grep "OpenGL vendor" OpenGL vendor string: Intel $ prime-run glxinfo | grep "OpenGL vendor" OpenGL vendor string: NVIDIA Corporation ``` fix sway bitching ``` sudo mkdir -p /usr/local/share/wayland-sessions sudo cp /usr/share/wayland-sessions/sway.desktop /usr/local/share/wayland-sessions/ ``` edit /usr/local/share/wayland-sessions/sway.desktop ``` [Desktop Entry] Name=Sway Comment=An i3-compatible Wayland compositor Exec=sway --unsupported-gpu Type=Application DesktopNames=sway ``` run anything "nvidia" with prime-run ### looking for binaries: ``` Sat Sep 19 22:25:21 kikuo.drheck.dev:~ $ sudo pacman -Fy :: Synchronizing package databases... core 1494.0 KiB 2.69 MiB/s 00:01 [###################################] 100% extra 48.6 MiB 11.6 MiB/s 00:04 [###################################] 100% multilib 105.5 KiB 831 KiB/s 00:00 [###################################] 100% Sat Sep 19 22:25:57 kikuo.drheck.dev:~ $ pacman -F wl-copy extra/wl-clipboard 1:2.3.0-1 usr/bin/wl-copy usr/share/bash-completion/completions/wl-copy ``` # Steam Streaming This guide covers how to stream games from the headless server gaming stack to any thin client, laptop, mobile device, or TV. The host runs **Sunshine** on top of **Steam-Headless**, accelerated by the server's **AMD Radeon AI PRO R9700** (hardware-accelerated AV1, HEVC, and H.264 video encoding via VA-API). Clients connect using the open-source **Moonlight** GameStream client. --- ## Server & Connection Details * **Hostname**: `sunshine.drheck.dev` * **Internal IPv4**: `10.0.0.112` * **Internal IPv6**: `[fd77:7777:5010:0:1337:f1ac:d00d:4799]` * **Public IPv6**: `[2603:3001:626:9d40:1337:f1ac:d00d:4799]` * **Sunshine Admin Web Portal**: `https://sunshine.drheck.dev` (Authentik SSO protected, restricted to `akadmin`) * **Headless Desktop Web Viewer (noVNC)**: `http://10.0.0.112:8083` (LAN access for initial Steam GUI login and 2FA) --- ## Universal Pairing Process Every Moonlight client connects via mutual TLS certificates authenticated once with a 4-digit PIN: 1. Launch **Moonlight** on your client device. 2. Click the **+ (Add Host)** button (or select `sunshine` if discovered via mDNS). 3. Enter `sunshine.drheck.dev` (or the internal IP `10.0.0.112` if on local LAN). 4. Moonlight will display a random **4-digit PIN** (e.g. `4821`). 5. Open a browser to **`https://sunshine.drheck.dev/pin`** and log in with your `akadmin` Authentik account. 6. Enter the 4-digit PIN and give your client a friendly name. 7. Click **Send**. The lock icon on Moonlight will turn into a green checkmark, showing your available applications (`Desktop`, `Steam Big Picture`). --- ## Client Setup Instructions ### 1. Arch Linux (Desktop / Laptop / Handheld) #### Installation Moonlight is available in the official Arch repositories: ```bash sudo pacman -S moonlight-qt ``` *(Optional gamepad support packages)*: ```bash # For Xbox Wireless controllers over Bluetooth sudo pacman -S xpadneo-dkms # For PlayStation DualSense / DualShock controllers sudo pacman -S linux-firmware ``` #### Configuration & Tuning 1. Open **Moonlight Settings (Gear Icon)**: * **Resolution**: Match your monitor natively (e.g., `1920x1080`, `2560x1440`, or `3840x2160`). * **Frame Rate**: Set to `60 FPS` or `120 FPS` depending on your screen refresh rate. * **Video Bitrate**: * 1080p60: 20–30 Mbps * 1440p60/120: 40–60 Mbps * 4K60/120: 60–80 Mbps * **Video Codec**: Choose **Automatic** or force **HEVC / AV1** (the R9700 encodes AV1 and HEVC with ultra-low latency). * **Hardware Acceleration**: Set to `VA-API` or `VDPAU` depending on your client GPU. --- ### 2. Android (Phones & Tablets) #### Installation * Install **Moonlight Game Streaming** from the [Google Play Store](https://play.google.com/store/apps/details?id=com.limelight) or [F-Droid](https://f-droid.org/). #### Controller Support * Connect any Bluetooth gamepad (Xbox Wireless, PS5 DualSense, 8BitDo, Razer Kishi, Backbone One). Android natively maps standard HID gamepads. * On-screen virtual touchscreen controls are available if no gamepad is connected. #### Configuration & Tuning 1. Open **Settings** in Moonlight: * **Display Resolution**: Select **Native resolution** or `1080p`. * **Framerate**: Match your phone screen (`60 FPS`, `90 FPS`, or `120 FPS` for high-refresh AMOLED panels). * **Video Decoder**: Set to **Hardware decoding** and enable **Prefer HEVC/H.265**. * **Stretch to fit**: Enable if your phone has a 19.5:9 or 20:9 ultrawide aspect ratio and you want to eliminate black bars (or leave unchecked for pixel-perfect 16:9). * **Touch Mode**: Select **Trackpad Mode** for desktop navigation or **Touchscreen Mode** for direct tap interactions. --- ### 3. iPad / iOS #### Installation * Download **Moonlight Game Streaming** from the [Apple App Store](https://apps.apple.com/app/moonlight-game-streaming/id1000551566). #### Controller Support * Connect any MFi, PlayStation (DualShock 4 / DualSense), or Xbox Series/One controller via **Settings > Bluetooth**. * Full L3/R3 clickable thumbsticks and analog triggers are supported natively by iOS. #### iPad-Specific Tuning 1. Open Moonlight on the iPad and tap **Settings**: * **Resolution**: iPads have a 4:3 / 3:2 aspect ratio. You can pick: * `1920x1080` or `2560x1440` (standard 16:9 with letterboxing). * **Custom Resolution**: Enter your iPad's exact panel resolution (e.g. `2048x1536` or `2388x1668`) for a full-screen, edge-to-edge experience without black bars. * **Frame Rate**: If using an iPad Pro with ProMotion, select **120 FPS**. * **HDR**: If using an iPad Pro with an XDR Liquid Retina display, enable **HDR** in Moonlight settings for 10-bit color. * **Mouse & Keyboard**: iPadOS supports Bluetooth mice and magic keyboards. Enable **Optimize mouse for remote desktop** in settings for zero mouse acceleration. --- ### 4. Google TV / Android TV (Chromecast, Shield TV, Smart TVs) #### Installation * Open the **Google Play Store** on your Google TV / Android TV interface. * Search for `Moonlight Game Streaming` and click **Install**. #### Controller Support * Pair an Xbox or PlayStation controller directly to Google TV via **Settings > Remotes & Accessories > Pair accessory**. * USB gamepads and 2.4GHz wireless dongles plugged into TV USB ports work out of the box. #### TV-Specific Optimizations 1. Open Moonlight on your TV and open **Settings**: * **Resolution**: Select `1080p` (for Chromecast 4K or 1080p dongles) or `4K` (for NVIDIA Shield or high-performance TV SoCs). * **Frame Rate**: Set to `60 FPS`. * **Frame Pacing**: Set to **Prefer smoothest video**. This reduces micro-stutters caused by TV display buffer mismatches. * **Audio Configuration**: * Set to **Stereo** for TV speakers or soundbars. * Set to **5.1 Surround Sound** if your TV connects to an AV receiver or multi-channel eARC sound system. * **Network**: For optimal results with 4K streaming on TVs, use a 5GHz Wi-Fi band or an Ethernet adapter. --- ## Available Applications | App Entry | Description | Ideal For | | :--- | :--- | :--- | | **Steam Big Picture** | Launches Steam directly in controller-friendly Big Picture UI | Gaming with Xbox / PS gamepads on TV or handheld | | **Desktop** | Opens full Xfce Linux desktop on virtual display `:55` | Keyboard & mouse games, emulators, web apps | *To add custom games, scripts, or emulators, navigate to `https://sunshine.drheck.dev/apps` and click `+ Add`.* --- ## Essential Navigation Shortcuts | Action | Keyboard Shortcut | Gamepad Shortcut | | :--- | :--- | :--- | | **Quit Stream** | `Ctrl + Alt + Shift + Q` | Hold `Start + Select + L1 + R1` for 3 seconds | | **Toggle Fullscreen** | `Ctrl + Alt + Shift + F11` | — | | **Capture / Release Mouse** | `Ctrl + Alt + Shift + Z` | — | | **Show Stream Stats (FPS, Ping, Loss)** | `Ctrl + Alt + Shift + S` | — | | **Send Ctrl+Alt+Del** | `Ctrl + Alt + Shift + D` | — |