Keychron WebHID Enabler for Arch Linux

---

---

This repository provides an automated script to enable WebHID support for multiple Keychron keyboards (QMK/VIA/Launcher compatible) on Arch Linux.

By default, Linux restricts user access to raw USB/HID interfaces. Because the Keychron Launcher operates via the browser using the WebHID API, you must explicitly grant it permission to read and write to your keyboards' firmware.

1. Usage

This script scans your USB tree for any device containing the name "Keychron", extracts its unique Vendor ID (VID) and Product ID (PID), generates the necessary udev rules, and then verifies that your user can actually access each keyboard.

1. Ensure all your Keychron keyboards are connected via USB (Cable mode). Keyboards connected through a 2.4G dongle enumerate under the dongle's own IDs and are not detected.
2. Run the script:

./setup_keychron_webhid.sh

3. The script ends with a per-device verification. On Setup complete and verified you are done — no unplug/replug needed.

The script is safe to re-run at any time: rules that are already in place are detected and skipped, and access is re-verified either way. It will also warn you if other udev rule files on your system match the same keyboard, since a later file can silently override the permissions this script sets.

The script additionally installs a static rule (50-keychron-dfu.rules) for firmware-update bootloaders. During a firmware update the keyboard reboots into its microcontroller's bootloader, which shows up under the chip maker's USB IDs (STM32, APM32, WB32, GD32V, AT32 — taken from QMK's canonical udev rules) rather than Keychron's, so it cannot be detected by scanning. The rule matches nothing outside of an active firmware update; without it, an in-browser firmware update can fail with a permission error halfway through.

2. Connect via Keychron Launcher

1. Go to the Keychron Launcher in Chromium.
2. Click Connect.
3. A browser prompt will appear showing your available Keychron devices. Select the one you want to configure and click Connect.

Troubleshooting

• Browser Cannot See Devices: Double-check that you are not using a Flatpak version of Chromium/Brave. Flatpaks isolate the browser from the host's hardware interfaces. Use sudo pacman -S chromium to install the native version.
• Very Old Browser: WebHID has shipped enabled by default in Chromium since v89 (2021). Only if your browser is older than that, enable Experimental Web Platform features in chrome://flags and relaunch.
• "Device In Use" Error: Close any standalone VIA desktop applications, QMK toolboxes, or other browser tabs that might already have an active lock on the keyboard's HID interface.
• No Devices Found by Script: Ensure the physical toggle switch on the back of the keyboards is set to Cable and that you are using data-capable USB cables.
• Script Reports FAIL for a Device: Unplug and replug that keyboard, then re-run the script — it will re-check without rewriting anything.
• Firmware Update Fails Partway: If Launcher's firmware update stalls or shows a permission error after the keyboard reboots into its bootloader, the bootloader's USB IDs are probably not covered by 50-keychron-dfu.rules. Put the keyboard in bootloader mode, run lsusb, and add a rule for the ID that appears.