QMK 固件开发指南：CherryB.Studio CB87v2 可编程 TKL 键盘的编译、烧录与多布局配置

QMK 固件开发指南：CherryB.Studio CB87v2 可编程 TKL 键盘的编译、烧录与多布局配置

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

本篇技术指南以 QMK Firmware 仓库中的 CB87v2 键盘文档 为主体，结合其数据驱动的 keyboard.json 配置、默认键位映射 与 矩阵接线图，系统讲解这款基于 Atmega32u4 的进阶 TKL（Tenkeyless）PCB 如何搭建编译环境、编译与烧录固件、进入 Bootloader 模式，以及如何理解其丰富的可配置布局（ANSI / ISO / Tsangan / Split Space 等）。读完本文，你将掌握 CB87v2 从源码到固件的完整操作链路，并能读懂其矩阵映射与数据驱动配置的底层细节。

CB87v2 键盘概况与仓库中的证据

CB87v2 是 CherryB.Studio 推出的一款面向进阶玩家的 TKL 键盘 PCB，官方 readme 将其定位为 "An advance TKL PCB with many configurable layouts"——即一块支持多种可配置布局的进阶 TKL PCB。在 QMK 仓库中，它的相关文件全部位于 keyboards/cherrybstudio/cb87v2/ 目录下，采用 QMK 新一代的"数据驱动"（data-driven）配置方式：硬件定义全部收敛在一个 keyboard.json 文件中，不再依赖传统的config.h与rules.mk。

从配置文件的元信息可以确认以下硬件事实：

编译与烧录：两条核心命令

官方 readme 给出了本键盘的标准操作命令，前提是先完成 QMK 构建环境的搭建。对首次接触 QMK 的用户，官方文档建议先阅读 构建环境搭建指南、Make 使用指南，并建议从 Complete Newbs Guide（新手完整指南）入门。

编译默认键位固件

在仓库根目录执行：

make cherrybstudio/cb87v2:default

该命令的含义是：编译keyboards/cherrybstudio/cb87v2这个键盘目标，键位方案（keymap）使用default——即目录 keyboards/cherrybstudio/cb87v2/keymaps/default/ 下的默认键位。命令产物是可直接烧录的.hex（或.bin）固件文件。编译系统会根据 keyboard.json 中的processor、bootloader、features等字段自动选择工具链与特性开关。

编译并一键烧录

make cherrybstudio/cb87v2:default:flash

在命令末尾追加:flash即可在编译完成后自动调用烧录工具（针对atmel-dfu引导程序），将固件写入主控。烧录前需要让键盘进入 Bootloader 模式（见下一节），系统才能识别到处于 DFU 状态的设备。

进入 Bootloader 模式：两种官方方法

readme 明确列出了两种进入 Bootloader 模式（刷机模式）的方式，任选其一即可：

1. 按复位开关：PCB 背面靠近主控芯片（MCU）的位置有一颗 Reset 开关，轻按一下即可让键盘复位进入 Bootloader。
2. 键盘快捷键（Bootmagic）：在连接 USB 数据线之前，先按住键盘左上角第一颗按键（Esc 位置）不放，然后插入 USB 线，键盘同样会进入 Bootloader 模式。

第二种方式之所以可行，是因为 keyboard.json 的features中开启了"bootmagic": true。Bootmagic 是 QMK 的经典功能：上电瞬间通过按住特定按键来触发引导、切换层、交换按键等特殊行为，这里正是利用它实现"免拆机进刷机模式"。这一特性意味着即使你手边没有尖锐工具去戳复位孔，也能随时通过键位组合进入刷机状态。

数据驱动配置解析：keyboard.json 的完整结构

CB87v2 的硬件定义全部集中在一个 keyboard.json 中，这也是 QMK 数据驱动配置（Data-Driven Configuration）架构的代表作。下面逐段拆解其关键字段。

功能特性开关（features）

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

• backlight：启用传统背光（PCB 上的单色背光控制，引脚见下文）；
• bootmagic：启用 Bootmagic，支持"按住左上角键插入 USB 进入刷机模式"；
• extrakey：启用扩展按键，支持多媒体键（音量、播放等）与系统控制键；
• mousekey：启用鼠标键，可用键盘模拟鼠标指针移动与点击；
• nkro：启用 N 键无冲突（N-Key Rollover），配合 USB 全键无冲报告；
• rgblight：启用 RGB 灯效系统（WS2812 可寻址灯带，见下文）。

