DEV Community

Cover image for Customize your keyboard's layout using QMK
Lucas Miguel
Lucas Miguel

Posted on

Customize your keyboard's layout using QMK

I had several problems bringing my QMK layout to life on my keyboard. I bought the OLKB Planck from Drop and since I am a native spanish speaker, and some common spanish characters (ñ, ¨, ´) were either missing or really hard to type, (not to mention I found the non-letter keys to be rather impractical) I decided to get into designing my own layout.

Setup QMK

I myself will only do this for Manjaro, but the official tutorial will help you set up your system on your specific OS, so you can still follow along with me after setting QMK on your computer.

As a prerequisite you'll need python and git installed in your system.

Install QMK's Command Line Interface (CLI)

python3 -m pip install --user qmk 
Enter fullscreen mode Exit fullscreen mode

Setup QMK

Run the following command and say yes to all

qmk setup
Enter fullscreen mode Exit fullscreen mode

Create your own keymap

QMK, which you just installed, comes with a lot of layouts for your keyboard made by members of the community that forked QMK's repo at <directory_where_you_installed_qmk>/keyboards/your_keyboard/keymaps/.

You can create your own layout from any of this layouts, but what I recommend is looking for the folder named default, which will contain the layout installed by default in your keyboard, and making a copy inside the same containing folder. You can name it however you want it.

Inside this layout you'll see several files:
image
You should only care about keymap.c if you only want to change the layout. If you in the other hand wish to set special actions like for example "tapping shift two times to activate mayus" you will need to modify config.h and rules.mk. See special actions.

Create your layout

Inside keymap.c, under the configuration part of the code, you should see commented how the final layout should look like and the matching keymap below it:
image

Now is time to include your special characters (if you want any). For your language's specific characters you will want to import them by importing it's language file (see what's your language file) under the muse.h import statement:

...
#include QMK_KEYBOARD_H
#include "muse.h"
#include "keymap_spanish.h" --> /*Your file
Enter fullscreen mode Exit fullscreen mode

NOTE: if there are many layouts to import for your language, make sure the layout you are importing matches your system's keyboard layout (ie: you only have a spanish layout available in QMK that should smath Spain's spanish layout in contrast with Latin America's spanish layout).

Now you should modify your layout accordingly by using the characters found in the keymap_<your_language.h> file. If you can't find them on your computer's file system, here you have the language files, just use the variable names for your language's character (i.e: ES_NTIL --> Ñ) on your layout like this:
image

Declare your special rules

I myself will make my shift key to activate bloq mayus when tapped twice.

Since we will be using "tap dance" special rules, we should enable them in our rules.mk file by inserting the following line at the bottom of the file:

...
TAP_DANCE_ENABLE = yes
Enter fullscreen mode Exit fullscreen mode

In order to set the time between tap and tap (tap = press of a key) we should add the following line at the bottom of the config.h file:

...
#define TAPPING_TERM 200
Enter fullscreen mode Exit fullscreen mode

Now we should declare the double-tap special action like this in above the declaration of the layout (the line that starts with const uint16_t ...):

...
// Tap Dance Declarations
enum {
  TD_LSFT_CAPS,
};
// Tap Dance Definitions
qk_tap_dance_action_t tap_dance_actions[] = {
  // Tap once for shift, twice for Caps Lock
  [TD_LSFT_CAPS] = ACTION_TAP_DANCE_DOUBLE(KC_LSFT, KC_CAPS),
};
...
const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
...

Enter fullscreen mode Exit fullscreen mode

Now that you have your special actions declared, go ahead and include it as a key in your keyboard like this:
image

Install your new keymap settings

After you are finished with your layout and special actions for your keymap, go ahead and put it inside your keyboad.

In the home directory for your qmk installation (in my PC lucas/qmk_firmware) open a terminal and follow this 2 steps:
1- Compile your keymap so it can be installed in your keyboard:

qmk compile -kb <kb_name>/<version> -km <keymap>
Enter fullscreen mode Exit fullscreen mode

Where <kb_name> is your keyboards name, where <version> is your keyboard's version (only in case your keyboard has many versions like my planck). <keymap> stands for the name you gave to your folder containing all your keymap's files.
2- Flash your keyboard: once you have your compiled keymap for your keyboard, you should set your keyboard on flash mode. This depends on our keyboard, but basically just google "flash mode " and that should do it. Once you got your keyboard to enter flash mode, but your keymap inside your keyboard with the following command:

qmk flash -kb <your_keyboard>/<version> -km <keymap>
Enter fullscreen mode Exit fullscreen mode

That's it! Hope this tutorial was helpful.

Top comments (2)

Collapse
 
axelr0d2 profile image
axelr0d

thanks for the tutorial. is it possible to assign an additional character when I hold Alt + N to get it Ñ?

Collapse
 
sherlockcodes profile image
Lucas Miguel

I don't know exactly how. I really don't think is impossible to do so. You might want to check QMK docs for that: docs.qmk.fm/#/.