I recently remapped some keys on my Keychron Q1 with QMK and decided to document the process on Linux. It is fairly easy, but some of the documentation wasn't fully clear to me.

Proceed with caution since this involves overwriting the firmware currently on your keyboard which could potentially cause it to operate improperly afterwards.

Check if your keyboard supports QMK before proceeding. This page has a list of supported keyboards.

You need to have 'qmk' and 'make' installed which should both be available from the package manager on most distros.

Once installed, you should run the following command:

qmk setup

It will download the firmware which will later be flashed onto your keyboard, assuming it isn't already downloaded on your system.

The output of this command may recommend that you make udev rules changes, likely as so:

sudo cp /home/user/qmk_firmware/util/udev/50-qmk.rules /etc/udev/rules.d/

Read the output of the previous command to find out what (if anything) is required from you.

You need to find the identifier for your keyboard, the easiest way (in my opinion) to do this is to browse to the firmware directory that was just created. On my system this is at /home/user/qmk_firmware/ - You should find a keyboards directory which you can look through to find your keyboard.

For instance, at qmk_firmware/keyboards/keychron will be a list of different Keychron branded keyboards. Keep looking through the folders until you find the right one which was, for me, the following:

~/qmk_firmware/keyboards/keychron/q1v2/ansi_encoder

Note that many keyboards will have different variants, in my case my variant is “ansi_encoder” referring to it being an ANSI layout with a rotary encoder (volume adjustment knob) at the top right. If you are not sure if you have ANSI or ISO, take a look at this page: ANSI vs ISO

Once you found the path to your keyboard, run the following:

qmk config user.keyboard=keychron/q1v2/ansi_encoder

Naturally replace the keychron/q1v2/ansi_encoder part above with the relative path to your keyboard.

Once you have selected your keyboard, you can start editing the default keymap to make it your own. Start by running this command to begin making a new keymap:

qmk new-keymap

You will be asked for a name of the keymap. I just used my username for this. Once this runs, you will see some output from the command stating where it just stored the new files, in my case, I could find them here:

~/qmk_firmware/keyboards/keychron/q1v2/ansi_encoder/keymaps/yourkeymapname

Go to this directory, and open keymap.c in the editor of your choice. You should see at least one (maybe more depending on your keyboard type) block(s) that look like this:

LAYOUT_ansi_82(
        KC_ESC,   KC_BRID,  KC_BRIU,  KC_MCTL,  KC_LPAD,  RGB_VAD,  RGB_VAI,  KC_MPRV,  KC_MPLY,  KC_MNXT,  KC_MUTE,  KC_VOLD,    KC_VOLU,  KC_DEL,             KC_MUTE,
        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_PRINT_SCREEN,
        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_END,
        KC_CAPS,  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_HOME,
        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_LOPT,  KC_LCMD,                                KC_SPC,                                 KC_RCMD,  MO(MAC_FN), KC_RCTL,  KC_LEFT,  KC_DOWN,  KC_RGHT),
        

This is the definition of each key on your keyboard. For my keyboard, I had 4 separate layouts in total:

1. Mac basic
2. Mac function
3. Windows basic
4. Windows function

This is because my keyboard has a physical Windows/Mac selector switch, and a function key which modifies what each key does. You can edit each independently, for instance I could have made my changes only get applied when in Windows mode.

To make changes, find the key which you want to replace and overwrite the value in that key position. Some of the key values are obvious, especially when also looking at the position in the table (eg, KC_ESC in the top left is the escape key) but you should reference this page to ensure you use the right values: QMK Keycodes

As an example, if you want to replace your printscreen with a media play/pause key, you would add “KC_MEDIA_PLAY_PAUSE” to overwrite the “KC_PRINT_SCREEN”. Be sure not to add or remove any commas since this will change the entire layout!

Once your changes are made, you should compile them with the following command:

qmk compile --keymap yourkeymapname

Since we are using a CLI tool which relies on a working keyboard, I suggest plugging in a spare keyboard now.

First you need to put your target keyboard into programming mode; how to do this varies by manufacturer and model. For the Keychron Q1v2, you must remove the space bar and hold the “reset” button underneath while plugging in the keyboard. Your keyboard should not be responsive after going into programming mode, but needs to remain connected to your PC.

Using your spare keyboard, run the following command:

qmk flash --keymap yourkeymapname

Assuming you only have a single programmable keyboard connected, QMK should detect the keyboard and begin the flashing process. It is important not to disconnect the keyboard or cancel the command during this.

Immediately after the flashing is complete, your new keyboard map should be working and ready to use. Since this is stored in the keyboard, it will function as expected on any system you connect this keyboard to. Keep that in mind if you ever sell the keyboard or give it away, especially if you don't replace your physical keycaps to represent the new layout.

Since the changes you made were only to a copy of the firmware, you can revert the changes easily. To do so, run the following command to compile the default map:

qmk compile --keymap default

Then this command to flash it:

qmk flash --keymap default

Be sure to remember to put your keyboard into programming mode before attempting to flash it.