企业官网建设流程全解析

QMK 固件中的 Budgy 键盘：RP2040 无二极管分体键盘的配置、编译烧录与实现原理

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

Budgy 是 QMK 官方仓库中一款极具代表性的经济型分体键盘：它只有 34 个按键、采用无二极管（diodeless）的直接矩阵设计、主控为树莓派 RP2040（Raspberry Pi Pico），整体定位是"预算（budget）"入门的 DIY 键盘。本文以 keyboards/budgy/readme.md 为核心线索，结合其 keyboard.json、config.h 与 默认键位 的仓库源码，完整讲解该键盘的硬件架构、分体通信机制、编译烧录流程与 Bootloader 进入方式，帮助读者在 QMK 中真正跑通并理解这样一款 RP2040 分体键盘的完整实现。

项目概况：34 键、无二极管、RP2040 的经济型分体键盘

根据 keyboards/budgy/readme.md 的描述，Budgy 是一把34 键、无二极管（diodeless）、基于 RP2040 的预算键盘。其关键信息如下：

• 键盘维护者（Maintainer）：KeyboardDweebs
• 支持的硬件（Hardware Supported）：Raspberry Pi Pico
• 布局规模：每只手 5 列 × 3 行共 15 个主键区按键，加上每只手 2 个拇指键，合计 34 键，对应 QMK 社区标准的split_3x5_2分体布局。

"无二极管"这一特性是 Budgy 的核心卖点。传统键盘矩阵需要为每个按键配一枚二极管来防止"鬼键"（ghosting）与"串键"（masking），而 Budgy 采用 QMK 支持的direct pins（直接矩阵）方案，即每个按键直接独占一个 GPIO 引脚，从而省去了二极管与部分矩阵扫描逻辑。从 keyboard.json 中的matrix_pins.direct配置可以看到，左右手共 8 行 × 5 列的直接引脚映射（左半部分为GP6~GP18中的 17 个引脚，右半部分镜像对称）。

硬件配置逐项解析：keyboard.json 中的数据驱动配置

QMK 支持 Data-Driven Configuration（数据驱动配置），Budgy 的全部板级信息都集中在 keyboards/budgy/keyboard.json 中，无需维护传统rules.mk与大部分config.h内容。下面逐项拆解其含义。

USB 与处理器标识

"processor": "RP2040", "bootloader": "rp2040", "usb": { "device_version": "1.0.0", "pid": "0x0117", "vid": "0xFABE" }

• processor声明主控为树莓派 RP2040 双核 Cortex-M0+ 微控制器；
• bootloader声明使用 RP2040 的 UF2 引导加载器（rp2040），编译产物为可拖拽烧录的 UF2 文件；
• usb段定义了 USB VID（0xFABE，QMK 键盘的通用厂商 ID）与 PID（0x0117）。

功能开关（features）

"features": { "bootmagic": true, "extrakey": true, "mousekey": true, "nkro": true }

• bootmagic：启用 Bootmagic（详见后文 Bootloader 章节），这也是 readme 中"按住矩阵 (0,0) 键再插入 USB 即可进入引导加载器"的依据；
• extrakey：启用多媒体/系统键支持（如音量、媒体播放键）；
• mousekey：启用鼠标键功能，可将按键映射为鼠标移动与点击；
• nkro：启用 N 键无冲突（N-Key Rollover）报告。

无二极管的直接矩阵（Direct Pins）

"matrix_pins": { "direct": [ ["GP6", "GP5", "GP4", "GP3", "GP2"], ["GP11", "GP10", "GP9", "GP8", "GP7"], ["GP15", "GP14", "GP13", "GP12", "GP16"], ["GP17", "GP18", null, null, null] ] }

这是左手半边的引脚表：行号即矩阵行索引，列中的每个元素是对应按键所直接连接的 GPIO 引脚，null表示该位置没有按键。右手半边在split.matrix_pins.right.direct中给出了镜像对称的引脚排列（如GP2、GP3等，与左手对应位置交错对应）。从矩阵结构可以推断：

