企业官网建设流程全解析

QMK 固件中的 Desire65 键盘：基于 RP2040 的 65% 开源机械键盘编译、刷写与 Bootloader 指南

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

导读

Desire65 是 ArcherKeyboard 推出的一款 65% 配列的开源机械键盘，其固件已正式收录于本仓库（QMK Firmware）。本文以 keyboards/archerkeyboard/desire65/readme.md 为主线，结合 keyboard.json 数据驱动配置与 默认键位，系统讲解 Desire65 的硬件特性、编译与刷写命令、三种进入 Bootloader 的方式，以及键盘矩阵、RGB 灯效与配列定义的底层实现。阅读完本文，你将能够从零编译 Desire65 固件、顺利刷入键盘，并理解其>"matrix_pins": { "cols": ["GP21", "GP29", "GP1", "GP0", "GP15", "GP14", "GP13", "GP12", "GP11", "GP10", "GP9", "GP8", "GP2", "GP5", "GP4", "GP3"], "rows": ["GP24", "GP25", "GP19", "GP16", "GP17"] }

由于diode_direction为COL2ROW，每一列的二极管阳极连接列引脚、阴极连接行引脚，QMK 在扫描矩阵时会先拉低各列再读取行电平，从而定位按下的按键坐标。矩阵扫描逻辑可参考仓库中的quantum/matrix.c等核心实现。

2.2 启用功能特性

features字段声明了默认编译进固件的功能：

• bootmagic: true—— 允许通过 Bootmagic 快捷方式（如本文档所述的复位方式）进入刷写模式；
• extrakey—— 支持多媒体键（音量、媒体播放等）；
• mousekey—— 支持鼠标键功能；
• nkro—— 支持 N 键无冲突（NKRO）；
• rgblight—— 支持 RGB 灯效。

2.3 RGB 灯效配置

Desire65 采用WS2812 可寻址 RGB LED方案，配置如下：

"ws2812": { "driver": "vendor", "pin": "GP26" }, "rgblight": { "driver": "ws2812", "led_count": 17, "sleep": true, "animations": { "breathing": true, "rainbow_mood": true, "rainbow_swirl": true, "static_gradient": true, "twinkle": true }, "default": { "animation": "rainbow_mood", "val": 128 } }

要点：

• 灯带挂在GP26引脚，共17 颗 LED，驱动为厂商（vendor）原生驱动，对应仓库drivers/led/ws2812.c与quantum/rgblight/实现；
• 内置了 5 种动画：呼吸（breathing）、彩虹心情（rainbow_mood）、彩虹漩涡（rainbow_swirl）、静态渐变（static_gradient）、闪烁（twinkle）；
• 默认灯效为 rainbow_mood，亮度 128（取值范围 0～255），开机即生效；
• sleep: true表示键盘休眠时自动关闭 RGB，节省功耗。

2.4 指示灯

Caps Lock 指示灯映射到 GPIO 18：

"indicators": { "caps_lock": "GP18" }

即按下 Caps Lock 时，该引脚会驱动 LED 点亮，具体指示灯逻辑可在quantum/quantum.c及平台层实现中查看。

三、编译固件

在完成 QMK 构建环境搭建后，编译 Desire65 默认键位固件的命令为：

make archerkeyboard/desire65:default

命令中的三段含义：

• archerkeyboard—— 厂商目录（keyboards/archerkeyboard/）；
• desire65—— 键盘型号；
• default—— 目标键位（keymaps/default）。

构建产物通常是.uf2文件（RP2040 主控的刷写格式），生成于构建目录中。若需要自定义键位，可仿照 默认键位 新建keymaps/<你的名字>/keymap.c，然后执行make archerkeyboard/desire65:<你的名字>。

四、刷写固件

刷写命令与编译一致，追加:flash目标即可：

make archerkeyboard/desire65:default:flash

该命令会先编译，再通过 RP2040 引导加载程序将固件写入键盘。刷写前需要让键盘进入 Bootloader 模式（见下一节）。RP2040 的刷写流程在 QMK 中由util/与平台相关脚本支持，遵循 UF2 拖放或自动烧录机制。

