QMK 固件中的 1upkeyboards pi60_hse 键盘支持：基于 RP2040 的 60% 热插拔 PCB 配置与刷写实战

QMK 固件中的 1upkeyboards pi60_hse 键盘支持：基于 RP2040 的 60% 热插拔 PCB 配置与刷写实战

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

导读

本文以 QMK Firmware 仓库中keyboards/1upkeyboards/pi60_hse

键盘目录及其 readme.md 为研究对象，系统梳理这款 60% 热插拔 PCB 的硬件特性、data-driven 配置结构、默认键位设计、编译刷写流程以及进入 Bootloader 的两种方式。读完本文，你将掌握如何基于仓库现有实现理解该键盘的矩阵与 RGB 配置、如何从零构建并刷写固件、如何自定义键位层，以及如何在仓库中追溯同类键盘的源码证据。

pi60_hse 是什么

pi60_hse 是 1up Keyboards 对初代 60% HSE（Hot Swap Edition）PCB 的更新换代产品。根据官方 readme 描述，它是一块支持多配列（multi layout）的热插拔 PCB，控制器采用 Raspberry Pi RP2040 微控制器（对应 keyboard.json 中的"processor": "RP2040"、"board": "GENERIC_RP_RP2040"

）。

主要特性包括：

• 支持分裂 Backspace（split backspace）与分裂右 Shift（split right shift）；
• 支持 6.25u 与 7u 两种空格配列；
• 热插拔轴座，免焊接更换轴体；
• 板载 WS2812 RGB 灯带（引脚 GP15，vendor 驱动），支持完整 RGB Matrix 动画；
• 10 层动态键位（dynamic_keymap layer_count = 10）。

键盘维护者为 [ziptyze]，硬件购买渠道为 1upkeyboards 官网的 pi60hse 60 PCB 页面。仓库中 1up Keyboards 品牌下的所有键盘由同一厂商支持，详见 keyboards/1upkeyboards/readme.md。

data-driven 配置结构

现代 QMK 键盘目录采用>"usb": { "device_version": "1.0.0", "pid": "0x5603", "vid": "0x6F75" }

• VID0x6F75是 1upkeyboards 的厂商 ID；
• PID0x5603是该 PCB 的专属产品 ID（同一厂商的 pi60 使用0x5604，见 pi60/keyboard.json），多个键盘共用同一 VID 时靠 PID 区分，避免操作系统混淆设备。

矩阵与二极管方向

"diode_direction": "COL2ROW", "matrix_pins": { "cols": ["GP9", "GP8", "GP6", "GP5", "GP14", "GP20", "GP13", "GP12", "GP11", "GP16", "GP17", "GP10", "GP19", "GP18"], "rows": ["GP4", "GP3", "GP2", "GP1", "GP0", "GP21"] }

• 采用 6 行 × 14 列矩阵，共 84 个矩阵交点，全部映射到 RP2040 的 GPIO 引脚；
• COL2ROW表示二极管方向为列到行，这是大多数 PCB 的常规接法；
• 矩阵交点数量大于实际按键数，多余交点用于支撑分裂 Backspace、分裂右 Shift 以及 6.25u/7u 空格等多种配列切换。

功能特性开关

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

• bootmagic：允许在插入 USB 时按住矩阵 (0,0) 键进入 Bootloader（下文详述）；
• extrakey：提供媒体键、系统电源键等扩展 HID 用法；
• mousekey：启用鼠标键（无鼠标也能用键盘模拟鼠标）；
• nkro: false：默认使用 6KRO 模式（普通 USB HID 报告），如需全键无冲可在编译时覆盖；
• rgb_matrix：启用核心 RGB 矩阵框架，配合ws2812段描述实际灯带。

WS2812 灯带与 RGB Matrix 动画

"ws2812": { "pin": "GP15", "driver": "vendor" }, "rgb_matrix": { "driver": "ws2812", "sleep": true, "animations": { ... 40+ 种动画全部为 true ... }, "layout": [ {"flags": 2, "x": 98, "y": 51}, ... ] }

• 灯带数据线接 RP2040 的 GP15，使用 vendor（RP2040 PIO）驱动；
• sleep: true表示键盘进入睡眠时自动关闭 RGB 以省电；
• animations段一次性开启了 alphas_mods、gradient、rainbow、reactive、splash、digital_rain、typing_heatmap 等 40 余种官方动画，键位层中可通过RM_*系列键码直接切换；
• layout数组用x/y坐标描述 16 颗 LED 在键位图上的物理位置，flags用于标记可参与特定效果的 LED。

动态键位与锁定支持

"dynamic_keymap": { "layer_count": 10 }, "qmk": { "locking": { "enabled": true, "resync": true } }

• 动态键位支持在运行期（配合 VIA / Vial 等工具）改写最多 10 层键位，无需重新编译固件；
• locking开启锁定键（Caps Lock 等）的指示与重同步逻辑，保证 LED 状态与真实锁定状态一致。

配列：60_ansi_split_bs_rshift

community_layouts声明为60_ansi_split_bs_rshift

，该社区配列的定义位于 layouts/community/60_ansi_split_bs_rshift/readme.md，对应的默认社区键位实现可参考 layouts/default/60_ansi_split_bs_rshift/default_60_ansi_split_bs_rshift/keymap.c。

