Keychron K8 Pro custom firmware on Linux

Official firmware

It is always possible that a custom firmware doesn't work at all. You should always be able to get back to the factory default by re-flashing with the official firmware from Keychron, so we'll just put that link here to be safe.

But obviously we want to do things that aren't in the default, so let's continue, shall we?

Setup

There are a few things we need to do in preparation. Which is basically clone the Keychron fork of QMK, and install the QMK CLI.

git clone https://github.com/Keychron/qmk_firmware.git && cd qmk_firmware

git remote add upstream https://github.com/qmk/qmk_firmware.git

make git-submodules

git switch bluetooth_playground

python3 -m pip install --user qmk

qmk setup

Testing a build

There are two keymaps defined, one called default and one called via. The only difference between them is a rules.mk in the via one that enables via support. So if you use default, via won't work. So with that, lets try to build the via keymap.

qmk compile -km via

If all goes well, you should see something like this

Success

Now we can create a custom keymap. The qmk cli has a qmk new-keymap, which will prompt you for a new keymap name, but you can also specify with -km mynewmap. That will essentially just create a new keymap based on default. Since we wanted to maintain via compatibility, we could just copy the rules.mk from via into our new keymap directory, but since it is just copying anyway, I created a new keymap with:

cp -R keyboards/keychron/k8_pro/ansi/rgb/keymaps/via keyboards/keychron/k8_pro/ansi/rgb/keymaps/mynewmap

At this point you could try to compile your new one (which should be the same as the via one that we tested above) with

qmk compile -km mynewmap

But, we want to actually change something, so let's edit keyboards/keychron/k8_pro/ansi/rgb/keymaps/mynewmap/keymap.c and change "KC_CAPS" in the "WIN_BASE" layer to "LCTL_T(KC_ESC)", which is what gets escape on tap, control on hold for the caps lock key. So the full WIN_BASE layer looks like this now

[WIN_BASE] = LAYOUT_ansi_87(
     KC_ESC,   KC_F1,    KC_F2,    KC_F3,    KC_F4,    KC_F5,    KC_F6,    KC_F7,    KC_F8,    KC_F9,    KC_F10,   KC_F11,   KC_F12,             KC_PSCR,   KC_CTANA, RGB_MOD,
     KC_GRV,   KC_1,     KC_2,     KC_3,     KC_4,     KC_5,     KC_6,     KC_7,     KC_8,     KC_9,     KC_0,     KC_MINS,  KC_EQL,   KC_BSPC,  KC_INS,    KC_HOME,  KC_PGUP,
     KC_TAB,   KC_Q,     KC_W,     KC_E,     KC_R,     KC_T,     KC_Y,     KC_U,     KC_I,     KC_O,     KC_P,     KC_LBRC,  KC_RBRC,  KC_BSLS,  KC_DEL,    KC_END,   KC_PGDN,
     LCTL_T(KC_ESC),  KC_A,     KC_S,     KC_D,     KC_F,     KC_G,     KC_H,     KC_J,     KC_K,     KC_L,     KC_SCLN,  KC_QUOT,            KC_ENT,
     KC_LSFT,            KC_Z,     KC_X,     KC_C,     KC_V,     KC_B,     KC_N,     KC_M,     KC_COMM,  KC_DOT,   KC_SLSH,            KC_RSFT,             KC_UP,
     KC_LCTL,  KC_LGUI,  KC_LALT,                                KC_SPC,                                 KC_RALT,  KC_RGUI, MO(WIN_FN),KC_RCTL,  KC_LEFT,  KC_DOWN,  KC_RGHT),

Now with that change, we are going to compile for real this time:

qmk compile -km mynewmap

Assuming everything is good, we can move on to flashing

Flashing

The previous step should have created a keychron_k8_pro_ansi_rgb_mynewmap.bin file. We are going to flash the keyboard with that file. We are again going to use the qmk CLI to do that. Run:

qmk flash keychron_k8_pro_ansi_rgb_mynewmap.bin

You should see:

Flashing binary firmware...
Please reset your keyboard into bootloader mode now!
Press Ctrl-C to exit.

Ok, so let's do what it tells us. If you follow the instructions on Keychron's site, in order to do this you have to do the following:

1. move the keyboard switch to the 'cable'
2. Pop off the spacebar keycap
3. press and hold the reset button
4. plug in the USB cable
5. release the reset button

This works, and I think the point is that this works no matter what. I don't particularly want to pop off my keycap every time I want to flash a firmware, and it turns out there is a simpler way. The USB cable can already be plugged in for this method (probably could be for the previous one too, but their documentation specifically states to have it unplugged)

1. move the keyboard switch to off
2. plug in the USB cable (if not already connected)
3. hold the escape key (upper left-hand button)
4. move the keyboard switch to cable
5. release the escape key.

The process is basically the same, with the major difference being you don't have to pop off any keycaps to do it.

If all goes well, you should see the qmk flash command begin to wipe the keyboard memory and apply the new firmware. Then we should be ready to go. Except, if you hit your new capslock-thats-supposed-to-be-an-escape, you'll still see caps lock behavior. WTF?

Well it turns out this is a via-compatibility thing. This is specifically covered in the FAQ. The solution is to basically do the thing we did above to put it in bootloader mode:

Hold the Bootmagic Lite key (usually top left/Escape) while plugging the board in, which will also place the board into bootloader mode; then unplug and replug the board.

Since the K8 pro has a physical switch, you can do the same thing with switching it from off->cable instead of the plugging/unplugging.