How to install Vial firmware on the Keychron Q1 Knob (and other Keychron QMK keyboards)

The Keychron Q and V series of QMK keyboards come with VIA support out of the box. But Vial offers much more customisable options.

Of QMK, VIA and Vial?

QMK stands for “Quantum Mechanical Keyboard” and is in essence, a custom firmware that you can flash on support mechanical keyboards to unlock additional functionality. You can re-program keys, program RGB lighting etc. with a custom QMK firmware. However, such custom functions are ‘hard-coded’ in the firmware itself. You have to make the relevant customisations, compile the firmware and then flash it to your keyboard. If you’ve already programmed a key and want to modify it thereafter, you would need to amend the script, re-compile the firmware and then re-flash it on your keyboard.

To make things easier, there is a software called VIA (probably named after its creator, Olivia), which exposes certain QMK features (such as remapping of keys) through a user interface without needing to re-compile and re-flash firmware each time. To enable VIA support on a QMK firmware, you simply need to compile QMK with an added flag. You will generally also need to make sure that there is an available keyboard definition on the VIA keyboard repository (alternatively, you could supply your own, but you would need to reload the keyboard definitions every time you run the app).

All Keychron Q and V series keyboards come preloaded with VIA firmware out of the box. This means that, with a supported browser (e.g. Google Chrome), you can simply go to the VIA web app to re-program your keyboard. That said, there aren’t many features built into VIA by default, apart from remapping keys, programming simple macros and configuring some RGB lighting settings.

Further, at the time of writing, only the first version of the Keychron Q1, the Keychron Q2 and the Keychron Q0 are officially supported. If your keyboard isn’t supported (e.g. if you have the newer Keychron Q1 with the rotary encoder knob), you will need to load your keymap file every time you wish to re-program your keyboard.

Vial comes in as an alternative to VIA. Vial exposes more QMK features than VIA. For example, you can take advantage of combos, the “tap dance” feature, key overrides and also allows you to enable/ disable certain QMK features on the fly, such as swapping caps lock and left control, etc. It also circumvents the requirement of having to load your keymap file each time you wish to change settings, as the keyboard definition is stored locally within the firmware itself.

Similar to my earlier GMMK Pro QMK/ Vial guide, I’ve therefore written this step-by-step guide, with the objective of making it as easy as possible to someone who knows nothing about programming, and as ‘evergreen’ as possible such that it should hopefully be applicable to the plethora of QMK-compatible keyboards which Keychron has launched, and continues to launch. Note that this guide assumes that you are using Windows.

Prerequisites

To get started, you will first need to set-up/ install the following:

1. A GitHub account — this is recommended for you to pull files from the Vial GitHub repository later on (otherwise, you will have to download the files manually)
2. QMK-MSYS — this provides the command line interface for you to run QMK commands. Alternatively, you can also get started using Windows Subsytem for Linux but using QMK-MSYS is much faster and I will use this for the purpose of this guide.
3. QMK Toolbox — this is the tool that enables you to flash the Vial firmware on to your GMMK Pro.

Step 1: Set up access between QMK-MSYS and GitHub

After setting up and installing the above, the first step is to allow QMK-MSYS to communicate with your GitHub account so that you can download the Vial repository seamlessly.

To do this, run QMK-MSYS. Next, key in the following command, followed by the enter key:

ssh-keygen

You should thereafter receive a prompt as to where you want to save the rsa key paid. Press enter to save in the default location. You should also be asked to enter a passphrase. Key in a password which you can remember.

Next, open the location where the rsa key is saved (by default, it should be at C:\Users\<Username>\.ssh\id_rsa.pub). There should be a long string of text beginning with “ssh-rsa”.

Now, go to your GitHub account, click your profile icon on the upper right hand corner, then click “Settings”. On the next page, click “SSH and GPG keys” from the left sidebar and click the green button which says “New SSH Key”. Copy and paste the entire string of text from the id_rsa.pub earlier, including “ssh-rsa”, and click “Add SSH Key”.

Step 2: Download/ clone the Vial repository

Next, back in the QMK-MSYS application, run the following command, followed by the enter key:

git clone git@github.com:vial-kb/vial-qmk.git

You will then be prompted for your passphrase. The passphrase would be the same as the one you have keyed in during Step 1 earlier.

