4. Customizing Keyboard Layout for Linux with QMK (Version 2022-01-10)

4.1 Instructions

$ Text after the $ sign refers to what is typed into the terminal.

Text in block quotes refers to the terminal output.

For reference, see the QMK documentation.

4.2 Install the QMK CLI tool if you have not used it before

$ python3 -m pip install --user qmk
$ qmk setup

4.3 Test that the QMK CLI tool works by compiling a keymapping. Here I use the clueboard/66/rev3 keymap

$ qmk compile -kb clueboard/66/rev3 -km default

You should see a message similar to below:

Linking: .build/clueboard_66_rev3_default.elf [OK]

Creating load file for flashing: .build/clueboard_66_rev3_default.hex [OK]

Copying clueboard_66_rev3_default.hex to qmk_firmware folder > [OK]

Checking file size of clueboard_66_rev3_default.hex [OK]

* The firmware size is fine - 26356/28672 (2316 bytes free)

4.4 Create a custom keymap

$ qmk new-keymap -kb handwired/dactyl_manuform/5x6

You'll then be prompted to give a name to the keymap. Here I give it the name keyboard_alpaca.

4.5 Edit the keymap.c file with your preferred editor.

$ nano ~/qmk_firmware/keyboards/handwired/dactyl_manuform/5x6/keymaps/keyboard_alpaca/keymap.c

While editing your keymap.c, you may wish to look at the following:

Layers - What are they?

Keyboards flashed with QMK are able use layers, which is a QMK specific functionality.

Layers are similar to a Fn or FnLock key that is seen on some keyboards. For reference, see the Switching and Toggling Layers on the QMK website.

Layer keys are what you press on your keyboard to switch to a different layer. The RAISE and LOWER keycodes raises and lowers the layer, similar to Fn or Shift on a regular keyboard.

If you have been following along, look in your current keymap.c file. As an example of how layere keys work, here you must hold "RAISE" and press "P" to get "Scroll Lock" on layer the upper layer. The lower layer works the same way.

A more useful layer key is the DF(layer) key. The DF stands for Default. It is similar to a FnLock key seen on some keyboards. Tapping this key changes your keymapping to the new layer until you decide to switch to a different layer by pressing another DF key.

[QWERTY] = LAYOUT5x6() refers to the default base layer.

Keycodes - What are they?

Keycodes are functions that start with KC_.

For example, say we want it so that when we press the top left button of our keyboard, it produces an = equal sign.

If we look at our current keymap.c, we will see that the keycode furthest to the top left is KC_ESC (assuming you have been following along this section). We want to replace KC_ESC with the keymap for =, so we go to the QMK List of Keycodes to check.

A quick Ctrl+F for = brings us to the following.

Now we know to replace KC_ESC with KC_EQUAL, or its alias KC_EQL. After we flash the firmware in section 4.6 with our new keymap.c, the keyswitch to the top left of our keyboard will output = .

Save your keymap.c after you are finished editing.

4.6 Flash the firmware

Before you flash the firmware, ensure you have:

• Disconnect the RJ9 cord from each piece of the keyboard

• Connected one piece of the keyboard to your computer via USB cord

Then flash the firmware:

$ qmk flash -kb handwired/dactyl_manuform/5x6 -km keyboard_alpaca

You should see:

Detecting USB port, reset your controller now...

When you see "Detecting USB port, reset your controller now..." in the terminal, click the keyboard reset button twice, as seen in Figure 4.2.

Figure 4.2. Reset button. New versions of the keyboard look slightly different but the button is at the same location.

If it flashes correctly, you should see this message:

avrdude: 18874 bytes of flash verified

avrdude: safemode: Fuses OK (E:CB, H:D8, L:FF)

avrdude done. Thank you.

4.7 Repeat section 4.6 with the other piece of the keyboard

4.8 Before using the keyboard

Make sure no keyboard is connected to your computer before attaching the RJ9 cord to each piece of the keyboard. Afterwards, your keyboard is ready to go. Simply connect the USB cord from your computer to the left keyboard.