企业官网建设流程全解析

QMK 键盘固件实战：Erdnuss65 的编译、烧录与配置解析

【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware

Erdnuss65 是由 Citrus Lab（维护者 ctt）设计的一款基于 STM32F103C8T6 主控的 65% 配列机械键盘，其 QMK 固件位于本仓库的 keyboards/citrus/erdnuss65 目录下。本篇指南以该键盘的官方 readme.md 为主线，结合仓库内实际的keyboard.json、config.h、erdnuss65.c与默认键位源码，系统讲解从构建环境准备、固件编译烧录，到矩阵配置、RGB 指示灯与双层键位的完整技术细节。读完本文，你将掌握 Erdnuss65 固件的构建与刷写流程，并能读懂其数据驱动配置与底层实现。

键盘概况与硬件基础

Erdnuss65 的维护信息记录在仓库目录的 readme 中，核心事实如下：

从 keyboard.json 可以看出这是一块 65% 配列（5 行 × 15 列，含方向键与 Insert/Delete 列）的键盘：

• 矩阵采用COL2ROW二极管方向，行引脚为B10、B1、B0、A7、A6，列引脚为B12、B14、B15、B5、B13、B3、B4、B6、A0、A1、A2、A3、A4、A5、B11；
• 主控为STM32F103，USB VID 为0x636C、PID 为0x6374，设备版本1.0.0；
• 板载一颗 WS2812 RGB LED，数据引脚为A15（rgblight.led_count为 1）；
• 固件启用的特性包括：bootmagic、extrakey、mousekey、nkro、rgblight。

这里有一个值得注意的细节：矩阵定义中多组键位（如 K03 与 K07、K08 与 K0A 附近的引脚标注）在布局 JSON 中出现了引脚标注与matrix索引不完全一致的情况，例如K03标注为(B10,B5)而K07也标注为(B10,B5)，且部分键位（如K08、K09）标注的列引脚与矩阵列定义存在出入。从源码结构看，这更可能是布局标注信息的历史遗留问题，实际扫描由matrix_pins的 15 个列引脚与diode_direction: COL2ROW共同决定；对用户而言，编译与烧录并不受影响。真正决定矩阵行为的是 keyboard.json 中的matrix_pins与diode_direction字段。

构建环境准备与固件编译

Erdnuss65 的固件编译遵循 QMK 的标准流程。官方 readme 给出的构建命令为：

make citrus/erdnuss65:default

前提是已经完成 QMK 构建环境（工具链、编译器）的搭建，并正确设置了qmk_firmware仓库。该命令会以citrus/erdnuss65键盘目录下默认键位（keymaps/default）为目标进行编译，产物为可烧录的固件镜像。仓库的 Makefile 与 builddefs/build_keyboard.mk 会在编译时根据 keyboard.json 中声明的processor、bootloader、features等字段自动生成对应的构建选项。

对于keyboard.json中启用的特性，QMK 会将其映射为编译宏：

• bootmagic: true使能 Bootmagic 复位/配置功能；
• nkro: true启用 N 键无冲突上报；
• rgblight: true启用板载 RGB 背光；
• qmk.locking.resync: true表示启用 Caps Lock 等锁定键的重新同步行为。

默认键位结构

默认键位定义位于 keymaps/default/keymap.c，包含两层布局。层 0 为常规输入层，采用QK_GESC（Esc 键在按住时表现为 Grave 键）、标准字母区、KC_CAPS、KC_LSFT/KC_RSFT、KC_LCTL/KC_LGUI/KC_LALT、7U 空格（KC_SPC）、MO(1)功能键以及KC_LEFT、KC_DOWN、KC_RGHT等方向键；层 1 为功能层，由MO(1)按住触发，映射了KC_F1~KC_F12、KC_TILD、KC_PSCR、QK_BOOT、KC_CALC、KC_MYCM、媒体键（KC_MPRV/KC_MNXT/KC_MUTE/KC_VOLD/KC_VOLU/KC_MPLY）以及KC_HOME/KC_END等导航键。其中层 1 的QK_BOOT正是进入 bootloader 的键位途径之一。

烧录固件与三种进入 Bootloader 的方式

官方 readme 给出的烧录命令为：

make citrus/erdnuss65:default:flash

由于该键盘使用stm32duino作为 bootloader，烧录时 QMK 会调用与 STM32duino 配套的烧录方式（通常基于 USB 串口的 maple 协议）。对应的链接脚本与板级定义位于仓库的 platforms/chibios/boards/STM32_F103_STM32DUINO 目录，例如STM32F103xB_stm32duino.ld定义了 F103 系列的 Flash/RAM 布局。