What this command does is to download, or clone the Vial repository to your hard drive. The default folder in which the repository will be saved should be C:\Users\<Username>\vial-qmk. If you would like to specify another folder, you can simply specify the folder name after the command, like this:

git clone git@github.com:vial-kb/vial-qmk.git C:/path/to/folder

Do note that you will need to use the forward slash instead of backslash.

Step 3: Setting up the QMK build environment

Next, we will setup the QMK build environment, which is the pre-requisite for compiling the Vial firmware. To do this, we first need to enter into the folder where the Vial repository is saved on your hard drive. Assuming you chose the default settings, you can simply type in the following, followed by the enter key:

cd vial-qmk

If you saved the files in another folder, you can simply type something like cd C:/path/to/folder instead.

Then, run the following command:

make git-submodules

This step will download the relevant QMK libraries required for you to compile your Vial firmware. After this is complete, run the following command:

qmk setup

The setup should complete without errors, though there might be a warning that “minor problems were found”. This is not an issue.

Step 4: Clone the “playground” branch of the Keychron repository

Next, clone the developmental, or “playground”, branch on Keychron’s QMK fork, available on GitHub. As the Keychron repository is maintained by Keychron itself, it is the most up-to-date and offers the keymaps to every of its QMK-programmable keyboard.

To clone the branch, simply run in QMK MSYS the following command:

 git clone -b playground git@github.com:keychron/qmk_firmware.git C:/path/to/folder

You would have to specify a different folder from the one in Step 2.

Update (18 Dec 2022): There were some recent changes in the QMK repository (which has been incorporated in Keychron’s playgroud branch) which has not been ported over to Vial yet. As a temporary fix, we will have to use an older commit of the Keychron playground branch; otherwise, there will be a compilation error. To do this, you have to navigate to the folder where you Keychron playground branch is cloned, and then checkout an older version of the playground branch (25efaea which is an early November commit seems to work just fine). See below:

cd C:/path/to/folder
git checkout 25efaea

Once you have cloned the Keychron playground branch, you can open the folder in File Explorer and copy over the entire keyboards/keychron folder from the Keychron playground branch to the same folder in the Vial repository which you cloned earlier. If prompted, choose to replace the relevant files with the one from the Keychron playground branch. What this step does is to copy over all the keymap files provided by Keychron into your cloned Vial repository.

Step 5: Modify some code in your cloned Vial repository

The keymap files provided by Keychron contain some “proprietary” code, particularly in respect of the rotary encoder knob, which will cause some issues when compiling the firmware later without the code. To fix this, there are a few things to do:

First, copy over the encoder.c, encoder.h and util.h files in the quantum folder of the Keychron playground branch to your cloned Vial repository folder. What this step does is to replace the default QMK code for the rotary encoder knob with Keychron’s implementation, which is said to work better on certain Keychron boards.

Next, open util.h in Notepad and add the following lines right after #include “bitwise.h”:

// convert to L string
#define LSTR(s) XLSTR(s)
#define XLSTR(s) L## #s

The reason why we have to add the above lines in is because the Vial repository which you cloned earlier is based on the stable version of the official QMK repository, whereas the Keychron playground branch contains code from the developmental branch of the QMK repository. In the developmental branch, the above lines have been deprecated but the changes have not been implemented in the Vial repository yet. Without these lines, compilation will fail as certain files within the Vial repository rely on the LSTR function.

Step 6: Create your Vial-specific keymap

The Keychron keymaps which you copied earlier are only configured to work with VIA. You would therefore need to create a Vial-specific keymap. A Vial keymap consists of the following:

• a rules file (rules.mk) telling the compiler to enable Vial support
• a config file (config.h) specifying certain Vial parameters
• a keyboard definition file (vial.json) telling the compiler which key corresponds to which hardware switch on the keyboard
• a keymap file (keymap.c) telling the compiler that by default, which command should correspond to which key (e.g., that Fn + F3 runs the calculator by default)

Hence, the next steps will guide you through the “recipe” to create a Vial-specific keymap for your Keychron keyboard. Using the Q1 knob version with ANSI layout as an example:

1. Go to the keymap folder for your specific keyboard variant, e.g. keyboards/keychron/q1/q1_ansi_stm32l432_ec11/keymaps

