Vial 是一個可以讓你隨時修改 QMK 鍵盤的各種設定的軟體，其中就包含可以即時編輯 Keymap（也就是改鍵位）。如果要自製 QMK 鍵盤的話，加入 Vial 絕對會方便很多。
這篇文章會教你如何爲你自己的 QMK 鍵盤啓用 Vial 功能。
除了 Vial 外，還有一個類似的功能稱爲 Via，雖然功能相近但用法不同，不要搞混了。
建立 vial.json
要啓用 Vial，首先要準備所謂的鍵盤定義檔，這是一個 JSON 檔。
此步驟的官方文件爲：Build support 1 - Create JSON。
鍵盤佈局
到 Keyboard Layout Editor（KLE）完成你鍵盤的 Layout。當然，如果你之前使用 KLE 時有儲存 JSON 檔的話，可以把它重新上傳。
接著，你需要在 KLE 中的各個鍵上標註此鍵的鍵矩陣掃描行列。以 row,column 的格式將其標記在左上，編號由 0 開始。例如 row1-col0 的鍵要標註爲 1,0。
依照鍵矩陣的物理位置編輯 KLE 的各鍵標記
編輯完成後就下載此 KLE 的 JSON 檔。以我的例子，它的內容大概是：
1[
2 [
3 "0,0",
4 "0,1",
5 "0,2",
6 "0,3",
7 "0,4",
8 "0,5",
9 "0,6",
10 "0,7",
11 "0,8",
12 "0,9",
13 "0,10",
14 "0,11"
15 ],
16 [
17 "1,0",
18 "1,1",
19
20 ... ...
21
22 "4,7"
23 ]
24]
建立定義檔
使用以下的樣板格式建立一個新的 JSON 檔，命名爲 vial.json：
1{
2 "name": "Calcite52",
3 "matrix": {
4 "rows": 5,
5 "cols": 12
6 },
7 "layouts": {
8 "keymap":
9 }
10}
其中，keymap 要填入上一步在 KLE 下載的 JSON 檔內容，包含最外圍的方括號。例如：
1{
2 "name": "Calcite52",
3 "matrix": {
4 "rows": 5,
5 "cols": 12
6 },
7 "layouts": {
8 "keymap":
9 [
10 [
11 "0,0",
12 "0,1",
13 "0,2",
14 "0,3",
15 "0,4",
16 "0,5",
17 "0,6",
18 "0,7",
19 "0,8",
20 "0,9",
21 "0,10",
22 "0,11"
23 ],
24 [
25 "1,0",
26 "1,1",
27
28 ... ...
29
30 "4,7"
31 ]
32 ]
33 }
34}
如果你想看看實例，可以參考我的 Calcite52 及 Vial 官方的多重佈局範例。
測試
完成 vial.json 定義檔後可以先驗證，因爲 QMK 的編譯器不會對它的錯誤報錯，因此你需要自行確認。
打開 Vial 軟體，於上方工具列 File > Load dummy JSON 並選擇你的 vial.json，你應該會看到一個與你在 KLE 上一樣的鍵盤 Layout。
載入 vial.json
移植到 Vial
有了 vial.json 檔後就可以進行移植。
此步驟的官方文件爲：Build support 2 - Port to Vial。
下載 Vial QMK
Vial 不使用 QMK 的 repo，他們有自己的 Vial QMK repo，請 git clone 此 repo。不要把它 clone 到 qmk_firmware 資料夾內，請爲它指定另一個獨立的路徑。
1git clone https://github.com/vial-kb/vial-qmk
如果你不太熟悉 git，或想要 GUI 的話，可以用 GitHub Desktop 或 GitKraken。
準備環境
打開你的 QMK 環境（例如 QMK MSYS），用 cd 指令導航到你剛剛下載的 vial-qmk 資料夾下，然後 clone git submoduels。
1~$ cd <PATH>/vial-qmk/
2vial-qmk$ make git-submodule
使用 QMK MSYS 準備環境
完成後可以進行一下簡單的驗證：
1qmk doctor
你可能會看到「The official repository does not seem to be configured as git remote “upstream”」警告訊息，這很正常，因爲這是 Vial QMK，確實不是官方 QMK。
接下來你可以進行一下編譯測試，例如：
1make vial_example/vial_atmega32u4:default
這裡的路徑是 vial-qmk/keyboards/ 底下的路徑，不用前導斜線 /。如果這時有編譯錯誤的話，你可能要先確定你的 QMK 環境及相關工具。
使用 Vial 時建議使用
make而非qmk compile，當然你可能要另外安裝 make。
建立 Keymap
要爲 Vial 建立其專屬的 Keymap。
在 keymaps 資料夾底下新增一個資料夾 vial，複製 keymaps/default 資料夾內的所有內容（應該只會有一個 keymap.c），貼上到剛剛新增的 vial 資料夾底下。
在 keymaps/vial 內新增一個 rules.mk，並增加以下內容：
1VIA_ENABLE = yes
2VIAL_ENABLE = yes
將建立好的定義檔 vial.json 也複製到 keymaps/vial 資料夾內。
生成識別碼
接下來要爲你的鍵盤生成唯一的識別 ID。用 cd 指令回到 vial-qmk 的根目錄並執行：
1python3 util/vial_generate_keyboard_uid.py
它應該會回傳類似這樣的內容：
1#define VIAL_KEYBOARD_UID {0xXX, 0xXX, 0xXX, 0xXX, 0xXX, 0xXX, 0xXX, 0xXX}
在 keymaps/vial 內新增一個 config.h，並增加以下內容：
1/* SPDX-License-Identifier: GPL-2.0-or-later */
2
3#pragma once
4
5#define VIAL_KEYBOARD_UID {0xXX, 0xXX, 0xXX, 0xXX, 0xXX, 0xXX, 0xXX, 0xXX}
VIAL_KEYBOARD_UID 後面的內容要替換成你上面實際執行指令所得到的。
設定安全解鎖組合鍵
Vial 必須要你設定一個安全解鎖組合鍵，以避免惡意軟體寫入你的鍵盤中。詳細請參考 Security。
在 keymaps/vial/config.h 中的 VIAL_KEYBOARD_UID 下方增加：
1#define VIAL_UNLOCK_COMBO_ROWS { 0, 3 }
2#define VIAL_UNLOCK_COMBO_COLS { 0, 11 }
該組合鍵應該至少包含兩個按鍵，通常會用 ESC+Enter 的組合。上面的數字必須改成你按鍵的物理位置（也就是這裡編輯的 row 與 colume）。上面的例子就是指定 row0-col0 與 row3-col11 這兩個鍵。
如果你不想要這個功能，可以在
keymaps/vial/rules.mk中增加一行VIAL_INSECURE = yes。但增加這行的鍵盤不會被允許提交並合併進 vial-qmk 的 repo 中。
設定 row0-col0 與 row3-col11 爲解鎖組合鍵
確認檔案
完成上面的步驟後，你的 keymaps/vial 資料夾底下應該會有這些檔案：
keymap.crules.mkconfig.hvial.json
其中 config.h 大概會有以下的內容：
1/* SPDX-License-Identifier: GPL-2.0-or-later */
2
3#pragma once
4
5#define VIAL_KEYBOARD_UID {0xXX, 0xXX, 0xXX, 0xXX, 0xXX, 0xXX, 0xXX, 0xXX}
6
7#define VIAL_UNLOCK_COMBO_ROWS { 0, 3 }
8#define VIAL_UNLOCK_COMBO_COLS { 0, 11 }
可以參考官方範例
編譯
都完成後就可以進行編譯了。
編譯與燒錄的方式基本上和官方 QMK 一樣，只是要記得 Keymap 要選擇 vial。到 vial-qmk 根目錄，執行 make path/keyboard:vial 指令。例如：
1make zite/calcite52:vial
如果你使用 Pro Micro 或 ATmega32U4 的話，有可能會遇到空間不夠的問題，這時你可以參考此指南降低韌體大小。如果最後無論如何都不夠小的話，可能只能考慮改用其它容量更大的 MCU 了。
完成編譯並燒錄後，就可以鍵鍵盤接上電腦並打開 Vial 軟體了。Vial 可以編輯的各個功能介紹請看 User manual。
相關網站
留言可能不會立即顯示。若過了幾天仍未出現，請 Email 聯繫：）
comments powered by Disqus