Customize your keyboard's layout using QMK
Tags: espanol, spanish, qmk, keyboard
Published: 2021-05-18 22:51:18

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](https://docs.qmk.fm/#/newbs) 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)

```terminal
python3 -m pip install --user qmk 
```
## Setup QMK
Run the following command and say yes to all
```
qmk setup
```

## 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](https://github.com/qmk/qmk_firmware) 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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/woetq588fen6922nd4zh.png)
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](https://beta.docs.qmk.fm/using-qmk/software-features/feature_tap_dance).

### 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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/w7241a9tf5be39e34y3l.png)

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](https://beta.docs.qmk.fm/using-qmk/simple-keycodes/reference_keymap_extras)) under the `muse.h` import statement:
```C
...
#include QMK_KEYBOARD_H
#include "muse.h"
#include "keymap_spanish.h" --> /*Your file
```
*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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/8y15nvljh0h29vrprc98.png)

### 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:
```mk
...
TAP_DANCE_ENABLE = yes
```
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
```
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 ...`):
```C
...
// 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] = {
...

```
Now that you have your special actions declared, go ahead and include it as a key in your keyboard  like this:
![image](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/om0vm5a1e57uz23oii8h.png) 
 
# 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>
```
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 <your keyboard name>" 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>
```

That's it! Hope this tutorial was helpful.