Information
vial-qmk
provides several examples of most common microcontroller configurations set up for Vial usage. You can check them out atvial-qmk/keyboards/vial_example
.
Porting to Vial
The second part of this tutorial will guide you through porting your keyboard to Vial.
1. Clone the Vial QMK fork
Vial is currently not included into the main QMK repository. As such, you will need to check out Vial’s QMK fork vial-kb/vial-qmk
and port your keyboard there before getting started with the rest of this tutorial.
High level guide:
- Clone the latest version of the repository from https://github.com/vial-kb/vial-qmk into a new directory; this can be different from your main QMK directory if you have that setup elsewhere. If you get stuck, please refer to the main QMK install guide here.
- Run
make git-submodule
in your newvial-qmk
directory to clone the git submodules. - Continue to run
make path/to/your/keyboard:keymap
for Vial builds from this directory. Make sure thedefault
keymap for your keyboard compiles successfully. For example, if your keyboard is located in thekeyboards/xyz/xyz60
folder, to compile it using thedefault
keymap, typemake xyz/xyz60:default
.
2. Create a new vial
keymap
Copy the existing keymaps/default
keymap to keymaps/vial
.
3. Enable Vial in your rules file
Create a new file under [keyboard_name]/keymaps/vial/rules.mk
with the following contents:(example)
VIA_ENABLE = yes
VIAL_ENABLE = yes
4. Move JSON so Vial can find it
Place your keyboard definition JSON (either one made in step 1 of this tutorial or downloaded from the VIA keyboards repository) under [keyboard_name]/keymaps/vial/vial.json
so that Vial build process can find it. (example)
5. Generate and add unique keyboard ID
From the root of vial-qmk, run python3 util/vial_generate_keyboard_uid.py
in order to generate a unique Vial keyboard ID:
python3 util/vial_generate_keyboard_uid.py
#define VIAL_KEYBOARD_UID {0xXX, 0xXX, 0xXX, 0xXX, 0xXX, 0xXX, 0xXX, 0xXX}
Create a new file under [keyboard_name]/keymaps/vial/config.h
and add the following contents to it:
/* SPDX-License-Identifier: GPL-2.0-or-later */
#pragma once
#define VIAL_KEYBOARD_UID {0xXX, 0xXX, 0xXX, 0xXX, 0xXX, 0xXX, 0xXX, 0xXX}
The last line should match what you got in the previous step. (example)
6. Set up a secure unlock combination
Vial needs a key combination in order to protect the user from a malicious host computer unknowingly changing security-sensitive settings, such as flashing a malicious firmware; for more information see here.
If you do not want to utilize this feature, you should set VIAL_INSECURE = yes
in your keymaps/vial/rules.mk
. While you can distribute the resulting firmware to your users and will not lose any Vial functionality, note that keyboards which enable VIAL_INSECURE
will not be accepted to the main vial-qmk
repository.
For keyboards that do not define VIAL_INSECURE
, proceed to configure VIAL_UNLOCK_COMBO_ROWS
and VIAL_UNLOCK_COMBO_COLS
definitions:
- You should configure a combo of at least 2 keys
- Suppose this is your KLE and you want to configure a combo of Escape+Enter:
- The Escape key is located at [0, 0] and the Enter key is at [2, 13]
- So you should set in your
keymaps/vial/config.h
right below theVIAL_KEYBOARD_UID
line (example):#define VIAL_UNLOCK_COMBO_ROWS { 0, 2 }
#define VIAL_UNLOCK_COMBO_COLS { 0, 13 }
- Note that this feature works with multi-layout keyboards, however you should make sure that the keys you pick appear in every possible layout:
After you flash the firmware, check that the function works correctly by activating the “Security->Unlock” menu.
7. Compile Vial firmware
Compiling and flashing can be done in the same way as QMK. For example, to compile a vial
keymap for a keyboard located under keyboards/xyz/xyz60
, run make xyz/xyz60:vial
from the root vial-qmk
directory. If at this point you’re having issues making the firmware fit (running out of flash, RAM or EEPROM), see this guide for how to reduce Vial firmware size.
Done!
You now should be able to compile the firmware, flash it, and have your keyboard auto-detected by Vial.
Did you run into a problem? You can get porting support by joining Vial discord.