QMK自定義4*4鍵盤固件創建教程：最新架構詳解

前言

通過本教程，你將學習如何在QMK框架下創建自己的鍵盤固件。QMK是一個強大的開源鍵盤固件框架，廣泛用于DIY機械鍵盤的制作。本文將詳細介紹最新架構下所需創建的文件及其功能。

準備工作

在開始之前，我們需要理解QMK架構中必須創建的幾個核心文件：

• info.json：鍵盤的基本信息配置
• config.h：硬件和功能的配置頭文件
• rules.mk：編譯選項和功能開關
• <keyboard_name>.c：鍵盤的主要C源文件
• <keyboard_name>.h：鍵盤矩陣定義的頭文件

接下來，我們將一步步實現這些文件的創建。

實操步驟

1. 創建鍵盤目錄

首先導航到QMK固件的keyboards目錄：

2. 創建自定義鍵盤文件夾

在keyboards目錄下創建一個新的文件夾，使用你自定義的鍵盤名稱（本例中使用"despacito0o"）：

3. 打開IDE并開始編輯

使用VSCode打開剛創建的文件夾（可以直接將文件夾拖到VSCode圖標上）：

4. 創建rules.mk文件

首先創建rules.mk文件，這是編譯選項和功能開關的配置文件：

在rules.mk文件中寫入以下內容：

MCU = STM32F103          # 主控型號，使用的是 STM32F103 微控制器
BOOTLOADER = stm32duino  # 啟動加載器類型，使用 stm32duino 引導程序
NKRO_ENABLE = yes        # 啟用 NKRO (N-Key Rollover)，支持多鍵同時按下
EXTRAKEY_ENABLE = yes    # 啟用額外按鍵功能，例如媒體鍵(用鍵盤控制音量大小等)
# LTO_ENABLE = yes        # 是否啟用鏈接時優化 (Link Time Optimization)，暫時不需要注釋掉

rules.mk文件說明

rules.mk文件是QMK的頂級Makefile，用于設置關于MCU的信息以及啟用/禁用特定功能。主要包含：

• 構建選項：指定默認文件夾、固件格式等
• 功能開關：通過設置yes/no來啟用或禁用功能
• MCU選項：設置微控制器類型、時鐘頻率等
• 編譯優化：如LTO_ENABLE可顯著減少編譯大小

5. 創建鍵盤頭文件

接下來創建鍵盤的.h頭文件（使用你的鍵盤名稱）：

在頭文件中添加以下內容：

#pragma once // 防止頭文件被重復包含#include "quantum.h" // 包含 QMK 的核心頭文件

鍵盤頭文件說明

該頭文件用于定義鍵盤的矩陣布局。應至少定義一個C宏，將數組轉換為代表鍵盤物理開關矩陣的矩陣。如果你的鍵盤可以構建多種布局，則應定義多個宏。

• 對于單一布局，應使用LAYOUT宏
• 對于多布局鍵盤，應有一個支持所有可能開關位置的基本布局LAYOUT_all，以及其他特定布局如LAYOUT_ansi、LAYOUT_iso等

6. 創建鍵盤C源文件

創建鍵盤的主C源文件（使用你的鍵盤名稱）：

添加以下內容：

#include "Despacito0o.h" // 包含鍵盤的頭文件(使用你自定義的名稱)

7. 創建config.h文件

創建config.h配置文件：

添加以下內容：

#pragma once // 防止頭文件被重復包含#define MATRIX_ROWS 4 // 定義矩陣的行數
#define MATRIX_COLS 4 // 定義矩陣的列數
#define MATRIX_ROW_PINS {B3, A1 , A2 , A3} // 定義行引腳
#define MATRIX_COL_PINS {A4, A15, A14, A8} // 定義列引腳
#define DIODE_DIRECTION COL2ROW // 定義二極管方向為列到行

config.h文件說明

config.h是最先被包含的C頭文件，其中設置的變量會在整個項目中持續存在。主要配置內容包括：

• 硬件選項：VID/PID、設備版本、廠商信息等
• 矩陣配置：行列數、引腳定義、二極管方向等
• 功能配置：背光、音頻、RGB燈效、防抖等
• 鍵盤行為：按鍵觸發時間、組合鍵設置等

8. 創建鍵盤映射文件

創建鍵盤映射的文件結構：先創建keymaps文件夾，然后在其中創建default文件夾，最后在default文件夾中創建keymap.c文件：