readme 明确列出了 3 种进入 bootloader 的方式，这是刷写固件时的关键操作：

1. Bootmagic 复位：按住矩阵 (0,0) 位置的键（通常是左上角第一颗键或 Esc 键）的同时插入 USB 线，即可进入 bootloader。该功能由 keyboard.json 中的bootmagic: true特性支持。
2. 物理复位按钮：短按 PCB 背面的复位按钮；部分批次没有实体按钮，而是需要短接预留的复位焊盘。
3. 键位触发：按下键位映射为QK_BOOT的键。Erdnuss65 默认键位在层 1 已内置该键（见 keymaps/default/keymap.c），按住MO(1)（FN 键）的同时按下对应位置即可触发。

数据驱动配置解析：keyboard.json 与 config.h

Erdnuss65 采用 QMK 的数据驱动配置方式，硬件描述集中在 keyboard.json 中，而板级编译期配置放在 config.h。

keyboard.json 中的关键字段

config.h 中的 RGB 层配置

config.h 额外定义了两个与指示灯相关的编译宏：

#define RGBLIGHT_LAYERS #define RGBLIGHT_LAYERS_OVERRIDE_RGB_OFF

• RGBLIGHT_LAYERS：允许定义可按需开关的 RGB 光照层，非常适合用来指示当前键盘所在层或 Caps Lock 等锁定状态；
• RGBLIGHT_LAYERS_OVERRIDE_RGB_OFF：定义后，即使 RGB 背光整体处于关闭状态，也会强制显示光照层内容，保证指示功能不被背光开关影响。

指示灯实现：Caps Lock 白色指示

Erdnuss65 的板载 RGB LED 在键盘级实现了一个指示灯功能，源码位于 erdnuss65.c：

bool led_update_kb(led_t led_state) { if (led_update_user(led_state)) { if (led_state.caps_lock) { rgblight_setrgb_at(255, 255, 255, 0); //white } else { rgblight_setrgb_at(0, 0, 0, 0); } } return true; }

其工作原理为：

1. 每次 LED 状态变化时，led_update_kb被调用；
2. 先调用led_update_user，给用户层留出扩展机会，其返回值为true才继续执行键盘级逻辑；
3. 当Caps Lock处于激活状态时，通过rgblight_setrgb_at(255, 255, 255, 0)将索引 0 的 LED（即唯一的板载 WS2812）设为白色；
4. 否则调用rgblight_setrgb_at(0, 0, 0, 0)将其熄灭。

结合 config.h 中的RGBLIGHT_LAYERS_OVERRIDE_RGB_OFF，即使 RGB 背光被关闭，Caps Lock 的白色指示依然能够显示，兼顾了背光关闭场景下的状态可见性。

从 readme 到仓库：进一步探索的入口

官方 readme 还引导用户参考 QMK 官方文档了解构建环境与 make 用法，对应到本仓库的本地文档即 getting_started_build_tools（实际路径为 docs/newbs_getting_started.md 与 docs/getting_started_make_guide.md）。如果你是 QMK 新手，建议从 docs/newbs.md 的完整新手指南开始。Erdnuss65 的完整源码位于 keyboards/citrus/erdnuss65，其中：

• keyboard.json 提供硬件与布局的完整数据驱动定义；
• keymaps/default/keymap.c 提供默认双层键位示例；
• erdnuss65.c 展示键盘级led_update_kb的典型写法。

如需修改键位，可参照默认键位在keymaps下新建用户键位目录，编译命令中的:default替换为对应键位名即可（例如make citrus/erdnuss65:yourkeymap），再通过:flash目标烧录。

小结

Erdnuss65 是一个基于 STM32F103C8T6、采用 stm32duino bootloader 的 65% 键盘，其固件完整体现了 QMK 数据驱动配置与分层键位的组织方式。核心操作要点可归纳为：

• 编译：make citrus/erdnuss65:default
• 烧录：make citrus/erdnuss65:default:flash
• 进入 bootloader：Bootmagic（按住左上角键插入 USB）、物理复位按钮、QK_BOOT键位三种方式任选其一
• 指示灯：erdnuss65.c中通过led_update_kb实现 Caps Lock 白色指示，配合config.h的RGBLIGHT_LAYERS相关宏保证指示在背光关闭时仍可见

以上信息均可在仓库的 keyboards/citrus/erdnuss65 目录下直接查阅与验证。

【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware