QMK 固件 Cata 键盘适配全解：34 键正交布局与 Waveshare RP2040-Zero 的编译、刷写与 Bootloader 指南

QMK 固件 Cata 键盘适配全解：34 键正交布局与 Waveshare RP2040-Zero 的编译、刷写与 Bootloader 指南

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

本篇技术指南以 QMK 官方仓库中keyboards/cata的键盘适配为对象，系统讲解 Cata 这款 34 键正交（ortholinear）键盘的硬件定义、默认键位映射、固件编译与刷写流程，以及进入 Bootloader 的三种标准方式。读完本文，你将掌握如何为这款基于 Waveshare RP2040-Zero 主控的键盘构建并烧录 QMK 固件，也能理解其数据驱动配置（keyboard.json）与社区布局（split_3x5_2）背后的实现细节，从而为自行修改键位或移植类似正交小配列键盘打下基础。

Cata 键盘概览：34 键正交配列与 RP2040-Zero 主控

Cata 是 skarrmann 的说明：

• 键盘维护者（Keyboard Maintainer）：skarrmann；
• 支持的硬件（Hardware Supported）：搭载 RP2040-Zero 的 Cata PCB；
• 硬件资料（Hardware Availability）：Cata 的 GitHub 仓库。

34 键的数量来自split_3x5_2社区布局的结构：左右各 3 行 × 5 列（共 30 键），再加上左右各 2 颗拇指键（共 4 键），合计 34 键。这种“类 Corne”的紧凑配列在 QMK 生态中非常流行，而 Cata 将其做成了单板一体式（monoblock）设计，且键盘本体无需自带的复位开关，完全依赖 RP2040-Zero 板载的 RESET 按钮与 Bootmagic 机制进入刷写模式。

在 QMK 仓库中，Cata 的适配由三个文件构成：

• keyboards/cata/readme.md：键盘说明文档（即本文主体）；
• keyboards/cata/keyboard.json：数据驱动的硬件定义文件；
• keyboards/cata/keymaps/default/keymap.c：默认键位映射。

整个适配不依赖手写的config.h或rules.mk，属于 QMK 现代的数据驱动配置（data-driven configuration）模式，全部硬件信息集中在keyboard.json中。

硬件定义解析：keyboard.json 中的矩阵、USB 描述符与功能开关

Cata 的硬件配置完整地定义在 keyboards/cata/keyboard.json 中，核心字段如下：

矩阵引脚定义

"matrix_pins": { "cols": ["GP9", "GP10", "GP11", "GP12", "GP13", "GP14"], "rows": ["GP27", "GP5", "GP26", "GP6", "GP15", "GP7", "GP14", "GP8"] }

从源码结构看，该矩阵为6 列 × 8 行的配置，列引脚使用GP9～GP14，行引脚使用GP27、GP5、GP26、GP6、GP15、GP7、GP14、GP8。这里值得注意的是GP14同时出现在列引脚与行引脚列表中，这是该 PCB 的实际布线方式，与常见的“行列引脚完全独立”配置不同，也印证了 Cata 采用了 8 行 × 6 列的不对称矩阵来容纳 34 键与拇指键布局。若需自行修改矩阵，需严格对照 PCB 走线，切勿照搬其他键盘的引脚映射。

启用的功能特性

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

• bootmagic：允许在插入 USB 时通过按住矩阵 (0,0) 键进入 Bootloader（详见下文“进入 Bootloader 的三种方式”）；
• extrakey：提供媒体键与系统键支持——默认键位中的KC_MUTE、KC_VOLD、KC_VOLU、KC_PSCR等正是依赖该特性；
• mousekey：启用鼠标键功能；
• nkro：N 键无冲突（N-Key Rollover），允许多键同时按下被正确识别，对游戏与快速输入场景友好。

在 QMK 中，这些特性通常由 builddefs/common_features.mk 根据features配置统一处理；Cata 仅声明了上述四项，未开启 RGB、OLED、蓝牙等额外模块，固件体积也因此保持精简。

布局结构：LAYOUT_split_3x5_2 与 34 键坐标映射

Cata 的keyboard.json中定义了一个名为LAYOUT_split_3x5_2的布局，同时声明支持社区布局split_3x5_2（参见 layouts/community/split_3x5_2/readme.md）。这意味着：

1. 默认键位映射使用LAYOUT_split_3x5_2(...)宏编写；
2. 用户也可以借助 QMK 的社区布局机制，把其他同样采用split_3x5_2配列的键盘键位复用到 Cata 上。

从布局的x/y坐标可以看到中间明显的“缝隙”：左半区第 5 列（x=4）与右半区第 1 列（x=6）之间空出x=5一列，形成分体式观感；最底行则只有左右各两颗拇指键（矩阵索引[6,3]、[6,4]、[7,0]、[7,1]）。整个布局共 34 个矩阵位置，与 Cata 的 34 键配列一一对应：

