Linux running the Keychron Launcher

How to run the official keychron launcher web app under Linux for keyboard configuration and firmware updates.

Overview

There are a few things to consider when trying to use the keychron launcher web app under Linux:

Versions used

These software versions were used to update a Keychron K10 Pro ISO RGB K10P-H3P-DE to firmware V1.1.0. Other (newer) versions and other keyboards probably work, too.

Connect the Launcher Web App

Without correct udev configuration, clicking the Connect button in the web app at https://launcher.keychron.com and choosing the keyboard in the selection dialog results in an error message popup 

⊗ HID Device Connected [K]

showing up for a (very) short time.

The following steps allow the launcher web app to talk to the keyboard for configuration, macro recording etc. The process was mostly taken from [1].

  1. Connect the keyboard via wire

    If the keyboard has a switch to select between wire and wireless mode, set it to wire mode.

  2. Create the first udev rule

    To automatically give sufficient access to the keyboard USB device create a rule like this:
    1. Find the USB device id of the keyboard in the output of the command 
      lsusb
      On my computer it currently looks like this: 
      # lsusb
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 002 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 003 Device 002: ID 1235:8006 Focusrite-Novation Focusrite Scarlett 2i2
Bus 003 Device 003: ID 05e3:0608 Genesys Logic, Inc. Hub
Bus 003 Device 004: ID 050d:065a Belkin Components F8T065BF Mini Bluetooth 4.0 Adapter
Bus 003 Device 005: ID 3434:02a1 Keychron Keychron K10 Pro
Bus 004 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
      The second to last line of the output shows that the USB bus id of my keyboard is 3434:02a1 here. The first part before the colon is called idVendor, the second part is the idProduct. The ids of other keyboards might be different.
    2. Choose the user group that will get permission to access the USB device. If unsure just use the primary group of your linux user. Find that primary group with (as root): 
      id -gn <linux user>
      On my computer, for my default user chb it looks like this: 
      # id -gn chb
chb
      On a lot of unix systems the primary group of any user has the same name as the user itself by default.
    3. Create (as root) the file /etc/udev/rules.d/99-keychron.rules and put the following line into it: 
      KERNEL=="hidraw*", SUBSYSTEM=="hidraw", ATTRS{idVendor}=="XXXX", ATTRS{idProduct}=="YYYY", MODE="0660", GROUP="ZZZZ", TAG+="uaccess", TAG+="udev-acl"
      • Substitute XXXX with the idVendor from lsusb.
      • Substitute YYYY with the idProduct from lsusb.
      • Substitute ZZZZ with the group name from id.
      So, for me the line would look like: 
      KERNEL=="hidraw*", SUBSYSTEM=="hidraw", ATTRS{idVendor}=="3434", ATTRS{idProduct}=="02a1", MODE="0660", GROUP="chb", TAG+="uaccess", TAG+="udev-acl"

  3. Activate the new rule

    Run (as root): 
    udevadm control --reload-rules
udevadm trigger

You should now be able to run a supported browser as the user whose group went into the rule, go to https://launcher.keychron.com and connect to your keyboard via the Connect button (and the following selection dialog). Configuration, macro recording etc. should work.

However, firmware updates still won't start or get stuck, continue to the next section if you want to fix that.

Enable firmware updates

Disclaimer: Botched firmware updates can damage your keyboard!

Use at your own risk! You have been warned!

When putting the keyboard into firmware update mode the USB device id changes to a different one. In order to allow the web app to continue talking to the keyboard a second udev rule is needed that sets the access permissions for this new device.

For transmitting firmware updates the web app calls the tool dfu-util. If it is not installed the firmware update will stay stuck[2].

The following steps enable the launcher web app to talk to the keyboard for firmware updates:

  1. Prepare keyboard(s)

    1. Connect a second keyboard to the computer. The keychron keyboard cannot be used for typing when it is set to firmware update mode.
    2. Put the keychron keyboard in firmware update mode (usually by holding the Esc or ° key while powering the keyboard up. Check the keyboard documentation for the exact procedure).

  2. Add the second udev rule

    1. Use lsusb again to find the new USB device id of the keyboard. On my computer the output now looks like this: 
      # lsusb
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 002 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 003 Device 002: ID 1235:8006 Focusrite-Novation Focusrite Scarlett 2i2
Bus 003 Device 003: ID 05e3:0608 Genesys Logic, Inc. Hub
Bus 003 Device 004: ID 050d:065a Belkin Components F8T065BF Mini Bluetooth 4.0 Adapter
Bus 003 Device 006: ID 0483:df11 STMicroelectronics STM Device in DFU Mode
Bus 004 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
      The bus id of my keyboard in firmware update mode (line STMicroelectronics STM Device in DFU Mode) is 0483:df11 here, so the new idVendor is 0483 and the new idProduct is df11. On other systems the ids might look different.
    2. Append (as root) a second line to the rule file /etc/udev/rules.d/99-keychron.rules: 
      KERNEL=="hidraw*", SUBSYSTEM=="hidraw", ATTRS{idVendor}=="XXXX", ATTRS{idProduct}=="YYYY", MODE="0660", GROUP="ZZZZ", TAG+="uaccess", TAG+="udev-acl"
      • Substitute XXXX with the idVendor of the new device.
      • Substitute YYYY with the idProduct of the new device.
      • Substitute ZZZZ with the group name used for the first udev rule before.
      For my computer the second rule line would look like: 
      KERNEL=="hidraw*", SUBSYSTEM=="hidraw", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="df11", MODE="0660", GROUP="chb", TAG+="uaccess", TAG+="udev-acl"

  3. Activate the new rule

    Run again (as root): 
    udevadm control --reload-rules
udevadm trigger

  4. Ensure dfu-util is installed

    The dfu-util tool is available in the repositories of most distributions (Debian, Ubuntu, Fedora, Gentoo and maybe more). See https://dfu-util.sourceforge.net/.

With those bits and pieces in place the keychron launcher web app should be able to perform a firmware update on a keychron keyboard. Please see one of the firmware update tutorials for your keyboard at Keychron for instructions on how to proceed from here.

To add to the big warning sign from above: Updating firmware is only worth the risk if there is a good reason for it (e.g. an annoying bug that you actually encounter repeatedly gets fixed or a feature is added that you desperately need). It is only tested with one single keyboard, there is no guarantee that it will work with anything else (not from me and certainly not from Keychron)[3].

Good luck and have fun!