QMK 固件中的 CherryB Studio CB87TKL 键盘的硬件配置、默认键位与刷写指南【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmwareCherryB Studio CB87 是 QMK 开源键盘固件仓库qmk_firmware中一款 TKLTenkeyless87 键键盘 PCB 的完整移植示例专为 CherryB Studio Freyr 外壳设计也可作为多种兼容 TKL 键盘的替换 PCB。本文以 CB87 官方文档 为主体结合仓库中的 keyboard.json 与 默认键位 keymap.c 等源码系统讲解该键盘的硬件定义、矩阵与布局机制、RGB 与背光配置、编译刷写流程以及 Bootloader 进入方式。读完本文你将掌握如何编译、刷写、定制 CB87 固件并理解 QMK 数据驱动配置Data-Driven Configuration在真实键盘上的落地方式。一、键盘概览定位与硬件支持根据官方文档CB87 是一块TKL 尺寸的 PCB最初为 CherryB Studio Freyr 键盘设计同时可以作为一些 TKL 键盘的替换 PCB 使用。其核心信息如下键盘维护者Maintainerduongaanh硬件支持Hardware SupportedCB87主控为atmega32u4硬件特性支持 ANSI / ISO 两种主流 TKL 配列详见后文布局章节在仓库目录中CB87 的完整工程位于 keyboards/cherrybstudio/cb87/包含三个文件keyboards/cherrybstudio/cb87/ ├── keymaps/ │ └── default/ │ └── keymap.c # 默认键位定义 ├── keyboard.json # 数据驱动硬件配置 └── readme.md # 官方说明文档需要说明的是CB87 属于 QMK 的**数据驱动配置Data-Driven Configuration**键盘整个硬件的定义全部收敛在keyboard.json中不再像传统键盘那样散落在config.h/rules.mk/ 矩阵 C 文件里。这种组织方式也是 QMK 近年推荐的新式结构便于用 QMK Configurator 等工具直接生成固件。二、硬件配置深度解析keyboard.jsonkeyboard.json 是 CB87 硬件的唯一事实来源下面逐块拆解其核心配置项。2.1 USB 标识usb: { vid: 0x4342, pid: 0x8787, device_version: 0.0.1 }VID0x4342对应 ASCII 字符 CBCherryBPID0x8787则呼应 CB87 型号设备版本为0.0.1。这三个字段会编译进 USB 描述符决定操作系统如何识别该设备也是刷写工具如 QMK Toolbox识别目标键盘的依据。2.2 功能开关featuresfeatures: { backlight: true, bootmagic: true, extrakey: true, mousekey: true, nkro: true, rgblight: true }CB87 固件默认启用了六项核心功能功能作用backlight按键背光支持使用 B6 引脚见下文bootmagic启动时 Magic 按键组合可快速切换键位/进入刷写模式extrakey媒体键音量、播放控制等扩展 HID 键mousekey鼠标键用键盘模拟鼠标移动与点击nkroN 键无冲突NKRO多键同按不丢键rgblight板载 RGB 灯效支持22 颗 WS2812 LED其中nkro与bootmagic分别对应 QMK 的 NKRO 配置 与 Bootmagic 机制——后者正是下文进入 Bootloader 模式第二种方法得以生效的基础。2.3 矩阵定义matrix_pins: { cols: [D5, D4, D6, D7, B4, B5, F5, C6, C7, F7], rows: [B0, B1, B2, B3, B7, D0, D1, D2, D3] }, diode_direction: COL2ROW矩阵为9 行 × 10 列即最多可挂 90 个按键位置实际使用 87 键。diode_direction: COL2ROW表示二极管阴极朝向行、阳极朝向列列扫描驱动行读取这是 PCB 布线决定的刷写自定义固件时必须与硬件保持一致否则会出现按键错位。所有引脚均为 ATmega32U4 的可用 IO与主控选型呼应。2.4 背光与 RGBbacklight: { pin: B6 }, rgblight: { saturation_steps: 8, brightness_steps: 8, led_count: 22, 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 }按键背光由B6引脚以 PWM 方式驱动对应 QMK 的 背光功能。RGB 灯效22 颗WS2812可寻址 LED 挂在E6引脚数据线上饱和度与亮度各提供 8 档步进调节RGB_SAT/-、RGB_VAI/VAD并默认启用了 10 种动画呼吸、彩虹流动、彩虹旋转、贪吃蛇、骑士大灯、圣诞、静态渐变、RGB 测试、交替闪烁与星光闪烁。这些动画与步进参数属于rgblight驱动范畴具体键码与用法可参考 QMK 的 RGB Lighting 文档注意cb87 使用的是经典的rgblight而非rgb_matrix两者驱动不同。2.5 状态指示灯indicators: { caps_lock: F0, scroll_lock: F4, on_state: 0 }Caps Lock 指示灯接F0Scroll Lock 指示灯接F4。on_state: 0表示低电平点亮引脚为 0 时 LED 亮起这在 PCB 设计中非常常见定制固件时需保持该电平逻辑与硬件一致。2.6 处理器与引导加载程序processor: atmega32u4, bootloader: atmel-dfu主控为经典的ATmega32U4自带 USB 控制器引导加载程序使用atmel-dfu。该引导加载程序对应的 DFU 设备 VID/PID 为03EB:2FF4ATm32U4DFU详见 驱动安装说明。在 Windows 上使用qmk flash或 QMK Toolbox 刷写 atmel-dfu 目标时需要确保驱动类型正确新版本 QMK Toolbox 使用 WinUSB相关历史说明可参见 ChangeLog。三、配列支持LAYOUT_all 与 ANSI / ISOCB87 在keyboard.json中定义了三种布局并对外声明了两个社区配列community_layouts: [tkl_ansi, tkl_iso]LAYOUT_all完整布局包含 ISO 回车键KC_NUHS、KC_NUBS与左 Shift 旁的KC_NUBS位置以及 1.5U 右 Shift 等非标准键位适合全部引脚可用的情况。LAYOUT_tkl_ansi标准 ANSI 配列右 Shift 为 2.25U空格行使用标准键位组合。LAYOUT_tkl_iso标准 ISO 配列回车键为高 2 行h: 2的倒 L 形键位并相应省略了部分键位位置。三种布局的关键区别可以从布局 JSON 的w宽度与h高度字段看出ANSI 版底行左起为 1.25U 1.25U 1.25U 6.25U 空格 1.25U 1.25U 1.25U 1.25UISO 版在回车上使用{matrix: [6, 3], w: 1.25, h: 2}表示这颗键横跨两行高度。选择要点如果使用 LAYOUT_all可以在同一块 PCB 上同时兼容 ANSI 与 ISO 键帽若只使用标准配列LAYOUT_tkl_ansi/LAYOUT_tkl_iso会少占用矩阵位置键位定义更直观。社区配列tkl_ansi/tkl_iso的声明也意味着该键盘可以直接在 QMK Configurator 中选择对应配列在线生成固件。四、默认键位解读default keymap默认键位 keymap.c 使用LAYOUT_all定义了 2 个图层覆盖全部 87 键图层 0默认层标准 87 键 TKL 布局第一行KC_ESC F1–F12 KC_PSCR/KC_SCRL/KC_PAUS第二行KC_GRV数字行KC_1–KC_0KC_MINS/KC_EQL/KC_BSPCKC_INS/KC_HOME/KC_PGUP第三行KC_TAB 字母区 QWERTY KC_LBRC/KC_RBRC/KC_BSLSKC_DEL/KC_END/KC_PGDN第四行KC_CAPS A–L KC_SCLN/KC_QUOT/KC_NUHSISO 反斜杠KC_ENT第五行KC_LSFTKC_NUBS Z–M 区 KC_COMM/KC_DOT/KC_SLSHKC_RSFTKC_UP第六行KC_LCTL/KC_LGUI/KC_LALT 6.25UKC_SPCKC_RALT/KC_RGUI/KC_APP/KC_RCTLKC_LEFT/KC_DOWN/KC_RGHT图层 1全部填充KC_TRNS透明意味着该层尚未定义任何功能、完全透传给默认层。这是新键盘最常见的初始状态——为后续扩展例如 Fn 层、媒体层预留了位置你可以在自定义 keymap 中按需填入KC_TRNS之外的键码。解读方法由于LAYOUT_all同时兼容 ANSI 与 ISOkeymap 中保留了KC_NUHS/KC_NUBS这类 ISO 专属键位切换键帽配列时无需修改矩阵定义只需调整键位内容。这是 CB87 作为多配列兼容 PCB在固件层的直接体现。五、编译与刷写官方文档给出的构建命令为需先完成 QMK 构建环境搭建# 编译默认键位 make cherrybstudio/cb87:default # 编译并刷写 make cherrybstudio/cb87:default:flash命令格式为make 键盘路径:键位名[:目标]其中cherrybstudio/cb87是键盘在仓库中的路径default是键位名对应 keymaps/default追加:flash目标会在编译成功后自动调用刷写工具烧录固件。使用 QMK CLIqmk compile/qmk flash时的等价写法qmk compile -kb cherrybstudio/cb87 -km default qmk flash -kb cherrybstudio/cb87 -km default关于make构建与刷写目标更完整的说明可参考 Make 指南 与 刷写文档。由于引导加载程序为 atmel-dfu刷写时设备需进入 DFU 模式见下一节Windows 用户首次使用还需按 驱动安装指南 安装正确驱动。定制键位自定义 keymap 时只需复制默认键位目录并修改keymap.c例如make cherrybstudio/cb87:mykeymap。关于键位语法与图层机制可参考 键位文档 与 图层特性文档。六、进入 Bootloader 模式官方文档提供了两种进入 BootloaderDFU 刷写模式的方法任选其一轻触复位开关按下 PCB 顶侧、空格键左侧的 Reset 复位开关Tap the Reset switch mounted on the top side of the PCB to the left of the spacebar启动时按键插入 USB 线的同时按住键盘左上角第一颗键Hold the top left key of the keyboard while connecting the USB cable。第二种方式正是依靠固件中bootmagic功能实现的Bootmagic 会在上电瞬间检测指定的 Magic 组合键从而让键盘直接进入 Bootloader 模式。这也是features中bootmagic: true的实际用途之一。进入 DFU 模式后系统会识别到 atmel-dfu 设备ATm32U4DFUVID:PID 为03EB:2FF4此时再执行make cherrybstudio/cb87:default:flash或使用 QMK Toolbox 即可完成烧录。若 Windows 下设备未被正确识别请检查 驱动安装 并将该设备驱动设为 WinUSB。七、常见问题与排查编译报错找不到键盘确认cherrybstudio/cb87路径与仓库中 keyboards/cherrybstudio/cb87/ 完全一致且已初始化 QMK 环境qmk setup。刷写后按键错乱多为矩阵定义或diode_direction与实物不符CB87 为COL2ROW请勿随意改动 keyboard.json 中的矩阵引脚顺序。RGB 灯不亮确认编译时rgblight已启用默认开启并检查ws2812.pinE6与灯珠数量led_count22是否与实际硬件一致。指示灯方向反了indicators.on_state为 0 表示低电平点亮若指示灯逻辑异常需核对on_state与 PCB 设计。Windows 刷写卡在 DFU 识别按 驱动安装指南 为03EB:2FF4安装 WinUSB 驱动。更多编译相关问题可参考 构建 FAQ。八、同系列键盘延伸阅读CB87 属于 CherryB Studio 系列仓库中同目录下还有其他成员可作为横向参考CB87RGBRGB TKL PCB热插拔/焊接双版本改用rgb_matrix驱动并支持 30 种动画配置 中可见完整的rgb_matrix布局与动画开关CB87V2CB87 的迭代版本目录中附带 matrix_diagram.md 矩阵接线图CB65 与 CB1800分别对应 65% 与 1800 配列可用于对比不同尺寸键盘的矩阵与布局组织方式。对比 CB87 与 CB87RGB 的配置可以发现CB87 使用经典的rgblight22 颗 LED而 CB87RGB 升级为rgb_matrix按矩阵位置逐键映射 RGB两者在keyboard.json中的声明方式、动画列表和布局数据结构均有明显差异——这为理解 QMK 两套 RGB 体系的区别提供了最直接的对照素材。结语CherryB Studio CB87 是理解 QMK 数据驱动键盘工程的理想样本一块主控为 ATmega32U4、采用 atmel-dfu 引导加载程序的 TKL PCB通过 keyboard.json 完整声明了 USB 标识、9×10 矩阵、ANSI/ISO 双配列、22 颗 WS2812 RGB、B6 背光与状态指示灯。结合官方文档的编译刷写命令与两种 Bootloader 进入方式开发者可以在几分钟内完成默认固件的编译与烧录在此基础上替换 keymap、调整 RGB 动画或新增图层即可将这块兼容多种 TKL 外壳的 PCB 打造成完全属于自己的键盘固件。【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考