QMK鍵盤固件配置詳解

前言

大家好！今天給大家帶來QMK鍵盤固件配置的詳細指南。如果你正在DIY機械鍵盤或者想要給自己的鍵盤刷固件，這篇文章絕對不容錯過。QMK是目前最流行的開源鍵盤固件框架之一，它允許我們對鍵盤進行高度自定義。接下來，我們將深入了解QMK的配置項，幫助你打造一把獨一無二的機械鍵盤！

基礎配置

鍵盤矩陣設置

#define MATRIX_ROWS 5
#define MATRIX_COLS 15
#define MATRIX_ROW_PINS { D0, D5, B5, B6 }
#define MATRIX_COL_PINS { F1, F0, B0, C7, F4, F5, F6, F7, D4, D6, B4, D7 }

這些參數定義了鍵盤的物理矩陣結構：

• MATRIX_ROWS：鍵盤矩陣的行數
• MATRIX_COLS：鍵盤矩陣的列數
• MATRIX_ROW_PINS：行引腳定義，從上到下排列
• MATRIX_COL_PINS：列引腳定義，從左到右排列

如果你采用替代方式處理矩陣讀取，可以省略引腳定義，詳情請參閱低級矩陣重寫(low-level matrix overrides)。

矩陣相關配置

#define MATRIX_IO_DELAY 30
#define MATRIX_HAS_GHOST
#define MATRIX_UNSELECT_DRIVE_HIGH
#define DIODE_DIRECTION COL2ROW

• MATRIX_IO_DELAY：更改矩陣引腳狀態和讀取值之間的延遲（微秒）
• MATRIX_HAS_GHOST：定義矩陣是否有重影現象（不太常見）
• MATRIX_UNSELECT_DRIVE_HIGH：取消選擇矩陣引腳時設置為輸出高電平而非輸入高電平
• DIODE_DIRECTION：二極管方向，COL2ROW表示二極管黑色標記面向行，ROW2COL表示反方向

直接引腳映射

#define DIRECT_PINS { { F1, F0, B0, C7 }, { F4, F5, F6, F7 } }

當每個按鍵直接連接到單獨的引腳和接地時，可以使用此配置定義引腳映射。

音頻功能配置

#define AUDIO_VOICES
#define AUDIO_PIN C4
#define AUDIO_PIN_ALT B5

QMK支持通過蜂鳴器或揚聲器輸出音頻。上述配置啟用音頻功能并指定音頻輸出引腳。AUDIO_PIN_ALT與AUDIO_PIN一起使用可實現雙聲道輸出。

💡 小知識：QMK音頻功能不僅可以播放簡單的提示音，還能演奏整首歌曲！你可以用它來設置開機音樂，甚至可以在打字時播放音效。

背光配置

#define BACKLIGHT_PIN B7
#define BACKLIGHT_LEVELS 3
#define BACKLIGHT_BREATHING
#define BREATHING_PERIOD 6

這些選項用于配置鍵盤背光：

• BACKLIGHT_PIN：背光控制引腳
• BACKLIGHT_LEVELS：背光亮度級別數（最多31級，不包括關閉狀態）
• BACKLIGHT_BREATHING：啟用背光呼吸效果
• BREATHING_PERIOD：一個背光"呼吸"周期的時長（秒）

按鍵行為配置

#define DEBOUNCE 5
#define TAPPING_TERM 200
#define TAPPING_TERM_PER_KEY
#define RETRO_TAPPING
#define PERMISSIVE_HOLD
#define QUICK_TAP_TERM 100

這部分涉及按鍵檢測和雙功能鍵的行為設置：

• DEBOUNCE：按鍵去抖動延遲（默認5ms）
• TAPPING_TERM：點按變為長按的時間閾值（毫秒）
• TAPPING_TERM_PER_KEY：啟用針對每個鍵單獨設置TAPPING_TERM
• RETRO_TAPPING：如果在TAPPING_TERM時間內按下并釋放鍵，且期間沒有其他鍵干擾，則仍視為點擊
• PERMISSIVE_HOLD：如果在釋放前按下另一個鍵，即使未到TAPPING_TERM時間也觸發長按功能
• QUICK_TAP_TERM：定義雙角色鍵重復激活的時間窗口