在keymap.c中添加以下內容：

#include  QMK_KEYBOARD_Hconst uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {[0] = LAYOUT(MI_B2  , KC_Q   , KC_W,  MI_C3  ,  // 第一行按鍵映射MI_F2  , MI_G2  , MI_A2, MI_OCTU, // 第二行按鍵映射MI_C2  , MI_D2  , MI_E2, MI_OCTD, // 第三行按鍵映射KC_PSLS, MI_OCTD, MO(1), KC_PENT  // 第四行按鍵映射，包含層切換按鍵MO(1)),[1] = LAYOUT(QK_BOOT, KC_P8 , RGB_MOD, RGB_TOG, // 第二層第一行：包含重啟引導和RGB控制KC_P4  , KC_G  , KC_A   , KC_PAST, // 第二層第二行KC_P1  , KC_P2 , KC_P3  , KC_PMNS, // 第二層第三行KC_PSLS, KC_P0 , KC_PDOT, KC_PENT  // 第二層第四行)
};

9. 創建鍵盤JSON配置文件

最后，創建一個keyboard.json文件（注意JSON文件中不能有注釋）：

添加以下內容：

{"keyboard_name": "Despacito0o", "manufacturer": "Despacito0o", "usb": {"vid": "0x1564", "pid": "0x8456", "device_version": "0.0.1" },"layouts": {"LAYOUT": {"layout": [{"matrix": [0, 0], "x": 0, "y": 0}, {"matrix": [0, 1], "x": 1, "y": 0}, {"matrix": [0, 2], "x": 2, "y": 0}, {"matrix": [0, 3], "x": 3, "y": 0}, {"matrix": [1, 0], "x": 0, "y": 1}, {"matrix": [1, 1], "x": 1, "y": 1}, {"matrix": [1, 2], "x": 2, "y": 1}, {"matrix": [1, 3], "x": 3, "y": 1}, {"matrix": [2, 0], "x": 0, "y": 2}, {"matrix": [2, 1], "x": 1, "y": 2}, {"matrix": [2, 2], "x": 2, "y": 2}, {"matrix": [2, 3], "x": 3, "y": 2}, {"matrix": [3, 0], "x": 0, "y": 3}, {"matrix": [3, 1], "x": 1, "y": 3}, {"matrix": [3, 2], "x": 2, "y": 3}, {"matrix": [3, 3], "x": 3, "y": 3}  ]}}
}

編譯固件

完成所有文件創建后，打開QMK MSYS終端，輸入以下命令進行編譯：

qmk compile -kb despacito0o -km default

看到綠色的成功信息，恭喜你已經成功創建了自己的鍵盤固件！

知識拓展：QMK架構關鍵概念

1. 鍵碼(Keycode)系統

QMK提供了豐富的鍵碼系統，包括：

• 基礎字母數字鍵（KC_A到KC_Z，KC_1到KC_0）
• 功能鍵（KC_F1到KC_F24）
• 特殊功能鍵（媒體控制、RGB控制等）
• 層控制鍵（MO、LT、TO、TG等）

2. 層(Layer)系統

QMK的層系統允許在有限的物理按鍵上實現多層功能：

• 基礎層(Base Layer)：默認層，通常為0
• 功能層：通過層控制鍵臨時激活或鎖定
• 層優先級：高層級覆蓋低層級的按鍵定義

3. Quantum鍵碼

QMK引入了獨特的高級鍵碼，如：

• Mod-Tap：按下為修飾鍵，點擊為普通鍵
• Layer-Tap：按下激活層，點擊為普通鍵
• One-Shot Keys：點擊后效果持續到下一個按鍵

4. 矩陣掃描

QMK通過矩陣掃描檢測按鍵狀態：

• 行列式矩陣：減少所需引腳數
• 二極管方向：COL2ROW或ROW2COL定義電流流向
• 防抖處理：避免按鍵彈跳導致的誤觸

結語

通過本教程，你已經掌握了QMK最新架構下創建自定義鍵盤固件的完整流程。這些基礎知識將幫助你進一步探索QMK的強大功能，如RGB燈光效果、OLED屏幕控制、旋鈕編碼器配置等高級特性。

希望這篇教程對你有所幫助，祝你在DIY鍵盤的道路上越走越遠！
QMK鍵碼參照表大全