由于布局中矩阵索引与物理行列对应，(0,0)即矩阵左上角第一颗键——也就是默认键位中的KC_Q。这一点对下文 Bootmagic 复位至关重要。

默认键位映射：四层结构深度解析

默认键位定义在 keyboards/cata/keymaps/default/keymap.c 中，共划分4 个层（Layer）：

enum layer_names { _BASE, _SYMBOL, _NAVIGATION, _FUNCTION };

并通过宏定义简化层切换键的书写：

#define MO_SYM MO(_SYMBOL) #define MO_NAV MO(_NAVIGATION) #define MO_FUN MO(_FUNCTION)

MO(x)是 QMK 的“瞬时层切换（momentary）”键码：按住时临时切换到指定层，松开后自动回到底层。

底层 _BASE（QWERTY 主层）

[_BASE] = 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_QUOT, KC_Z , KC_X , KC_C , KC_V , KC_B , KC_N , KC_M , KC_COMM, KC_DOT , KC_SLSH, MO_NAV , KC_LSFT, KC_SPC , MO_SYM )

• 主键区为标准 QWERTY 字母排布，第三行右侧为'、,、.、/等常用符号键；
• 四颗拇指键被充分利用：左拇指外侧为MO_NAV（导航层瞬时切换），左拇指内侧为KC_LSFT（左 Shift），右拇指内侧为KC_SPC（空格），右拇指外侧为MO_SYM（符号层瞬时切换）。

符号层 _SYMBOL（数字与符号）

[_SYMBOL] = LAYOUT_split_3x5_2( KC_SCLN, KC_LBRC, KC_RBRC, KC_5 , XXXXXXX, XXXXXXX, KC_6 , KC_MINS, KC_EQL , KC_GRV , KC_1 , KC_2 , KC_3 , KC_4 , KC_BSLS, XXXXXXX, KC_7 , KC_8 , KC_9 , KC_0 , OS_LGUI, OS_LALT, OS_LSFT, OS_LCTL, XXXXXXX, XXXXXXX, OS_RCTL, OS_RSFT, OS_RALT, OS_RGUI, MO_FUN , _______, _______, _______ )

