1. 项目概述从键盘到代码一个开源固件的诞生如果你和我一样是个对键盘手感、布局和功能有“执念”的玩家那么你肯定不止一次地想过能不能有一把完全按照自己心意打造的键盘从键位排列、灯光效果再到每一个按键的宏定义都由自己说了算。几年前这个想法实现起来门槛不低你需要懂硬件、懂焊接还得会写底层驱动。但现在情况大不一样了。今天要聊的这个项目——RJx87/Rvicii就是一个典型的例子它完美地展示了如何通过开源固件将一把普通的机械键盘变成高度可定制化的生产力工具或游戏利器。简单来说RJx87/Rvicii 是一个为特定键盘通常是87键或类似布局量身定制的QMK/VIA 兼容固件。QMK 是一个强大且流行的开源键盘固件而 VIA 是一个允许你实时配置键盘的图形化软件。这个项目的核心价值在于它为你手中的那块特定型号的 PCB印刷电路板提供了“灵魂”让你无需编写一行代码就能通过 VIA 软件轻松修改键位、设置层、配置 RGB 灯光和宏命令。对于键盘爱好者来说这相当于获得了这把键盘的终极控制权。这个项目适合谁呢首先当然是购买了对应型号套件的玩家。你拿到了套件焊好了轴体装好了键帽最后一步就是刷入固件让它“活”起来。其次是喜欢折腾、想要深入学习键盘自定义的极客。通过研究这个开源固件的代码结构你能理解 QMK 是如何工作的甚至可以为其他键盘移植固件。最后对于那些厌倦了厂商驱动臃肿、功能受限的用户转向开源固件是一种“解放”。你会发现原来键盘可以如此听话和高效。2. 核心思路与架构设计解析2.1 为什么选择 QMK 和 VIA在深入 RJx87/Rvicii 的具体内容之前我们必须先理解它构建的基石QMK 和 VIA。这不仅仅是技术选型更代表了一种键盘自定义的哲学。QMKQuantum Mechanical Keyboard是一个基于 GPL 协议的开源键盘固件。它的强大之处在于其模块化和可编程性。你可以把它想象成一个高度可配置的操作系统内核专门为键盘设计。它定义了键盘的矩阵扫描、按键处理、层切换、宏执行、RGB 控制等所有核心逻辑。开发者也就是 RJx87/Rvicii 的作者需要根据特定键盘的硬件主要是主控芯片型号和按键矩阵的电路连接方式编写对应的“驱动程序”和配置文件从而让 QMK 能够正确驱动这块 PCB。那么直接使用 QMK 不就好了吗对于终端用户来说直接面对 QMK 的代码进行配置门槛依然很高。你需要搭建编译环境修改复杂的 C 语言头文件和规则文件然后编译、刷写固件。任何一个步骤出错键盘都可能变“砖”。这时VIA的价值就凸显出来了。VIA是一个与 QMK 深度集成的图形化配置工具。它的工作原理是固件RJx87/Rvicii在编译时已经将键盘的键位映射表、可配置项等信息“预埋”了进去。当你通过 USB 连接键盘并打开 VIA 软件时软件会自动识别键盘并读取这些预埋信息动态生成一个可视化的配置界面。你可以在这个界面上通过拖拽来修改键值、设置层、配置灯光所有修改都是实时生效的无需重新编译和刷写固件。这极大地降低了自定义的门槛实现了“所见即所得”的配置体验。因此RJx87/Rvicii 项目的核心工作就是搭建一座桥梁一端是硬件的具体规格RJx87 PCB另一端是用户友好的 VIA 软件。这座桥梁就是那份符合 QMK 框架和 VIA 协议的固件源代码。2.2 项目文件结构深度解读一个典型的 RJx87/Rvicii 项目仓库其文件结构清晰地反映了 QMK 固件的组织逻辑。理解这个结构对于想要复现、修改或为其他键盘移植固件的用户至关重要。rvicii/ ├── keyboards/ │ └── rj/ │ └── rjx87/ # 针对 RJx87 键盘的专属目录 │ ├── keymaps/ │ │ ├── via/ # 用于 VIA 识别和配置的默认键位图 │ │ └── default/ # 基础的默认键位图 │ ├── config.h # 硬件配置文件引脚定义、RGB设置等 │ ├── rjx87.c # 键盘初始化、LED驱动等硬件相关代码 │ ├── rjx87.h # 头文件定义矩阵布局、引脚映射 │ └── rules.mk # 编译规则启用哪些功能如RGBLIGHT, VIA ├── readme.md # 项目说明、刷写指南 └── ... (其他可能有的通用文件)我们来拆解几个关键文件config.h这是硬件的“身份证”。里面定义了主控芯片的型号如 ATmega32U4、时钟频率、USB 描述符产品ID、厂商ID这对 VIA 识别至关重要。更重要的是它定义了按键矩阵的规模例如MATRIX_ROWS和MATRIX_COLS以及每个行列交叉点所对应的 GPIO 引脚。如果这里的引脚定义和 PCB 实际走线不符按键就会错乱甚至全部失灵。rjx87.h这里定义了键盘的物理布局。它用一个二维数组或使用 QMK 的LAYOUT宏来描述每个按键在矩阵中的位置第几行第几列。这个布局定义必须和config.h中的矩阵规模严格对应并且要和 VIA 中显示的键位图视觉布局一致。keymaps/via/keymap.c这是 VIA 功能的“入口”。它不仅仅是一个键位映射表。在它的最开头通常会通过VIA_EEPROM_CONFIG_AVAILABLE等宏定义声明此键盘支持 VIA 的实时配置。它的键位表是 VIA 软件读取的初始模板。当你通过 VIA 修改键位后新的映射关系会保存在键盘的 EEPROM一种断电不丢失的存储器中而不是修改这个源文件。rules.mk这是功能的“开关面板”。通过在这里添加或移除诸如VIA_ENABLE yes、RGBLIGHT_ENABLE yes、ENCODER_ENABLE yes等语句来告诉 QMK 的编译系统你需要为这个键盘启用哪些功能模块。RJx87/Rvicii 项目通常会在这里确保 VIA 和 RGB 背光等功能被启用。注意在尝试编译自己修改的固件前务必确认rules.mk中的功能开关与你的硬件完全匹配。例如如果你的 PCB 没有焊接 RGB LED却开启了RGBLIGHT_ENABLE编译虽能通过但刷入后可能导致电流异常或其他未定义行为。3. 从零开始环境搭建与固件编译实战知道了原理我们就要动手了。假设你拿到了一块 RJx87 的 PCB并且已经完成了焊接接下来就是让它运行起 RJx87/Rvicii 固件。整个过程可以分为环境准备、获取源码、编译和刷写四个步骤。3.1 搭建 QMK 开发环境QMK 官方推荐使用其提供的QMK MSYSWindows或通过 Homebrew 等包管理器在 macOS/Linux 上安装 QMK CLI 工具。这里以 Windows 下的 QMK MSYS 为例因为它集成了所有必需的编译工具链如 avr-gcc, dfu-programmer和友好的命令行界面。下载与安装从 QMK 官网下载 QMK MSYS 安装包。安装过程基本是“下一步”到底它会自动设置好环境变量。打开 QMK MSYS安装完成后你会在开始菜单找到一个名为 “QMK MSYS” 的终端。所有后续命令都在这里执行。初始化 QMK第一次运行时在终端输入qmk setup。这个命令会克隆官方的 QMK Firmware 仓库到本地通常是~/qmk_firmware并安装子模块依赖。这一步耗时较长取决于网络速度。3.2 获取并放置 RJx87/Rvicii 源码QMK 的环境有了我们还需要把具体的键盘代码放进去。克隆项目使用 Git 命令克隆 RJx87/Rvicii 的仓库。你可以直接在 QMK MSYS 里操作cd ~/qmk_firmware/keyboards git clone RJx87/Rvicii 仓库的Git地址 rj这会在keyboards目录下创建一个rj文件夹里面包含了rjx87的所有源代码。这个路径结构 (qmk_firmware/keyboards/rj/rjx87) 必须严格遵守因为 QMK 的编译系统依赖这个固定的目录结构来查找键盘代码。检查依赖有些键盘项目可能会依赖一些特殊的驱动或库。查看项目根目录的readme.md或rules.mk看是否有特别说明。RJx87/Rvicii 通常基于标准 QMK所以一般不需要额外步骤。3.3 编译固件环境就绪代码到位现在可以编译了。编译命令的格式是qmk compile -kb 键盘名 -km 键映射名。对于 RJx87/Rvicii命令通常是cd ~/qmk_firmware qmk compile -kb rj/rjx87 -km via-kb rj/rjx87指定键盘路径。对应我们刚才放置源码的位置。-km via指定使用keymaps/via目录下的键位映射进行编译。执行命令后终端会开始输出大量的编译信息。如果一切顺利最后你会看到类似Linking: .build/rj_rjx87_via.elf和Creating load file for flashing: .build/rj_rjx87_via.hex的成功提示。编译生成的.hex文件就是我们要刷入键盘的固件它通常位于qmk_firmware/.build/目录下。实操心得第一次编译可能会因为网络问题下载工具链或环境配置问题失败。最常见的错误是“找不到命令”或“头文件缺失”。请确保严格按照 QMK 官方文档安装 MSYS并且qmk setup过程完整无误。如果失败尝试以管理员身份运行 QMK MSYS或者彻底删除qmk_firmware目录重新执行qmk setup。3.4 刷写固件到键盘这是最关键也最需要小心的一步。刷写固件通常需要让键盘进入Bootloader引导加载程序模式。不同主控芯片进入此模式的方法不同常见的有物理复位键PCB 上有一个标着RESET或BOOT的按钮在键盘通电状态下短按。快捷键按住键盘上的某个特定组合键如Space B再插入 USB 线。跳线短接用镊子短接 PCB 上标有BOOT或GND和RST的两个焊点。对于 RJx87 这类客制化套件最常用的方法是物理复位键。请务必查阅该套件或 RJx87/Rvicii 项目的说明文档确认正确的进入方式。进入 Bootloader 模式后键盘在操作系统中通常会被识别为一个新的 USB 设备如 “ATm32U4DFU”。此时你可以使用 QMK Toolbox一个图形化刷写工具来刷写固件。打开 QMK Toolbox在 QMK MSYS 中可以通过命令qmk toolbox打开或单独下载运行。选择固件文件在 QMK Toolbox 中点击 “Open” 按钮导航到之前编译生成的.hex文件如rj_rjx87_via.hex。选择单片机型号在 “Microcontroller” 下拉菜单中选择你的主控芯片例如ATmega32U4。自动检测确保 “Auto-Flash” 选项被勾选。连接键盘并触发 Bootloader将键盘插入电脑如果已插入则拔下重插并立即通过复位键或快捷键使其进入 Bootloader 模式。QMK Toolbox 检测到设备后会自动开始刷写过程。等待完成刷写过程中日志窗口会显示进度。完成后会显示 “Flashing complete!” 或类似信息。此时键盘可能会自动重启或者需要你手动拔插一次 USB 线。刷写成功后你的键盘就应该能正常使用了并且可以被 VIA 软件识别。4. VIA 配置实战释放键盘的全部潜能固件刷写成功只是万里长征第一步。真正的乐趣现在才开始。打开 VIA 官网下载对应你操作系统的 VIA 客户端软件。安装后打开如果键盘固件RJx87/Rvicii的 VIA 支持配置正确软件应该能自动识别出你的键盘型号并加载出对应的键位配置界面。4.1 认识 VIA 界面VIA 界面通常分为几个主要标签页Configure核心键位配置页。这里以图形化方式展示了键盘的物理布局。你可以直接点击上面的任何一个键然后从右侧庞大的列表中选择一个新的功能分配给它。这个列表几乎涵盖了所有 QMK 支持的功能普通按键、修饰键Ctrl, Alt、媒体键、鼠标键、层切换键、宏甚至是复杂的 “Tap Dance”单击/双击不同功能和 “Combo”组合键触发。Lighting如果固件启用了 RGB 功能这里可以控制灯光模式、颜色、亮度、速度等。相比许多厂商驱动QMKVIA 的灯光系统更加强大和可编程。Macros宏定义页面。你可以录制或编辑一系列按键事件包括按键按下、释放和延迟并将其绑定到某个键上。这对于游戏连招或工作效率提升有奇效。Save Load保存和加载你的完整配置。这个配置会存储在键盘的 EEPROM 里所以即使换一台电脑只要插上键盘你的自定义配置依然有效。4.2 高阶自定义技巧层的艺术QMK/VIA 的核心功能之一是“层”。你可以把层想象成键盘的“页”。默认的是第0层。你可以设置一个键如MO(1)来瞬时切换到第1层按住时激活松开返回或者用TG(1)来切换第1层的开关状态。在 VIA 的 Configure 页面你可以为每一层单独设置键位。一个经典的用法是将 Caps Lock 改成一个层切换键如LT(1, KC_CAPS)这样轻触是 Caps Lock按住则激活一个包含方向键、数字小键盘和常用符号的导航层彻底解放右手减少手部移动。宏的实用化不要只把宏用于游戏。在工作中你可以创建一个“一键登录”宏模拟输入用户名、Tab、密码、Enter。但这里有个重要注意事项出于安全考虑切勿在宏里明文存储真实的密码。一个更安全的做法是宏只输入用户名并跳转到密码框密码由你手动输入或者配合密码管理器使用。你可以创建“格式化代码”、“常用邮箱签名”、“复杂地址”等文本宏大幅提升效率。利用修饰键修饰键VIA 允许你配置复杂的修饰键行为。例如将左右 Shift 键配置成 “MT(MOD_LSFT, KC_COMM)” 和 “MT(MOD_RSFT, KC_DOT)”这样它们单独轻触时是逗号和句号按住时则是 Shift 键。这需要一些练习来适应但一旦习惯可以进一步优化键盘布局。提示在进行大幅度的键位修改前建议先在 VIA 的 “Save Load” 页面导出当前配置备份。如果改乱了或者某个键被设成了无法使用的功能比如把回车键设成了层切换导致无法确认修改你可以通过键盘上的物理复位键进入 Bootloader 模式然后重新刷写固件来恢复出厂设置即via键映射的初始状态。5. 常见问题排查与进阶调试即使按照步骤操作你也可能会遇到一些问题。这里记录了一些我在折腾 RJx87 和其他 QMK 键盘时遇到的典型情况和解决方法。5.1 VIA 无法识别键盘这是最常见的问题。请按以下顺序排查问题现象可能原因解决方案VIA 软件打开后一直显示“搜索设备...”1. 固件未正确编译 VIA 支持。2. 固件的 USB 产品/厂商 ID 与 VIA 的定义文件不匹配。3. VIA 软件版本太旧。1. 确认rules.mk中VIA_ENABLE yes。2. 检查config.h中的VENDOR_ID和PRODUCT_ID。RJx87/Rvicii 项目通常会使用一组特定的 ID。你需要确保 VIA 的keyboards.json定义文件里包含了这组 ID。有时需要手动在 VIA 的 “File - Import Keymap” 中导入项目提供的.json定义文件。3. 更新 VIA 到最新版本。键盘能打字但 VIA 不识别键盘未启用 VIA 的 “可配置” 功能或者 EEPROM 相关设置有问题。确认keymap.c中使用了正确的宏如VIA_EEPROM_CONFIG_AVAILABLE。对于某些主控可能需要在rules.mk中启用EEPROM_DRIVER。换电脑后 VIA 不识别新电脑的 VIA 软件没有该键盘的定义文件。从项目仓库找到rjx87.json之类的定义文件在 VIA 软件中通过 “File - Import Keymap” 手动导入。5.2 按键失灵或错乱如果部分按键无效或者按A出B问题通常出在硬件定义上。矩阵扫描问题这是最根本的原因。首先核对config.h中的MATRIX_ROW_PINS和MATRIX_COL_PINS数组确保每一个引脚编号都对应 PCB 原理图上实际的连接。一个引脚定义错误可能导致一整行或一整列的按键失效。二极管方向机械键盘矩阵中每个按键都串联了一个二极管用于防止“鬼键”。所有二极管的朝向必须一致通常阴极朝向行线。如果焊接反了按键也会失灵。这不是固件能解决的需要检查焊接。键位映射错误rjx87.h中的LAYOUT宏定义必须准确反映物理键位的位置。如果这里把 Enter 键定义到了矩阵的 (2,5) 位置但实际 PCB 上 Enter 键的开关是接在 (2,6) 上那么当你按 Enter 时触发的是 (2,5) 对应的键值。你需要对照 PCB 的原理图或焊接说明图来仔细核对。5.3 RGB 灯光不工作或异常完全不亮首先确认rules.mk中RGBLIGHT_ENABLE yes或RGB_MATRIX_ENABLE yes取决于灯光类型。然后检查config.h中 RGB 数据引脚RGB_DI_PIN的定义是否正确。最后检查 PCB 上 RGB LED 的焊接是否有虚焊或短路。部分不亮或颜色错乱如果是串联的 RGB LED 灯带WS2812系列一个 LED 损坏或焊接不良会导致其后的所有 LED 都无法正常工作。需要逐个排查。如果是并联的单个 LED 控制则检查对应引脚的定义。VIA 中灯光控制无响应确保在rules.mk中不仅启用了 RGB还启用了VIA_RGBLIGHT_ENABLE或相应的 VIA 灯光支持选项。同时config.h中需要正确定义 RGB LED 的数量RGBLED_NUM。5.4 进阶调试使用 QMK 控制台当问题比较复杂时可以启用 QMK 的调试功能。在rules.mk中添加CONSOLE_ENABLE yes然后重新编译刷写固件。之后你可以使用 QMK Toolbox 或串口调试工具查看键盘实时输出的调试信息包括按键按下/释放的扫描码、层切换状态等。这对于诊断复杂的按键行为如 Tap Dance 不触发非常有帮助。6. 从使用者到贡献者理解与修改固件当你熟练使用 VIA 配置你的 RJx87 后你可能会产生一些 VIA 图形界面无法满足的定制需求。例如你想实现一个“三连击”功能或者想修改底层键盘扫描的去抖逻辑。这时你就需要直接修改 QMK 固件代码了。6.1 创建你自己的键映射不建议直接修改keymaps/via目录下的文件因为那是 VIA 的基准模板。更好的做法是复制一份作为起点cd ~/qmk_firmware/keyboards/rj/rjx87/keymaps cp -r via my_custom_keymap然后你就可以在my_custom_keymap/keymap.c里大展拳脚了。你可以使用更高级的 QMK 特性比如Tap Dance让一个键根据点击次数单击、双击、长按触发不同功能。Leader Key类似 Vim 的 Leader 键按下一个前缀键后再按一系列键来触发复杂命令。自定义宏在 C 代码中编写更复杂、带条件判断的宏。 修改完成后使用qmk compile -kb rj/rjx87 -km my_custom_keymap来编译你自己的固件。6.2 为其他键盘移植固件RJx87/Rvicii 项目本身就是一个为特定 PCB 移植 QMK 的绝佳范例。如果你手头有一块没有官方 QMK 支持的 PCB你可以参考它的结构进行移植。核心工作就是创建键盘目录在qmk_firmware/keyboards/下建立合适的品牌/型号目录结构。编写硬件定义文件根据 PCB 原理图编写正确的config.h引脚定义、keyboard.c/h矩阵定义、初始化代码。编写默认键映射至少创建一个default键映射。添加 VIA 支持可选创建via键映射并确保rules.mk和config.h中的相关设置正确以便生成能被 VIA 识别的固件。这个过程需要对硬件和 QMK 框架有较深的理解但成功后的成就感是无与伦比的。RJx87/Rvicii 的代码清晰简洁是学习移植的很好参考。折腾一把客制化键盘从焊接硬件到刷写、配置固件整个过程就像完成一个精致的数字手工艺品。RJx87/Rvicii 这样的开源固件项目极大地降低了软件部分的门槛让我们能将注意力更多地集中在布局设计和使用体验上。它不仅仅是一个固件更是一个社区和生态的体现。当你通过 VIA 轻松拖拽出一个完美契合自己工作流的布局时当你通过修改一行代码实现一个奇思妙想的功能时你会真正感受到“工具为人服务”的乐趣。这种深度定制带来的效率提升和身心愉悦是任何量产键盘都无法给予的。