• 每只手 4 行，其中前 3 行各 5 个键（主键区 15 键），第 4 行只有 2 个键（拇指键），合计每手 17 键，左右共 34 键；
• 由于是直接矩阵，每个按键的开关状态通过读取对应 GPIO 的电平直接获得，不需要行扫描/列扫描的组合逻辑，因此无需二极管；
• 需要注意的是，采用 direct pins 时按键数量直接受限于可用 GPIO 数量。RP2040 拥有丰富的引脚资源，Budgy 每手仅需 17 个 GPIO，加上左右手之间的串行通信引脚（见下文GP0/GP1），对 Pico 而言余量充足。

分体（Split）配置与左右通信

"split": { "enabled": true, "matrix_pins": { "right": { "direct": [ ... ] } }, "serial": { "driver": "vendor" } }

• split.enabled声明这是一把分体键盘；
• 右手矩阵通过split.matrix_pins.right单独定义（分体键盘的左右两半矩阵引脚通常不同，需要分开声明）；
• serial.driver指定左右手之间的串行驱动为vendor。在 RP2040 平台上，vendor对应 QMK 针对该芯片的PIO（Programmable I/O）串行驱动实现（详见 docs/drivers/serial.md）。

布局定义与社区布局

"community_layouts": ["split_3x5_2"], "layouts": { "LAYOUT_split_3x5_2": { "layout": [ {"matrix": [0, 0], "x": 0, "y": 0.25}, ... ] } }

community_layouts声明 Budgy 遵循 QMK 社区标准布局split_3x5_2（3 行 × 5 列 + 2 个拇指键的分体布局，见 layouts/community/split_3x5_2/readme.md），这意味着任何同样使用该社区布局的键位（keymap）都可以直接编译到 Budgy 上，无需修改布局宏。layouts.LAYOUT_split_3x5_2段通过matrix坐标（行、列）与物理坐标x、y的映射，把按键定义到键盘的物理位置，从坐标数据可以看到左右两半以x=4与x=8为界对称排布，符合典型的 34 键分体键盘布局。

编译与烧录：一条命令完成固件构建

readme 中给出了构建环境就绪后的两条核心命令（也可直接参考 docs/getting_started_make_guide.md）：

编译默认键位：

make budgy:default

编译并烧录：

make budgy:default:flash

命令的语义为make <键盘名>:<键位名>[:目标]：

• budgy对应键盘目录 keyboards/budgy；
• default对应默认键位 keyboards/budgy/keymaps/default/keymap.c；
• 附加:flash目标会在编译完成后自动进入烧录流程，将生成的固件写入板子。

对于 RP2040 平台，构建产物是UF2 固件镜像：将 Pico 以引导模式挂载为 U 盘后，把.uf2文件拖入即可完成烧录（无需额外刷写工具）。若你尚未搭建 QMK 构建环境，建议从 docs/newbs_getting_started.md（环境搭建与入门）和 docs/newbs.md（QMK 新手完全指南）开始。

进入 Bootloader 的三种方式

readme 明确列出了 Budgy 进入引导加载器的 3 种方式：

1. Bootmagic reset（Bootmagic 复位）：在矩阵 (0,0) 位置（通常是左上角第一个键或 Escape 键）按住不放的同时插入 USB 供电，键盘会直接进入引导模式。这一机制依赖 keyboard.json 中features.bootmagic的开启；
2. 物理复位按钮：按下 PCB 背面的复位按钮（部分版本没有按钮，而是需要短接对应的焊盘）即可进入引导模式；
3. 键位中的QK_BOOT键码：如果在键位中把某个按键映射为QK_BOOT（QMK 的复位键码，详见 docs/keycodes.md），按下该键即可触发复位进入引导加载器。

此外，Budgy 在 config.h 中还启用了 RP2040 平台的双击复位（Double-tap reset）机制：

#define RP2040_BOOTLOADER_DOUBLE_TAP_RESET #define RP2040_BOOTLOADER_DOUBLE_TAP_RESET_TIMEOUT 1000U