• 左右手各承担一半数字键：左手区为1～5，右手区为6～0；
• 中排提供;、[、]、\、-、=、`等符号；
• 最底行使用OS_LGUI、OS_LALT、OS_LSFT、OS_LCTL等一次性修饰键（One-Shot Modifier）——按下后即使松开，下一次敲击的主键仍会带上该修饰键，适合频繁使用快捷键的场景；
• XXXXXXX表示该位置没有按键功能（透明为空白键），_______表示“透传（transparent）”，沿用底层对应位置的定义；
• 左拇指位为MO_FUN，方便在符号层再叠入功能层。

导航层 _NAVIGATION（光标与编辑键）

[_NAVIGATION] = LAYOUT_split_3x5_2( KC_PSCR, KC_INS , KC_APP , KC_DEL , XXXXXXX, XXXXXXX, KC_HOME, KC_PGDN, KC_PGUP, KC_END , KC_ESC , KC_TAB , KC_ENT , KC_BSPC, XXXXXXX, XXXXXXX, KC_LEFT, KC_DOWN, KC_UP , KC_RGHT, OS_LGUI, OS_LALT, OS_LSFT, OS_LCTL, XXXXXXX, XXXXXXX, OS_RCTL, OS_RSFT, OS_RALT, OS_RGUI, _______, _______, _______, MO_FUN )

• 右手主键区集成了方向键← ↓ ↑ →，以及Home、End、PgUp、PgDn；
• 左手主键区提供Esc、Tab、Enter、Backspace、Delete、Insert、Print Screen、App等高频编辑键，便于不离开键盘完成文本编辑操作；
• 底行同样是系统修饰键的 One-Shot 版本，右侧拇指键仍保留MO_FUN。

功能层 _FUNCTION（F 键、启动与媒体控制）

[_FUNCTION] = LAYOUT_split_3x5_2( KC_F1 , KC_F2 , KC_F3 , KC_F4 , QK_BOOT, KC_SCRL, KC_F9 , KC_F10 , KC_F11 , KC_F12 , KC_F5 , KC_F6 , KC_F7 , KC_F8 , XXXXXXX, KC_CAPS, KC_MUTE, KC_VOLD, KC_VOLU, KC_PAUS, OS_LGUI, OS_LALT, OS_LSFT, OS_LCTL, XXXXXXX, KC_NUM, OS_RCTL, OS_RSFT, OS_RALT, OS_RGUI, _______, _______, _______, _______ )

• 功能层把F1～F12分布在左右手主键区；
• 左手区第 5 列（矩阵[0,4]）映射了QK_BOOT键码，按下即可让键盘重启进入 Bootloader（详见下节）；
• 右手区包含媒体控制键KC_MUTE（静音）、KC_VOLD（音量减）、KC_VOLU（音量加），以及KC_CAPS、KC_NUM、KC_SCRL、KC_PAUS等系统键——这些键码正常工作依赖keyboard.json中开启的extrakey特性。

四层之间通过拇指键的MO_SYM、MO_NAV、MO_FUN形成清晰的切换体系：底层承担打字，符号层承担数字符号，导航层承担光标编辑，功能层承担 F 键与系统控制，符合典型的分层式小配列键盘设计哲学。

编译与刷写：make cata:default 完整流程

Cata 遵循 QMK 标准的编译/刷写工作流。在完成 QMK 构建环境搭建后（构建环境与刷写工具的详细说明可参考仓库中的 docs/newbs_getting_started.md、docs/getting_started_make_guide.md 与 docs/newbs_flashing.md），在仓库根目录执行：

# 编译默认键位 make cata:default

该命令的格式为make <键盘>:<键位映射>：

• cata对应keyboards/cata目录；
• default对应keyboards/cata/keymaps/default键位映射；
• 若你拥有自定义键位目录keymaps/mine，则使用make cata:mine编译。

编译成功后即可刷写固件：

make cata:default:flash

:flash目标会先尝试让键盘进入 Bootloader，再写入固件。由于 keyboards/cata/keyboard.json 中声明了"bootloader": "rp2040"，QMK 会根据该声明选择与 RP2040 平台相匹配的刷写流程（RP2040 平台的移植说明见 docs/platformdev_rp2040.md）。刷写前请确认键盘已正确进入 Bootloader 模式（见下节），且系统已安装对应驱动或工具。

进入 Bootloader 的三种方式

Cata 原版文档明确了三种进入 Bootloader 的方式，覆盖了“无复位键也能刷写”的各种场景：

Bootmagic 复位机制的底层原理

Bootmagic 是 QMK 内置的启动特性。Cata 在 keyboards/cata/keyboard.json 中通过"bootmagic": true显式开启。根据仓库中的 docs/features/bootmagic.md，Bootmagic 的核心作用就是在键盘上电初始化阶段扫描矩阵，检测特定键是否被按住，若被按住则直接跳转进入 Bootloader——这对于没有物理复位按钮的键盘尤其有价值。

Bootmagic 在默认情况下使用的触发键就是矩阵(0,0)（多数键盘上为 Esc 键），这与 Cata 文档中“按住 (0,0) 键”的描述完全一致。若某款键盘的矩阵特殊，也可以通过定义BOOTMAGIC_ROW与BOOTMAGIC_COLUMN来指定其他触发键。

需要特别留意 Bootmagic 的一个行为特性：触发 Bootmagic 复位会同时重置 EEPROM，即键盘上通过 EEPROM 保存的各类设置（如层状态、RGB 配置等）将被清空。对于 Cata 这类未启用 EEPROM 相关特性的精简配置，影响通常可忽略，但值得了解。

物理复位键与 QK_BOOT 键码

• 物理复位键：RP2040-Zero 板载的 RESET 按钮位于开发板右侧，双击即可进入 Bootloader（这是 RP2040 系列开发板常见的启动方式），随后可以通过make cata:default:flash刷写；
• QK_BOOT 键码：默认键位在功能层将QK_BOOT映射到左手区第 5 列（keyboards/cata/keymaps/default/keymap.c 中的_FUNCTION层）。只要固件运行正常，随时按住MO_FUN再按该键，即可在系统内直接重启进 Bootloader，无需拔插 USB。QK_BOOT 同时也是 QMK 通用的启动键码（文档中常写作QK_BOOT，旧称RESET），在绝大多数 QMK 键盘上均可使用。

实战建议与延伸阅读

• 首次刷写：拿到 Cata 后建议先直接make cata:default:flash，验证三种进 Bootloader 的方式是否都可用（尤其是 Bootmagic 的 (0,0) 键触发）；
• 自定义键位：复制keyboards/cata/keymaps/default/为keyboards/cata/keymaps/<你的名字>/，修改keymap.c后执行make cata:<你的名字>；QMK 的完整键位编写指南见 docs/keymap.md；
• 复用社区布局：由于 Cata 声明支持split_3x5_2社区布局，可以尝试把其他同配列键盘的社区键位（位于 layouts/community/split_3x5_2/）直接编译到 Cata 上，相关机制参见 docs/feature_layouts.md；
• RP2040 平台细节：若关注 RP2040 在 QMK 中的移植与刷写原理，可阅读 docs/platformdev_rp2040.md；
• 深入 Bootmagic：想要自定义 Bootmagic 触发键或了解 EEPROM 重置行为，参考 docs/features/bootmagic.md。

综上，Cata 是一款结构清晰、配置精简的 34 键正交键盘适配范例：硬件信息全部收敛于keyboard.json，默认键位通过四层结构充分挖掘了 34 键的潜力，而 Bootmagic、物理复位与QK_BOOT三种进 Bootloader 的方式则保证了无论键盘处于何种状态都能可靠刷写。以此为起点，你既能快速上手 Cata 的固件构建，也能将其作为学习 QMK 数据驱动配置与小配列分层键位设计的参考模板。

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