LAYOUT_60_ansi_split_bs_rshift在keyboard.json的layouts

段中定义了 61 个物理键位（含分裂 Backspace 的额外一列），关键特征：

• 第一行末尾为BS+~两个 1u 键（分裂 Backspace）；
• 第三行右侧为 1.75u 右 Shift + 1uFN（分裂右 Shift）；
• 最底行为 6.25u 空格（"w": 6.25），该配列下空格占用matrix[5,5]；
• 每项matrix: [row, col]精确对应上面的 6×14 矩阵，例如 Esc 对应[0,0]，Enter 对应[2,13]宽度 2.25u。

关于 7u 空格：readme 声称支持 6.25u 与 7u 两种底排。仓库内该 keyboard.json 只定义了 6.25u 的LAYOUT_60_ansi_split_bs_rshift；7u 底排配列并未出现在当前仓库的layouts

定义中。因此本文仅以仓库证据确认 6.25u 配列的完整定义，7u 支持属于 PCB 硬件层面的能力描述，编译期如需使用需在本地另建配列映射。

默认键位解读

默认键位位于 keymaps/default/keymap.c，包含 3 层：

第 0 层（默认层）：标准 ANSI 60% 键位，分裂 Backspace（KC_BSPC+KC_GRV）、分裂右 Shift（KC_RSFT+MO(1)），底排为 1.25u Ctrl / Gui / Alt + 6.25u 空格 + 1.25u Alt / Gui /MO(1)/ Ctrl。右下角两个键均为MO(1)

，可左右手各持一个功能层入口。

第 1 层（功能层，MO(1)按住触发）

：

• 数字行变为 F1~F12；
• 方向键分布在W(上) /A(左) /S(下) /D(右) 附近——具体为KC_UP在W、KC_LEFT/KC_DOWN/KC_RGHT在A/S/D；
• 提供KC_PSCR/KC_SCRL/KC_PAUS（截图/滚动锁定/暂停）、KC_INS/KC_HOME/KC_PGUP、KC_END/KC_PGDN等导航键；
• 音量控制KC_VOLU/KC_VOLD/KC_MUTE；
• 右下角MO(2)作为进入第 2 层的入口。

第 2 层（RGB 控制层，MO(2)按住触发）：集中了 RGB Matrix 控制键码（定义于 quantum/keycodes.h 附近的QK_RGB_MATRIX_*

系列）：

从源码结构看，这些RM_*键码最终在process_rgb_matrix.c中通过rgblight/rgb_matrix

状态机转换成对灯带驱动（本键盘为 WS2812 vendor 驱动）的写入操作，因此无需记忆具体实现即可在键位层直接调用。

编译固件

在完成 QMK 构建环境搭建后（官方 Newbs 指南涵盖环境与首个固件流程），为 pi60_hse 构建默认键位固件：

make 1upkeyboards/pi60_hse:default

生成的固件位于构建输出目录（build/1upkeyboards/pi60_hse/下的*.uf2

文件，RP2040 平台产物格式为 UF2）。

自定义键位时，在用户空间或本地keymaps//keymap.c中以LAYOUT_60_ansi_split_bs_rshift

宏编写键位数组，然后：

make 1upkeyboards/pi60_hse:

刷写固件

连接键盘后直接编译并刷写：

make 1upkeyboards/pi60_hse:default:flash

RP2040 的刷写流程是：先将设备以 BOOTSEL 模式挂载为 USB 大容量存储盘，然后把 UF2 固件文件拖入即可。QMK 的:flash

目标会自动完成这一步（进入 bootloader 后写入 UF2）。

进入 Bootloader 的两种方式

readme 明确给出两种进入 Bootloader 的方法：

1. Bootmagic reset：键盘断电状态下，按住矩阵 (0,0) 位置对应的键（通常是左上角 Esc 键）再插入 USB。由于keyboard.json中"bootmagic": true已启用，固件启动时会检测该键是否被按住，从而直接进入刷写模式。
2. Bootloader 按钮：按住 PCB 背面的实体按钮（BOOTSEL 按钮）再插入 USB。这是 RP2040 芯片硬件级进入 bootloader 的方式，不依赖固件状态，即使固件损坏也能用。

两种方式均会将设备置于 RP2040 的 BOOTSEL 模式，之后按上文流程拖入 UF2 固件完成刷写。

进阶建议与源码追溯

• 配列调整：分裂 Backspace、分裂右 Shift 都已通过LAYOUT_60_ansi_split_bs_rshift内建；若使用普通 Backspace / 长右 Shift，可在keyboard.json中基于现有 layout 修改键位项，或在本地新增LAYOUT_60_ansi之类配列后重新编译。
• 更多底层细节：RP2040 平台支持、BOOTSEL 刷写与早期初始化参见 platformdev_rp2040.md；RGB Matrix 全量动画与配置参数参见 feature_rgb_matrix.md；键码总表参见 keycodes.md。
• 同厂商对照：pi60（keyboards/1upkeyboards/pi60）与 pi60_hse 同属 RP2040 平台的 60% 系列，pid 与矩阵引脚不同，可对照阅读以理解 QMK contenteditable="false">【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware