QMK 键盘固件移植指南以 CannonKeys Rekt1800STM32F072为例解读键盘目录结构与数据驱动配置【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware本文以 QMK Firmware 仓库中 CannonKeys Rekt1800 键盘的官方支持为切入点系统讲解一块基于 STM32F072 的 1800 配列机械键盘在 QMK 中的目录组织、keyboard.json数据驱动配置、矩阵与背光底层实现以及如何用make命令编译烧录。读完本文你将掌握读懂任意一款 QMK 官方键盘目录并自行编译默认固件的完整方法。键盘简介与仓库定位CannonKeys Rekt1800 是 CannonKeys 推出的一款 1800 配列键盘在标准全尺寸基础上压缩方向键区右侧保留完整数字小键盘由 Andrew Kannan 目录其官方说明文档即 readme.md。与其他键盘一样Rekt1800 的目录同时包含人可读的说明与机器可读的构建配置两类文件文件作用readme.md键盘简介、维护者、支持硬件与编译命令keyboard.json数据驱动配置主文件USB、矩阵、背光、布局等config.h传统 C 宏配置此处用于背光 PWM 驱动声明rules.mkMakefile 变量用于覆盖 DFU 烧录后缀chconf.h / halconf.h / mcuconf.hChibiOS 内核/外设配置由qmk chibios-confmigrate自动生成matrix_diagram.mdASCII 矩阵接线图keymaps/default/keymap.c默认键位映射编译与烧录从 readme 开始readme 中给出的编译命令是该键盘一切使用流程的起点。在完成 QMK 构建环境搭建后进入仓库根目录执行make cannonkeys/rekt1800:default该命令的含义是为cannonkeys/rekt1800这个键盘目标编译default键位映射产物为可烧录的固件通常位于build/目录下。QMK 的make命令采用键盘路径:键位名的约定其中键位名可替换为keymaps/目录下的任意子目录名例如keymaps/default即对应default。如果你还没有构建环境可以参阅仓库内的 getting_started_build_tools.md 完成工具链安装编译规则细节见 getting_started_make_guide.md首次接触 QMK 的用户建议先阅读 newbs.md 系列新手教程。DFU 烧录后缀的特别处理readme.md 未展开说明的一个细节藏在 rules.mk 中# Wildcard to allow APM32 MCU DFU_SUFFIX_ARGS -v FFFF -p FFFFQMK 在生成 STM32 DFU 固件时会写入 vendor/product 后缀校验字段而这里用通配符FFFF覆盖了默认值。从注释可以看出其目的是兼容 APM32 系列 MCUSTM32F072 的国产兼容芯片保证同一份固件既能刷入 STM32F072CBT6也能刷入引脚兼容的 APM32 替代芯片。数据驱动配置keyboard.json 全解析现代 QMK 键盘的核心配置集中在keyboard.json中数据驱动配置的总体说明见 data_driven_config.md。Rekt1800 的配置可以拆成几个层次来看。基础信息与 USB 描述符{ keyboard_name: Rekt1800, manufacturer: CannonKeys, url: https://cannonkeys.com, maintainer: awkannan, usb: { vid: 0xCA04, pid: 0x2377, device_version: 0.0.1 }, processor: STM32F072, bootloader: stm32-dfu }keyboard_name/manufacturer在主机侧显示为设备名称与厂商字符串vid/pidUSB 厂商 ID 与产品 ID0xCA04为 CannonKeys 的 VIDdevice_version为设备版本号processor指定STM32F072对应芯片为 readme 中提到的 STM32F072CBT6bootloaderstm32-dfu表示使用 STM32 内置 DFU 引导加载程序通过 BOOT0 引脚或复位键进入这也是rules.mk中 DFU 后缀参数发挥作用的前提。矩阵接线6 行 19 列matrix_pins: { cols: [B12, A14, A15, B3, B4, B5, B6, B7, B8, B9, A7, B0, B1, B2, B10, A3, A4, A5, C15], rows: [C13, C14, A0, A1, A2, B11] }, diode_direction: COL2ROW行引脚 6 个C13、C14、A0、A1、A2、B11列引脚 19 个B12、A14、A15、B3~B9、A7、B0、B1、B2、B10、A3、A4、A5、C15构成 6×19 的矩阵与 1800 配列的全键位规模相符diode_direction为COL2ROW即二极管正极接列、负极接行扫描时行列方向的决定性参数。矩阵的物理接线关系可对照 matrix_diagram.md 中的 ASCII 图图中行号 列号的十六进制编号如00、1D、4E直接对应[row, col]矩阵坐标例如1D表示第 1 行第 D13列即 2u Backspace 左半边。背光PWM 呼吸灯配置backlight: { pin: A6, levels: 6, breathing: true }背光由A6引脚以 PWM 方式驱动支持 6 级亮度与呼吸效果breathing。其底层实现横跨两个文件config.h 指定 PWM 定时器映射#define BACKLIGHT_PWM_DRIVER PWMD3 #define BACKLIGHT_PWM_CHANNEL 1 #define BACKLIGHT_PAL_MODE 1mcuconf.h 打开对应定时器与总线外设#undef STM32_PWM_USE_TIM3 #define STM32_PWM_USE_TIM3 TRUE #undef STM32_SPI_USE_SPI2 #define STM32_SPI_USE_SPI2 TRUEBACKLIGHT_PWM_DRIVER指向 ChibiOS 的 PWM 驱动PWMD3即 TIM3 定时器CHANNEL 1与PAL_MODE 1指定输出通道和 GPIO 复用模式而 halconf.h 中的HAL_USE_PWM TRUE则是启用 PWM HAL 模块的前提。三个配置文件配合完成A6 引脚输出 PWM 驱动背光 LED的完整链路STM32_SPI_USE_SPI2则是为后续 SPI 外设预留的能力开关。功能特性开关features: { bootmagic: true, mousekey: true, extrakey: true, console: true, command: true, nkro: true, backlight: true }, qmk: { locking: { enabled: true, resync: true } }bootmagic开机时按住特定键可临时改变键位/配置详见 feature_bootmagic 相关文档mousekey/extrakey鼠标键与媒体键支持console/command调试终端输出与 QMK 命令行调试功能nkroUSB 全键无冲突N-Key Rolloverbacklight启用背光功能对应上述 PWM 配置qmk.locking启用 Caps Lock/Scroll Lock/Num Lock 锁定键支持并开启resync锁状态重新同步。config.h 中还保留了通过注释开关裁剪功能的传统写法NO_DEBUG、NO_PRINT、NO_ACTION_LAYER等用于在需要压缩固件体积时按需关闭特性。默认键位LAYOUT_all 双分层实现默认键位位于 keymaps/default/keymap.c定义了两个层enum layer_names { _BASE, _FN1, };_BASE层使用LAYOUT_all宏覆盖 1800 配列全部键位主键区、F 区、方向键区与数字小键盘区包括 2u Backspace、ISO Enter 等异型键_FN1层通过MO(_FN1)按住 Fn 临时切换触发集中放置功能键QK_BOOT一键进入 DFU 刷写模式BL_BRTG、BL_UP、BL_DOWN、BL_TOGG背光呼吸、增亮、减亮、开关与keyboard.json中breathing: true的配置相呼应。值得注意的细节是_FN1层第 2 行多写了一个KC_TRNS该宏期望 19 个键位行内实际列数为 19这不会影响编译与使用属于键位数组与矩阵列数对应关系的直观体现——LAYOUT_all宏的实参个数必须与布局定义中键位数严格一致。布局家族一套 PCB 五种配列keyboard.json的layouts字段同时定义了 5 个布局宏使同一块 PCB 能适配不同键帽配列布局宏特点LAYOUT_all全键位布局容纳 2u Backspace、ISO Enter 等所有变体LAYOUT_ansiANSI 配列2u Backspace、单行回退LAYOUT_ansi_split_bsANSI 配列 分裂 BackspaceLAYOUT_isoISO 配列左侧带¬、长Enter竖向布局LAYOUT_iso_split_bsISO 配列 分裂 Backspace每个布局宏中的每个键位都通过{label: ..., matrix: [行, 列], x: ..., y: ...}描述matrix坐标必须与 matrix_diagram.md 的接线一一对应x/y及w/h则决定键位在视觉排布与 QMK Configurator 中的位置与大小。编写自定义键位时只需选择与你物理配列匹配的布局宏即可例如默认键位选用LAYOUT_all。底层运行时配置ChibiOS 三件套Rekt1800 的三个*conf.h文件头部都注明由qmk chibios-confmigrate命令从平台通用模板自动生成qmk chibios-confmigrate -i keyboards/cannonkeys/rekt1800/mcuconf.h -r platforms/chibios/GENERIC_STM32_F072XB/configs/mcuconf.hchconf.h设置系统节拍频率CH_CFG_ST_FREQUENCY 1000010 kHz关闭速度优化CH_CFG_OPTIMIZE_SPEED FALSE与带超时的条件变量CH_CFG_USE_CONDVARS_TIMEOUT FALSEhalconf.h启用 PWM 与 SPI HALmcuconf.h在GENERIC_STM32_F072XB模板基础上覆盖 TIM3 PWM 与 SPI2 外设开关。这三个文件共同决定了 ChibiOS 内核调度与 STM32F072 外设的初始化行为是背光 PWM 能正常工作的底层支撑。普通用户无需修改它们只有当自定义键盘需要新增外设如 SPI 屏幕、额外定时器时才需要参考 platformdev_chibios_earlyinit.md 等平台开发文档进行调整。从零开始把 Rekt1800 作为自定义键盘的参考模板Rekt1800 的目录结构是 QMK 现代数据驱动键盘的标准范例非常适合作为移植参考复制目录结构保留keyboard.json、config.h、rules.mk、*conf.h、keymaps/修改keyboard.json中的名称、厂商、USB ID、matrix_pins与layouts布局可直接参考其 5 种配列的坐标写法按需裁剪features开关新建键位映射后执行make 你的键盘路径:键位名编译。如需了解数据驱动配置的完整字段含义可继续阅读 reference_info_json.md矩阵原理可参考 how_a_matrix_works.md 与 custom_matrix.md。编译与烧录环境准备完毕后make cannonkeys/rekt1800:default即可得到可烧录固件按住QK_BOOT键进入 DFU 模式后即可用qmk flash或对应 DFU 工具完成刷写。小结通过 CannonKeys Rekt1800 这一个案例可以看到QMK 对一块键盘的支持是文档说明 数据驱动配置 底层外设配置 键位映射四层结构的组合readme 提供入口信息keyboard.json承载大部分硬件描述config.h/rules.mk/ChibiOS 三件套补充底层细节keymaps/决定最终手感。理解这套结构之后无论是编译官方键盘固件、还是为自定义 PCB 移植 QMK都能按图索骥、快速上手。【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考