2. Make a copy of the via folder and rename it vial

3. In the vial folder, open the rules.mk file and replace everything with the following code:

VIA_ENABLE = yes
VIAL_ENABLE = yes
VIALRGB_ENABLE = yes

4. Create a file in Notepad and insert the following lines and save it as config.h in your keymap folder (i.e., in keyboards/keychron/q1/q1_ansi_stm32l432_ec11/keymaps/vial:

/* SPDX-License-Identifier: GPL-2.0-or-later */

#pragma once

#define VIAL_KEYBOARD_UID {0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00}


#define VIAL_UNLOCK_COMBO_ROWS { 0, 2 }
#define VIAL_UNLOCK_COMBO_COLS { 0, 13 }

Back in QMK MSYS, run the following command:

python3 util/vial_generate_keyboard_uid.py

5. Copy the result that is shown in QMK MSYS and replace the line highlighted in bold and italics earlier in config.h. In other words, you will replace #define VIAL_KEYBOARD_UID {0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00} with something like #define VIAL_KEYBOARD_UID {0x01, 0x0A, 0x0B, 0xAA, 0x02, 0x04, 0x11, 0x12}.

Basically, your keyboard needs a unique identifier and running the command earlier would generate a random keyboard unique identifier for you.

6. Download the JSON file for your keyboard on the Keychron website. For the Q series, the files can be downloaded here, and for the V series, you can download it here. Copy it to your vial keymap folder and rename it as vial.json.

7. To allow access over RGB controls in Vial, open vial.json, and replace the lines starting with “lighting” until right before “matrix”, and replace it simply with:

"lighting": "vialrgb",

8. That’s all! You don’t need to modify the keymap.c file unless you wish to modify the default mapping of your keys. For example, coming from the GMMK Pro, I map the Fn+Backslash key to RESET, although this is not really required with Keychron keyboards as you can enter the bootloader either through the button beneath the spacebar, or pressing the Esc key while plugging in the keyboard.

Step 6: Further customisations (optional)

To improve the scanning rate of the keyboard (note: for boards with STM32L432 microcontrollers only, which should be basically all Keychron QMK keyboards except the Q1 version 1), you can head over to the “main” keychron model folder (e.g. keyboards/keychron/q1 in my case) and create a file called “chconf.h” with the following lines:

#pragma once
#define CH_CFG_ST_FREQUENCY 50000
#include_next <chconf.h>

This increases the resolution of the system (the default is 10,000) and thus improves the scan rate.

You can also modify the debounce algorithm, as you can read up from here and the official docs. To do so, you can open the rules.mk file in your Vial keymap folder, and add the line

DEBOUNCE_TYPE = sym_eager_pk

I’ve been using sym_eager_pk but you can try other algorithms as mentioned in the official docs.

You can also amend the debounce time by amending the “config.h” file in the main keymap folder (i.e., keyboards/keychron/q1 in my case). In the same file, you can also add/ remove/ modify certain RGB settings.

Step 7: Compile the Vial firmware

Once done, we can finally proceed to compile the Vial firmware in QMK MSYS. Run the following command (replacing the parts in bold and italics with the path to your keymap):

make keychron/q1/q1_ansi_stm32l432_ec11:vial

What this command does is to compile the QMK firmware using the vial keymap based on your keyboard variant. If you have done everything correctly earlier, you should be able to compile the firmware successfully without any error. Otherwise, try to troubleshoot the error message you see, or retrace the steps above.

Step 8: Flash the firmware

After the end of Step 7, the firmware file should now be residing in the same folder as your cloned Vial repository. Now, you need to run QMK Toolbox, and open the firmware file.

Next, you need to put your keyboard into bootloader mode. To do so, either (i) unplug the keyboard, then hold the Esc key while plugging in the USB cable (this will also clear all saved settings), or (ii) remove the spacebar, unplug the keyboard, then press the tiny button beneath the spacebar while plugging in the keyboard. You should then see a message pop up in the QMK Toolbox that a ST Microelectronics controller has been connected.

Now, just click Flash, and you should be up and running in less than thirty seconds.

You’re done! Now, just run Vial and you should be able to remap keys to your heart’s content through the user interface.