Building QMK with custom config options

#Why

QMK has a feature 🔗, where you can make a specific key act as some other key on press, and toggle a layer on hold:

LT(2, KC_ESC) activates layer 2 on hold and sends ESC on press, and this layer has HJKL mapped to arrows and the number row mapped to F1-F12

But by default, it has a delay before the “hold” action is executed, preferring a “tap”, which gets really annoying really fast when typing quickly

QMK provides a couple of solutions to this problem, allowing to modify tap-hold behavior for dual-use keys:

1. Permissive Hold 🔗
2. Hold On Other Key Press 🔗

There are small differences between them, and it’s something you’ll need to find out yourself while using it

Sadly, on most keyboards, you cannot enable any of this stuff without recompiling QMK, so let’s do just that

Alternative title: Removing LT delay from Keychron’s QMK enabled keyboards

#Prerequisites

1. For the sake of my (and your) sanity, I will assume that you have some sort of UNIX-like OS or already configured WSL, not a Windows
2. Knowing really well which keyboard model and revision you have
3. Upstream support in QMK (or an adequate fork)
4. Enough courage to risk bricking your keyboard (I’ll assume that if you own a keyboard with QMK, you’re not really afraid of that possibility)
5. A second keyboard to use while flashing (and in case something wents wrong)
6. A backup of your layout in case you’ll want to go back to the original firmware
7. An original firmware on hand in case something wents wrong (no idea how you’ll flash it with a dysfunctional keyboard, because most keyboards require you to press a key to enter a DFU mode, but better to have it than not)

##Note about commands listings

I will use my own keyboard for all the commands (keychron/q4/ansi/v2) and my own keymap (lynx). You’ll need to replace both with your own values

#Installing QMK

You can build a firmware using QMK’s web configurator, but I highly recommend you to install QMK locally, because it’s easier than uploading/downloading keymap into the configurator, waiting for it to compile on a shared infrastructure and flashing with a separate app

Just follow a guide for installing and testing compilation on the QMK website:

https://docs.qmk.fm/newbs_getting_started 🔗

On Linux, make sure to installudev rules and run sudo udevadm trigger, qmk setup will warn you about them

You can also specify an alternative path where QMK git repo would be cloned. Here’s what I’ve used: qmk setup -H projects/qmk

#Obtaining a layout file

##Converting layout from VIA

First, you’ll need to obtain a json export of your current layout

Navigate to usevia.app 🔗 using a supported browser, connect your keyboard, and export the layout as json (diskette icon)

Convert downloaded file into qmk format:

$ qmk via2json -kb keychron/q4/ansi/v2 -o output_file_name.json your_via_layout_file.json

For me this conversion yielded a bit broken layout, where some macOS layout modifiers were put as CUSTOM(number), so look out for the CUSTOM in a resulting file and replace it manually with proper keys

Open it in your text editor and edit keymap field. By default it will be via2json; change it to something you like

##Using QMK Configurer

Open config.qmk.fm 🔗, select your keyboard, edit the layout to your liking, set a name and download the JSON file

#Importing layout

After obtaining json file with your layout, you’ll need to import it into your local QMK tree:

$ qmk import-keymap your_layout_file.json

You shouldn’t trust the path it gives you, because for keyboards with multiple revisions, it tends to lie and put the keymap one level higher

You can always check where it was imported by running git status in the repo

#Enabling features

Navigate to the folder of your keymap in local qmk repo:

$ cd projects/qmk
$ cd keyboards/keychron/q4/ansi/keymaps/lynx

Here you’ll see a keymap.json file, where we will add your configuration options.

Nowadays QMK supports “data-driven configuration”, which can be used instead of editing C headers. Here 🔗 you can see the full reference

All the fields that can be used in info.json can also be used in keymap.json inside a config key

Let’s enable tapping.hold_on_other_key_press:

{
    "keyboard": "keychron/q4/ansi/v2",
    "keymap": "lynx",
    "layout": "LAYOUT_ansi_61",
    "config": {
        "tapping": {
            "hold_on_other_key_press": true
        }
    },
    "layers": [

Now we can try building our firmware:

$ qmk compile -kb keychron/q4/ansi/v2 -km lynx

#Flashing

The flashing process will depend on a keyboard and method you’ll choose. Consult the manufacturer’s guides on how to enter DFU, and also read this docs page 🔗

I’ll not provide any commands for this step, because you really should thoroughly research it yourself for your specific keyboard

After flashing the keyboard, it would reset any layout customizations back to the one provided by you

#Additional stuff

Here are some optional things you can also do

##Reenabling VIA support

If your keyboard had VIA support, and you would really like to bring it back:

In the folder with your keymap create a rules.mk file with this line:

VIA_ENABLE = yes

And reflash your keyboard. Now you’ll be able to use VIA just like before

##Moving your configs into a QMK userspace

QMK has a feature called “userspace” which allows you to store your modifications in a separate repo

Follow this guide 🔗 to create your own, and then just copy all the created files into it while keeping the folder structure

Here’s my userspace 🔗 with configs for my keyboard

Comments