QMK键盘固件配置详解

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社区