五、进入 Bootloader 的三种方式

文档明确列出了三种进入刷写模式（Bootloader）的方法，这也是绝大多数 QMK 键盘通用的方式：

1. Bootmagic 复位：按住矩阵中 (0,0) 位置的按键（通常是左上角键或 Esc 键），再插入 USB 线。由于 Desire65 的features.bootmagic已开启，这一快捷方式默认可用；
2. 物理复位按钮：按住 PCB 背面靠近 MCU 的USB_BOOT按钮，然后短按 PCB 背面的RESET按钮，即可进入引导模式。这是 RP2040 板上最常见的BOOTSEL/复位组合操作；
3. 键位中的复位键码：若当前键位映射了QK_BOOT，直接按下该键即可进入 Bootloader。QK_BOOT是 QMK 标准复位键码（参见 docs/keycodes.md 中QK_BOOTLOADER/QK_BOOT条目），它等价于通过 USB 触发复位。

在 默认键位 中，Fn 层（layer 1）虽然没有直接放置QK_BOOT，但你可以轻松将其加到自己的键位中，例如：

[1] = LAYOUT_65_ansi_blocker_tsangan_split_bs( ..., QK_BOOT, // 放在任意空位即可 ... ),

六、默认键位剖析

默认键位 定义了完整的两层按键布局，使用LAYOUT_65_ansi_blocker_tsangan_split_bs配列宏：

• Layer 0（主层）：标准 65% ANSI 布局，包含 Esc、数字行、QWERTY 字母区、Caps Lock、Shift、Ctrl/Win/Alt 修饰键，以及KC_HOME、KC_END、KC_PGUP、KC_PGDN和独立方向键。空格右侧将右 Alt 位置替换为MO(1)，即按住该键进入 Fn 层；
• Layer 1（Fn 层）：数字行对应KC_F1～KC_F12，KC_GRV提供反引号，并映射了KC_INS、KC_PSCR、KC_CALC、KC_MPLY、KC_MPRV、KC_MNXT、KC_VOLU、KC_VOLD等媒体/功能键，KC_DEL提供删除键。该层其余按键用_______（透明）继承主层定义。

从源码结构看，MO(1)是典型的 momentary（瞬时）层切换方式：按住进入 Fn 层，松开回到主层，不需要额外的层切换状态管理。

七、配列（Layout）与社区配列复用

Desire65 在keyboard.json中声明了两种配列，并作为社区配列公开：

"community_layouts": ["65_ansi_blocker_tsangan", "65_ansi_blocker_tsangan_split_bs"]

• LAYOUT_65_ansi_blocker_tsangan：标准 65% ANSI + 右上角阻隔（blocker）+ Tsangan 底排（6.25U 空格、1.5U Ctrl/Win/Alt 组合），Backspace 为 2U；
• LAYOUT_65_ansi_blocker_tsangan_split_bs：在上述基础上把 Backspace 拆分为\与 Backspace 两个按键（split backspace）。

这两种配列同时注册在仓库的社区配列目录 layouts/community/65_ansi_blocker_tsangan 与 layouts/community/65_ansi_blocker_tsangan_split_bs 下。这意味着：任何支持相同社区配列的其他键盘，都可以直接复用为 Desire65 编写的键位文件，反之亦然——这正是 QMK 社区配列机制的跨键盘可移植性价值。

从keyboard.json的layouts定义可以看到，每个按键通过matrix: [row, col]绑定到矩阵坐标，通过x、y与w（宽度）描述物理位置，QMK 生成配列宏时会将它们转换为 C 语言中的LAYOUT_*宏供键位使用。

八、参考资料

• 键盘说明与刷写指南：keyboards/archerkeyboard/desire65/readme.md
• 数据驱动硬件配置：keyboards/archerkeyboard/desire65/keyboard.json
• 默认键位源码：keyboards/archerkeyboard/desire65/keymaps/default/keymap.c
• 社区配列定义：layouts/community/65_ansi_blocker_tsangan/readme.md
• 键码总表（含QK_BOOT）：docs/keycodes.md
• QMK 入门与构建环境：docs/newbs_getting_started.md、docs/getting_started_make_guide.md

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