4. Customizing Keyboard Layout for Linux with QMK (Version 2021-11-29)

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 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

Keyboards flashed with QMK are able use layers, which is a QMK specific functionality. The concept is 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.

A layer key is what you press on your keyboard to switch to a different layer. The RAISE and LOWER keycodes raises and lowers the layer, similar to a Fn or Shift key on a regular keyboard. For example in the keymap, 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. Tapping this key changes your keymapping to the new layer until you decide to switch to a different layer by pressing another DF key. This is similar to the FnLock key seen on some keyboards.

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

See Figure 4.1 below as reference for what key to use, or the table linked here. As per QMK, North America primarily uses ANSI, Europe and Africa primarily use ISO, and Japan uses JIS.

Figure 4.1. Basic keycodes

4.6 Flash the firmware.

Unplug your keyboard from your computer. Disconnect the RJ9 cord from each piece of the keyboard. Connect one piece of the keyboard to your computer via USB.

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

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

Figure 4.2. Reset button

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 Make sure no keyboard is connected to your computer before attaching the RJ9 cord to both pieces of the keyboard. Afterwards, your keyboard is ready to go. Simply connect the USB cord from your computer to the left keyboard.