根据 docs/platformdev_rp2040.md 的说明，该机制允许在上电启动时快速双击复位引脚（在1000U即 1000 毫秒的超时窗口内完成两次触发）来进入 RP2040 的 UF2 引导加载器，行为与 AVR Pro Micro 类似，让没有物理开关的玩家也能方便地进入烧录模式。RP2040_BOOTLOADER_DOUBLE_TAP_RESET在 QMK 的 Generic Pro Micro RP2040 板上默认开启，Budgy 在此显式声明并自定义了超时窗口。

分体通信底层：全双工 USART 串行与 PIO 驱动

作为分体键盘，左右两半之间需要持续同步按键状态、层状态等数据。Budgy 在 config.h 中给出了具体的串行配置：

#define SERIAL_USART_FULL_DUPLEX #define SERIAL_USART_TX_PIN GP1 #define SERIAL_USART_RX_PIN GP0 // #define SERIAL_USART_PIN_SWAP

结合 docs/drivers/serial.md 的说明可以解读：

• SERIAL_USART_FULL_DUPLEX：启用全双工（Full-duplex）通信模式，使用两条独立数据线：TX发送、RX接收，一方半的TX必须接到另一半的RX（反之亦然）；
• SERIAL_USART_TX_PIN GP1/SERIAL_USART_RX_PIN GP0：指定分体通信使用的两个 GPIO 引脚；
• 被注释掉的SERIAL_USART_PIN_SWAP：是部分 MCU（如 STM32F303/Proton-C）提供的片内TX/RX交换能力。Budgy 未启用它，意味着左右交叉连接需要在 PCB 布线或连接线上完成；
• keyboard.json 中split.serial.driver设置为vendor，对应 RP2040 专属的PIO 串行驱动。PIO（Programmable I/O）是 RP2040 的特色外设，其优势在于任意 GPIO 均可作为TX/RX引脚，且内置上拉，不需要像半双工 USART 那样外接上拉电阻。

从源码结构看，Budgy 选择了 RP2040 上最灵活、配置最简洁的组合：PIO 驱动 + 全双工双线通信，兼顾了通信效率与引脚自由度。对分体键盘的握手与通信机制感兴趣的读者，可进一步阅读 docs/features/split_keyboard.md（分体键盘的硬件接线、左右手判定与数据同步选项）。

默认键位：34 键 QWERTY 布局实例

Budgy 的默认键位位于 keyboards/budgy/keymaps/default/keymap.c，使用LAYOUT_split_3x5_2宏定义了一层标准的 QWERTY 布局：

[0] = LAYOUT_split_3x5_2( KC_Q, KC_W, KC_E, KC_R, KC_T, KC_Y, KC_U, KC_I, KC_O, KC_P, KC_A, KC_S, KC_D, KC_F, KC_G, KC_H, KC_J, KC_K, KC_L, KC_SCLN, KC_Z, KC_X, KC_C, KC_V, KC_B, KC_N, KC_M, KC_COMM, KC_DOT, KC_SLSH, KC_BSPC, KC_TAB, KC_SPC, KC_ENT );

键位注释中给出了清晰的 ASCII 键位图：左右各 3 行 × 5 列的主键区（字母区），加上底部右侧的拇指键（左手拇指为 Backspace 与 Tab，右手拇指为 Space 与 Enter）。作为只有 34 键的极简键盘，字母以外的符号、数字与功能键通常需要借助层（Layer）实现——这也是split_3x5_2这类紧凑布局在 QMK 中常见的用法，读者可以仿照该文件自行添加LOWER/RAISE等功能层（层的定义与切换见 docs/feature_layers.md）。

小结

Budgy 是理解"RP2040 + 无二极管 + 分体键盘"三者结合的一个极佳范本：通过 keyboard.json 的数据驱动配置，可以在不写 C 代码的情况下完成矩阵、USB、分体与功能的声明；config.h 补充了 RP2040 双击复位与全双工 PIO 串行的底层细节；而 默认键位 展示了 34 键布局的实际写法。对希望动手制作一把经济型分体键盘、或想在 RP2040 平台上移植同类项目的开发者而言，Budgy 的整套配置都可以作为可直接复用的起点。

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