这些特性在编译时会通过 builddefs/common_features.mk 等构建脚本注入对应模块，用户无需再手工维护rules.mk特性列表。

矩阵扫描引脚（matrix_pins）

"matrix_pins": { "cols": ["D5", "D4", "D6", "D7", "B4", "B5", "F5", "C6", "C7", "F7"], "rows": ["B0", "B1", "B2", "B3", "B7", "D0", "D1", "D2", "D3", "F6"] }, "diode_direction": "COL2ROW"

CB87v2 使用10 列 × 10 行 = 100 个矩阵交叉点的扫描结构，足以覆盖 TKL 的 87/88 键位并预留分体空格、分体 Backspace 等额外焊点。diode_direction: "COL2ROW"表示二极管方向为"列到行"（即列输出、行读入），这是绝大多数 PCB 的标准接法，也是刷入固件前需要与实物电路核对的关键项。

背光与指示灯（backlight / indicators）

"backlight": { "pin": "B6" }, "indicators": { "caps_lock": "F0", "scroll_lock": "F4", "on_state": 0 }

• 单色背光由B6引脚驱动（PWM 调光）；
• Caps Lock 指示灯接F0，Scroll Lock 指示灯接F4；
• "on_state": 0表示指示灯为低电平点亮（即引脚输出 0 时灯亮）。依据 data/schemas/definitions.jsonschema 中bit类型的定义（取值仅为 0 或 1），该字段只能取 0 或 1，分别对应低电平有效与高电平有效两种接法。

RGB 灯效（rgblight + ws2812）

"rgblight": { "saturation_steps": 8, "brightness_steps": 8, "led_count": 24, "animations": { "breathing": true, "rainbow_mood": true, "rainbow_swirl": true, "snake": true, "knight": true, "christmas": true, "static_gradient": true, "rgb_test": true, "alternating": true, "twinkle": true } }, "ws2812": { "pin": "E6" }

• 灯带共24 颗 WS2812 可寻址 RGB LED，数据引脚为E6；
• 饱和度与亮度各有 8 档步进（saturation_steps: 8、brightness_steps: 8），即运行时通过RGB_SAT+/-、RGB_VAI/AD每按一次变化 1/8；
• 内置动画全部开启：呼吸（breathing）、彩虹情绪（rainbow_mood）、彩虹旋涡（rainbow_swirl）、贪吃蛇（snake）、骑士（knight）、圣诞（christmas）、静态渐变（static_gradient）、RGB 测试（rgb_test）、交替（alternating）、闪烁（twinkle）。

这些动画由 QMK 的 quantum/rgblight 模块在编译期按需裁剪，开启过多动画会占用更多 flash 空间，用户可根据需求在后续自定义键位中调整。

默认键位映射：LAYOUT_all 与双层结构

默认键位位于 keyboards/cherrybstudio/cb87v2/keymaps/default/keymap.c，它直接使用LAYOUT_all宏声明完整的全键位映射：

const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { [0] = LAYOUT_all( KC_ESC, KC_F1, KC_F2, KC_F3, KC_F4, KC_F5, KC_F6, KC_F7, KC_F8, KC_F9, KC_F10, KC_F11, KC_F12, KC_PSCR, KC_SCRL, KC_PAUS, KC_GRV, KC_1, KC_2, KC_3, KC_4, KC_5, KC_6, KC_7, KC_8, KC_9, KC_0, KC_MINS, KC_EQL, KC_BSPC, KC_BSPC, KC_INS, KC_HOME, KC_PGUP, KC_TAB, KC_Q, KC_W, KC_E, KC_R, KC_T, KC_Y, KC_U, KC_I, KC_O, KC_P, KC_LBRC, KC_RBRC, KC_BSLS, KC_DEL, KC_END, KC_PGDN, KC_CAPS, KC_A, KC_S, KC_D, KC_F, KC_G, KC_H, KC_J, KC_K, KC_L, KC_SCLN, KC_QUOT, KC_NUHS, KC_ENT, KC_LSFT, KC_NUBS, KC_Z, KC_X, KC_C, KC_V, KC_B, KC_N, KC_M, KC_COMM, KC_DOT, KC_SLSH, KC_RSFT, KC_RSFT, KC_UP, KC_LCTL, KC_LGUI, KC_LALT, KC_SPC, KC_SPC, KC_SPC, KC_RALT, KC_RGUI, KC_APP, KC_RCTL, KC_LEFT, KC_DOWN, KC_RIGHT ), [1] = LAYOUT_all( /* 全层 KC_TRNS，便于用户自定义 */ ), };

