QMK 实战[1x4] 1 Macropad 五键旋钮宏键盘固件解析与 Bootmagic 刷机指南【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware导读本文以 QMK Firmware 仓库中 [1x4] 1 Macropad 的完整键盘定义keyboards/arrayperipherals/1x4p1为研究对象深入剖析这款由 Array Peripherals 出品、以 Adafruit ItsyBitsy 32u4 为核心的五键1x4 矩阵按键 1 个带按压功能的旋钮宏键盘的固件结构、默认键位设计、旋钮回调实现并重点讲解其无物理复位按钮时依赖 Bootmagic Lite 进入 bootloader 的原理与操作细节。读完本文你将掌握如何在 QMK 数据驱动框架下读懂一个最小化 macropad 的keyboard.json、如何自定义旋钮与按键行为以及如何安全地使用 Bootmagic 触发刷机流程。一、硬件与固件概览1.1 键盘是什么[1x4] 1 Macropad 是一款小型宏键盘它由一排 1x4 的按键阵列4 个按键外加一个同时可以作为按钮按压的旋转编码器rotary encoder组成因此命名为 1x4 1。Keyboard Maintainer维护者David Doan硬件支持Hardware SupportedAdafruit ItsyBitsy 32u4 开发板硬件来源Hardware Availabilityarrayperipherals.com从仓库目录看该键盘仅包含四个核心文件keyboards/arrayperipherals/1x4p11x4p1/ ├── keyboard.json # 数据驱动的键盘定义引脚、USB、特性、布局 ├── readme.md # 键盘主页文档 └── keymaps/ └── default/ ├── keymap.c # 默认键位与旋钮回调 └── readme.md # 默认布局说明没有rules.mk、config.h或keyboard.h传统三件套——这说明该键盘完整采用了 QMK 的Data-Driven Configuration数据驱动配置模式所有硬件级配置都收敛到了keyboard.json中非常适合用来学习 QMK 新的配置范式。1.2 数据驱动配置keyboard.json 全解析keyboards/arrayperipherals/1x4p1/keyboard.json是理解这块板子的第一手资料其内容按功能块拆解如下配置块键值含义keyboard_name[1x4] 1 Macropad键盘显示名称manufacturerArray Peripherals制造商maintainerDavid Doan固件维护者usbvid: 0x4152pid: 0x4F46device_version: 0.0.1USB 识别信息VID/PID/版本processoratmega32u4主控芯片bootloadercaterinaItsyBitsy 32u4 使用的 Arduino 风格 bootloadermatrix_pins.direct[[C7,B7,D6,F5,F7]]直接驱动矩阵5 个按键各占一个独立引脚encoder.rotarypin_a: F0pin_b: F1旋转编码器的 A/B 相位引脚featuresbootmagic、encoder、extrakey、mousekey、nkro、unicode启用的 QMK 特性layouts.LAYOUT_ortho_1x55 个物理位置正交 1x5 布局定义矩阵direct 直连模式注意matrix_pins.direct中只有一个一维数组[C7,B7,D6,F5,F7]共 5 个引脚。这对应direct pins直接驱动矩阵模式每个按键直接连接一个 GPIO 引脚另一端接地不需要行扫描与列扫描固件只需逐个读引脚电平即可。5 个引脚 C7、B7、D6、F5、F7 分别对应 5 个按键位——其中前 4 个是常规按键第 5 个即旋钮的按压开关。旋钮encoder.rotaryencoder: { rotary: [ {pin_a: F0, pin_b: F1} ] }编码器 A、B 两相分别接 F0、F1。按 QMK 官方 Encoders 文档旋转编码器的 A、B 线应直连 MCUC/公共端应接地若顺时针方向反了可以交换 A/B 引脚定义。该定义在数据驱动模式下会自动展开为传统配置中的ENCODER_A_PINS { F0 }与ENCODER_B_PINS { F1 }。特性开关featuresfeatures: { bootmagic: true, encoder: true, extrakey: true, mousekey: true, nkro: true, unicode: true }bootmagic启动时按键进入 bootloader 的能力详见后文encoder旋转编码器支持extrakey媒体键如音量支持mousekey鼠标键支持——默认键位中的MS_WHLU/MS_WHLD滚轮上/下依赖它nkro无按键冲突N-Key RolloverunicodeUnicode 输入支持。布局LAYOUT_ortho_1x5layouts: { LAYOUT_ortho_1x5: { layout: [ {x: 0, y: 0, matrix: [0, 0]}, {x: 1, y: 0, matrix: [0, 1]}, {x: 2, y: 0, matrix: [0, 2]}, {x: 3, y: 0, matrix: [0, 3]}, {x: 4, y: 0, matrix: [0, 4]} ] } }尽管矩阵是 direct 模式、逻辑上只有 1 行QMK 仍把 5 个键映射为LAYOUT_ortho_1x51 行 5 列的正交布局坐标为 x0..4matrix 坐标为[0, 0]到[0, 4]。默认键位就是通过这个宏定义的。二、默认键位与旋钮行为keymap.c 逐段精读默认键位文件在keyboards/arrayperipherals/1x4p1/keymaps/default/keymap.c其配套说明见keymaps/default/readme.md。2.1 两层键位设计const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] { //button closest to usb is first [0] LAYOUT_ortho_1x5( KC_ESC, KC_TAB, KC_LSFT, KC_LCTL, TG(1) ), [1] LAYOUT_ortho_1x5( KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, TG(0) ) };第 0 层默认层从左到右依次为KC_ESCEsc、KC_TABTab、KC_LSFT左 Shift、KC_LCTL左 Ctrl最右侧即旋钮按压键是TG(1)——切换层Toggle Layer按下后在 0/1 层之间切换。第 1 层前 4 个键均为KC_TRNS透传实际沿用第 0 层行为最右侧为TG(0)用于切回第 0 层。默认布局文档中说明第二层留给用户自定义。代码注释特别强调button closest to usb is first靠近 USB 口的按键排在最前这是硬件接线顺序的提示阅读或修改键位时第 0 个位置对应离 USB 最近的按键。2.2 旋钮回调滚轮控制bool encoder_update_user(uint8_t index, bool clockwise) { if (index 0) { /* First encoder */ if (clockwise) { tap_code(MS_WHLU); } else { tap_code(MS_WHLD); } } return true; }该键盘只有 1 个编码器index 0顺时针旋转发送MS_WHLU鼠标滚轮上逆时针发送MS_WHLD鼠标滚轮下tap_code()用于发送一次按键事件这里依赖mousekey特性。在 QMK 中编码器回调存在用户层_user与键盘层_kb两级弱函数。查看源码 quantum/encoder.c__attribute__((weak)) bool encoder_update_user(uint8_t index, bool clockwise) { ... } __attribute__((weak)) bool encoder_update_kb(uint8_t index, bool clockwise) { ... }encoder_update_user默认实现为空弱符号用户在 keymap 中定义同名函数即可覆盖。若返回true则允许键盘层代码继续处理若返回false则会覆盖键盘层行为详见 docs/features/encoders.md 的 Callbacks 一节。此处返回true表示不阻止任何下层逻辑。替代方案Encoder Map。如果希望旋钮像按键一样按层生效例如在 Layer 1 上旋钮改为音量可以在 keymap 级启用ENCODER_MAP_ENABLE并定义encoder_map例如官方文档给出的形态#if defined(ENCODER_MAP_ENABLE) const uint16_t PROGMEM encoder_map[][NUM_ENCODERS][NUM_DIRECTIONS] { [0] { ENCODER_CCW_CW(MS_WHLU, MS_WHLD) }, [1] { ENCODER_CCW_CW(KC_VOLD, KC_VOLU) }, }; #endifEncoder Map 会把旋钮事件推入正常的 QMK 键码处理管线process_record_xxxxx()默认按键延迟与TAP_CODE_DELAY一致也可用ENCODER_MAP_KEY_DELAY调整。注意官方建议仅在 keymap 层级启用该特性。三、进入 Bootloader无复位键的 Bootmagic Lite 方案3.1 为什么要 BootmagicItsyBitsy 32u4 这类开发板通常没有独立的物理复位按键而刷写固件必须进入 bootloader。该键盘的 readme.md 明确说明The stock version of the macropad has bootmagic lite enabled. To trigger the bootloader, the first key (key furthest way from the rotary) needs to be held down when plugging the keyboard in.即将距离旋钮最远的那个按键即第一个按键对应keyboard.json中matrix_pins.direct的第一个引脚 C7键位上是KC_ESC按住同时插入 USB 线即可进入 bootloader 刷机模式。3.2 Bootmagic 的原理源码级Bootmagic 的现代版本只做一件事在启动时检测指定按键是否被按住若是则重置 EEPROM 并跳转 bootloader。官方文档 docs/features/bootmagic.md 指出这对没有物理复位按钮的板子尤其重要。核心实现在quantum/bootmagic/bootmagic.c__attribute__((weak)) bool bootmagic_should_reset(void) { uint8_t row BOOTMAGIC_ROW; uint8_t col BOOTMAGIC_COLUMN; ... return matrix_get_row(row) (1 col); } __attribute__((weak)) void bootmagic_scan(void) { // We need multiple scans because debouncing cant be turned off. matrix_scan(); wait_ms(BOOTMAGIC_DEBOUNCE); matrix_scan(); if (bootmagic_should_reset()) { bootmagic_reset_eeprom(); // Jump to bootloader. bootloader_jump(); } }流程拆解上电后执行多次matrix_scan()期间等待BOOTMAGIC_DEBOUNCE完成消抖读取BOOTMAGIC_ROW/BOOTMAGIC_COLUMN指定的矩阵位置默认 0,0即绝大多数键盘的 Esc 位若该键被按住matrix_get_row(row) (1 col)非 0则调用bootmagic_reset_eeprom()清除 EEPROM 有效标志随后bootloader_jump()跳入 bootloader。默认行列值定义在quantum/bootmagic/bootmagic.h# define BOOTMAGIC_ROW BOOTMAGIC_LITE_ROW ... #ifndef BOOTMAGIC_ROW # define BOOTMAGIC_ROW 0 #endif在本键盘场景中bootmagic特性已在keyboard.json中开启且默认行列 (0, 0) 恰好就是距离旋钮最远的第一个按键C7 / Esc因此出厂即开箱可用无需额外配置。重要提醒文档原文务必遵守使用 Bootmagic 会每次都重置 EEPROM因此任何已保存的设置如按键层自定义、VIA 配置等都会丢失。请仅在刷机前确认无需保留设置或在刷机后重新配置。3.3 刷写流程参考 QMK 的 Build Environment Setup 与 Make Instructions本键盘的典型流程如下按上文方式按住距离旋钮最远的第一个键Esc插入 USB 线使其进入 bootloader在 QMK 环境中编译并刷写qmk compile -kb arrayperipherals/1x4p1 qmk flash -kb arrayperipherals/1x4p1或者使用传统 make 方式make arrayperipherals/1x4p1:default:flashbootloader 类型为caterinaQMK 会自动调用 avrdude 完成烧录。若需自定义 Bootmagic 触发键例如板子矩阵特殊可在传统配置的config.h中设置#define BOOTMAGIC_ROW 0 #define BOOTMAGIC_COLUMN 1默认均为 0对应 Esc 位。进阶用户还可以覆盖弱函数bootmagic_scan()增加额外逻辑例如要求同时按多个键才触发但官方提醒该函数在多数特性初始化之前被调用逻辑务必保持简单可靠。四、如何扩展与自定义4.1 修改键位编辑keyboards/arrayperipherals/1x4p1/keymaps/default/keymap.c或为你的用户名新建keymaps/name/keymap.c例如把第 0 层改为媒体控制、把第 1 层留给组合键[0] LAYOUT_ortho_1x5( KC_MPLY, KC_MNXT, KC_MPRV, KC_MUTE, TG(1) ),编译命令相应地改为qmk compile -kb arrayperipherals/1x4p1 -km name。4.2 修改旋钮行为保持现在的encoder_update_user回调风格替换tap_code()的参数即可如KC_VOLU/KC_VOLD、KC_PGUP/KC_PGDN或启用 Encoder Map 实现按层区分旋钮功能见 2.2 节如果旋钮方向反了可交换keyboard.json中pin_a/pin_b的定义。4.3 布局宏的复用所有按键与旋钮按压键统一通过LAYOUT_ortho_1x5(...)宏排布旋钮按压键位于第 5 个位置。修改布局时保持 5 个参数与keyboard.json中layout数组一一对应即可。五、小结[1x4] 1 Macropad 是一个体量极小但结构完整的 QMK 示例它展示了现代 QMK 的三件事数据驱动配置整个硬件定义收敛于一个 keyboard.json从 USB 信息、direct 矩阵、旋钮引脚到布局宏一应俱全编码器回调范式encoder_update_user弱函数覆盖 tap_code组合配合 docs/features/encoders.md 可以轻松扩展为按层旋钮映射Bootmagic Lite 刷机方案无物理复位键的板子通过按住首键上电即可进入 bootloader其背后是quantum/bootmagic/bootmagic.c中扫描-校验-重置 EEPROM-跳转的完整链路且代价是每次触发都会清空 EEPROM 设置。对于任何想要理解最小可用的 QMK 键盘工程长什么样的开发者这是一个理想的阅读与改造起点。【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考