高級特性配置

鼠標鍵配置

#define MOUSEKEY_INTERVAL 20
#define MOUSEKEY_DELAY 0
#define MOUSEKEY_TIME_TO_MAX 60
#define MOUSEKEY_MAX_SPEED 7
#define MOUSEKEY_WHEEL_DELAY 0

這些參數控制鍵盤模擬鼠標時的行為特性，可以調整速度和加速度等參數。

拆分鍵盤配置

#define SPLIT_HAND_PIN B7
#define EE_HANDS
#define MASTER_RIGHT
#define USE_I2C
#define SOFT_SERIAL_PIN D0
#define SPLIT_USB_DETECT
#define SPLIT_TRANSPORT_MIRROR

拆分鍵盤（如Ergodox、Corne等）需要這些特殊配置來實現兩半部分的通信和協調：

• SPLIT_HAND_PIN：通過引腳電平確定左右手（高=左，低=右）
• EE_HANDS：從EEPROM讀取左右手信息
• MASTER_RIGHT：定義右半部分為主控端（默認左半部分為主控）
• USE_I2C：使用I2C而非串行通信（默認串行）
• SOFT_SERIAL_PIN：使用軟串行時的通信引腳
• SPLIT_USB_DETECT：檢測USB連接以決定主從關系
• SPLIT_TRANSPORT_MIRROR：在從機上鏡像主機矩陣狀態

💡 進階提示：拆分鍵盤設計中，需要特別注意兩半之間的通信延遲問題。如果遇到響應滯后，可以嘗試調整通信速率或切換通信方式。

USB端點配置和兼容性

QMK通過USB端點提供各種功能，但每個微控制器的端點資源有限。以下功能可能會占用單獨的端點：

• MOUSEKEY_ENABLE
• EXTRAKEY_ENABLE
• CONSOLE_ENABLE
• NKRO_ENABLE
• MIDI_ENABLE
• RAW_ENABLE
• VIRTSER_ENABLE

為了優化資源使用，QMK默認會合并一些功能到同一端點。但這可能帶來兼容性問題：

KEYBOARD_SHARED_EP = yes
MOUSE_SHARED_EP = no

• KEYBOARD_SHARED_EP = yes：將基本鍵盤功能合并到一個端點，但可能在某些BIOS中不兼容
• MOUSE_SHARED_EP = no：取消鼠標功能的合并，以保持Boot Mouse兼容性

?? 重要提示：組合鼠標會破壞Boot Mouse的兼容性。如果需要保持兼容性，請設置MOUSE_SHARED_EP = no。

rules.mk文件配置

除了config.h外，QMK還使用rules.mk文件來配置編譯選項：

DEFAULT_FOLDER = keyboard/default
FIRMWARE_FORMAT = bin
SRC += my_custom.c
LIB_SRC += lib_custom.c
LAYOUTS = 60_ansi 60_iso
LTO_ENABLE = yes

主要的功能選項包括：

MAGIC_ENABLE = yes        # 魔術鍵功能
BOOTMAGIC_ENABLE = yes    # 啟用Bootmagic
MOUSEKEY_ENABLE = yes     # 鼠標鍵
EXTRAKEY_ENABLE = yes     # 音頻控制和系統控制
CONSOLE_ENABLE = no       # 調試控制臺
COMMAND_ENABLE = no       # 調試和配置命令
NKRO_ENABLE = yes         # USB N-Key無沖
AUDIO_ENABLE = yes        # 音頻子系統
RGBLIGHT_ENABLE = yes     # RGB燈光
SPLIT_KEYBOARD = yes      # 分體式鍵盤支持

總結

通過QMK的豐富配置選項，我們可以實現鍵盤的高度定制化。從簡單的矩陣定義到復雜的分體鍵盤通信，從基礎按鍵去抖到花哨的RGB燈效，QMK幾乎能滿足所有DIY鍵盤愛好者的需求。

希望這篇教程對你有所幫助！如果你還有疑問，歡迎在評論區留言交流。記得點贊收藏，下期再見！

---

參考資料：

• QMK官方文檔
• QMK GitHub倉庫
• 機械鍵盤DIY社區