可以观察到几个要点：

• 第 0 层是标准 TKL 键位：主键区 + F1–F12 + Print Screen / Scroll Lock / Pause + 方向键区，空格拆分为三个物理焊点（KC_SPC× 3），Backspace 也有两个焊点（对应分体 Backspace 布局）；
• KC_NUHS（非美式 # 键）与KC_NUBS（非美式反斜杠键）的存在，表明该 PCB 同时兼容 ISO 欧式键帽的额外键位；
• 第 1 层全部为KC_TRNS（透明透传），即默认固件只有一层有效键位，第二层是为用户自定义预留的空层；
• 第 1 层保留LAYOUT_all声明意味着：即使你换了 ANSI、ISO、Tsangan 等不同布局的键帽，键位宏的物理映射仍然完整可用。

可配置布局体系：8 种 TKL 社区布局

CB87v2 最突出的卖点就是"many configurable layouts"。从 keyboard.json 的community_layouts与layouts两个字段可以看到完整的布局矩阵：

tkl_ansi tkl_ansi_split_bs_rshift tkl_ansi_tsangan tkl_ansi_tsangan_split_bs_rshift tkl_iso tkl_iso_split_bs_rshift tkl_iso_tsangan tkl_iso_tsangan_split_bs_rshift

这 8 种社区布局可以理解为三个维度的组合：

1. ANSI 与 ISO：回车键形态。ANSI 为宽回车，ISO 为倒 L 形回车，并在主键区右侧多出#（KC_NUHS）键；
2. Split Backspace / Split RShift：把标准 2U Backspace 拆成两个 1U 键（Delete 与\），把 2.75U 右 Shift 拆成 1U+1.75U 两键；
3. Tsangan / WKL：底部一排采用 1.5U Ctrl / 1U GUI / 1.5U Alt / 7U 空格 的对称布局（即 Tsangan 布局，常与无门牙的 WKL 外壳搭配）。

除此之外，keyboard.json 还内置了一个LAYOUT_all全键位宏，它是矩阵上所有焊点的"全集"（包含分体空格、分体 Backspace、ISO 额外键等全部位置），默认键位 keymap.c 正是基于它编写，从而保证任何物理按键都能被映射到。

在 matrix_diagram.md 中，维护者以 ASCII 矩阵图详细标注了每个键位对应的矩阵坐标编号（如00–92），并分别绘制了标准、分体 Backspace、ISO Enter、BAE（Backspace 分体）、Tsangan/WKL、Tsangan/WKL Split Space 等不同配列下的键位归属示意。该图对焊接排障、自定义布局坐标系核对都有直接的参考价值。

常见操作流程小结

注意事项与下一步

• 本文所有命令与配置均以当前仓库中的 CB87v2 官方文档 及 keyboard.json 为准；若在较新版本的 QMK 上操作，请留意数据驱动配置与构建工具的版本匹配关系。
• 进入 Bootmagic 刷机模式依赖固件中开启bootmagic特性；若你后续自行裁剪了 features，该快捷键将不再生效，此时请改用 Reset 开关。
• 若想编写自己的键位，可参考 QMK 官方的 键位编写指南 与 特性层指南，并将自定义键位放在keyboards/cherrybstudio/cb87v2/keymaps/<你的名字>/下，随后使用make cherrybstudio/cb87v2:<你的名字>编译。
• 布局（layouts）相关基础概念可参阅 布局特性文档；TKL 社区布局的通用 JSON 定义可对照 layouts/community 目录下的tkl系列文件。

通过上述流程，你可以从源码完整地编译、烧录 CB87v2 固件，并利用其 8 种 TKL 社区布局与LAYOUT_all全键位宏自由定制属于自己的配列与灯效。

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