QMK 开源固件实战AcheronProject SharkPCB 正交 40% 键盘的编译、刷写与源码解析【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware本篇技术指南以 QMK Firmware 仓库中 SharkPCB 键盘的官方文档为主体系统讲解 AcheronProject 这款开源正交 40% 键盘的 Alpha 与 Beta 两个硬件版本的固件编译命令、DFU bootloader 进入方式、刷写流程并结合仓库内keyboards/acheron/shark/目录下的keyboard.json、config.h、默认keymap.c等源码深入剖析矩阵定义、编码器、背光、RGB 与 EEPROM 等底层实现。读完本文你将能够独立完成 SharkPCB 固件的编译与刷写并理解 QMK 数据驱动配置data-driven config的完整工作方式。SharkPCB一颗 4×12 正交 40% 键盘与它的双版本设计SharkPCB 是 Gondolindrim 为 AcheronProject 设计的开源正交 40% 键盘采用 4 行 × 12 列共 48 键的正交ortholinear配列与 Preonic 等键盘处于同一键位范式。该键盘经历了两个硬件迭代Release Alpha使用 STM32F303 处理器板型为QMK_PROTON_CUSB PID 为0x5368Release Beta升级为 STM32F411 处理器USB PID 为0x5369新增了 RGB、NKRO 等能力。两个版本的固件定义位于仓库的 keyboards/acheron/shark/ 目录下其中alpha/与beta/子目录分别对应两个硬件版本而公共的 info.json 仅声明了厂商AcheronProject与 USB VID0xAC11。也就是说两个版本共享同一个 VID通过不同的 PID 加以区分。一、构建固件两条 make 命令SharkPCB 的编译非常简单进入 DFU 状态后直接使用 QMK 标准构建命令即可。需要特别注意的是由于存在 Alpha / Beta 两个硬件版本make的目标名必须写全不能省略版本段# Release Alpha make acheron/shark/alpha:default # Release Beta make acheron/shark/beta:default其中:default指定使用alpha/keymaps/default/或beta/keymaps/default/目录下的默认键位映射。构建产物为*bin格式的二进制固件文件位于构建输出目录中。在动手编译之前需要先完成 QMK 构建环境搭建可以参考仓库内的 docs/getting_started_build_tools.md环境搭建与 docs/getting_started_make_guide.mdmake 命令详解如果是 QMK 新手建议先通读 docs/newbs.md 的完整新手指南。从源码结构看alpha/与beta/均采用 QMK 的数据驱动配置方式硬件定义集中在 alpha/keyboard.json 与 beta/keyboard.json 中而config.h只保留 JSON 无法表达或需要精细控制的底层宏如 PWM 通道、DMA 流等这种「JSON 为主、C 宏为辅」的分工正是 QMK 新式键盘目录的典型组织方式。二、进入 DFU bootloader三种标准姿势SharkPCB 使用 STM32 芯片的 DFU 引导bootloader 类型为stm32-dfu见两个版本的keyboard.json。进入 DFU 状态即设备以可刷写模式枚举到 USB有 3 种方式Bootmagic reset魔术键复位按住矩阵 (0,0) 位置的键通常是左上角按键或 Esc 键再插入 USB 线物理复位按钮按下 PCB 背面的复位按钮。Beta 版本需要持续按住至少五秒键码触发按下默认键位中映射了QK_BOOT的按键。在 Alpha 默认键位中该键位于层 1即 Adjust 层的 Q 键位置。关于第 1 种方式Bootmagic 功能在两个版本的keyboard.json中均通过features: { bootmagic: true }显式开启其复位行为由 QMK 的 Bootmagic 模块实现相关机制可参考 docs/feature_bootmagic.md。值得注意的是 Alpha 与 Beta 在物理复位上的差异Alpha 只需「按一下」而 Beta 需要「长按五秒」。这是因为两个版本使用的 STM32 芯片不同F303 与 F411复位电路的触发时序存在差异刷写时务必按对应版本的说明操作。三、刷写固件dfu-util 与 QMK Toolbox构建得到*bin文件后在 DFU 状态下即可刷写。官方文档给出的方式是使用dfu-util或QMK Toolbox下载固件dfu-util命令行工具适用于 STM32 DFU 设备示例用法为dfu-util -a 0 -d 0xAC11:0x5368 -D acheron_shark_alpha_default.binAlpha 版PID 对应 0x5368Beta 版换成 0x5369QMK Toolbox图形化工具选择对应的*bin文件后点击 Flash 即可。更完整的刷写流程与各平台驱动配置可参考 docs/flashing.md。如果系统提示设备未被识别通常是缺少 DFU 驱动或未真正进入 DFU 状态请回到上一节重新确认进入方式。四、源码深析Alpha 版硬件定义alpha/keyboard.json 完整定义了 Alpha 版的硬件属性可以逐项解读配置项值说明处理器STM32F303基于 ARM Cortex-M4 的 MCU板型QMK_PROTON_CProton C 兼容板定义Bootloaderstm32-dfuSTM32 DFU 引导USB PID / 版本0x5368 / 0.0.1与公共 VID 0xAC11 组合矩阵列B1, B12, A1, A7, A5, A4, A3, A2, A0, C15, C14, C13共 12 列矩阵行B4, A15, B10, B2共 4 行二极管方向COL2ROW列到行方向扫描编码器旋转编码器引脚 B6 / B7位于矩阵之外背光引脚 B0PWM 背光布局LAYOUT_ortho_4x124×12 正交兼容社区布局其中背光在 alpha/config.h 中通过#define BACKLIGHT_PWM_DRIVER PWMD3指定使用 STM32 定时器 PWM 通道驱动。同时 alpha/rules.mk 显式声明RGBLIGHT_SUPPORTED no、AUDIO_SUPPORTED no、BACKLIGHT_SUPPORTED no即 Alpha 硬件不支持 RGB 灯与音频背光能力由 PWM 而非传统引脚驱动提供——这也是为什么文档特别标注 Alpha 版「背光、RGB 均不受支持」的原因。矩阵引脚、编码器与背光引脚这些声明在 JSON 中后QMK 构建系统会自动生成对应的矩阵扫描、编码器与背光驱动代码无需手写 C 配置这正是数据驱动配置的便利之处详细机制可参考 docs/data_driven_config.md。五、源码深析Beta 版的硬件升级beta/keyboard.json 展示了 Beta 版相比 Alpha 的全面升级处理器升级为 STM32F411USB 设备版本为0.0.2矩阵引脚重排列改为 A5, A10, C13, B9, B8, B5, B4, B3, A15, A0, A1, A2行改为 A8, B14, A4, A3仍为 COL2ROW编码器改用 C15 / C14 引脚背光增强引脚 A6支持 20 级亮度与呼吸效果levels: 20, breathing: true并在 beta/config.h 中配置为BACKLIGHT_PWM_DRIVER PWMD3、BACKLIGHT_PWM_CHANNEL 1RGB 灯带WS2812 可寻址灯带接 B15 引脚共 24 颗 LEDled_count: 24并在config.h中通过WS2812_PWM_COMPLEMENTARY_OUTPUT、WS2812_PWM_DRIVER PWMD1、WS2812_PWM_CHANNEL 3、WS2812_PWM_DMA_STREAM STM32_DMA2_STREAM5、WS2812_PWM_DMA_CHANNEL 6指定 PWMDMA 输出方式rgblight的animations段一口气启用了 breathing、rainbow_mood、rainbow_swirl、snake、knight、christmas、static_gradient、rgb_test、alternating、twinkle 共 10 种动画模式EEPROM使用 I2C 外挂 EEPROMdriver: i2c并在config.h中通过#define EEPROM_I2C_24LC256指定芯片型号为 24LC256用于持久化键位与 RGB 配置NKRO 与 Bootmagic均开启功能开关还包含 command、extrakey、mousekey 等。Beta 版还带有一个 beta/beta.c 板级源文件实现了board_init钩子将 B6、B7 两个引脚设置为输入模式void board_init(void) { gpio_set_pin_input(B6); gpio_set_pin_input(B7); }从代码结构可以推断B6 / B7 在 Beta 板上承担了需要上拉输入的功能如拨码开关或版本检测引脚在固件启动早期即完成初始化。与 Beta 配套的 beta/chconf.h、beta/halconf.h、beta/mcuconf.h 则是 ChibiOS 内核/硬件抽象层配置属于 STM32 平台级设置一般无需修改。六、默认键位解析两套风格截然不同的 keymapAlpha功能完整的四层键位alpha/keymaps/default/keymap.c 定义了 4 个层_QWERTY、_LOWER、_RAISE、_ADJUST并定义了LOWER、RAISE、ADJUST三个层切换宏MO()瞬时层切换。其设计是典型的 40% 键盘分层思路QWERTY 层标准字母区空格分成左右两个KC_SPC底部右起为方向键Left/Down/Up/RightLOWER、RAISE 分别位于空格两侧方便拇指触发Lower 层数字上档符号~!#$%^*()、F1–F12、_{}|、背光控制BL_TOGG、BL_UP、BL_DOWN与媒体键Next/Vol-/Vol/PlayRaise 层数字键与对应符号、-[]\、ISO 键位补充KC_NUHS、KC_NUBS、同样的背光与媒体控制Adjust 层Lower Raise 同时按住触发左上角 Q 键位置为QK_BOOT——这正是文档中「按 ESC 键所在位置层 1的 QK_BOOT 进入刷写模式」所指向的键底部还放了背光开关与亮度调节。Adjust 层通过update_tri_layer_state(state, _LOWER, _RAISE, _ADJUST)实现当 Lower 与 Raise 同时激活时自动切入 Adjust 层这是 QMK 社区标准的「三合一」层管理手法机制详见 docs/feature_layers.md 与 docs/custom_quantum_functions.md。Beta极简占位键位beta/keymaps/default/keymap.c 则非常简单第 0 层为基础 QWERTY 配列仅在第 4 行使用MO(1)、MO(2)切换层第 1、2、3 层全部为KC_TRNS透明键。可以推断Beta 版的默认键位只是用于验证硬件的占位固件真正的功能键位需要用户按需定制——这也意味着拿到 Beta 版后建议直接以 Alpha 的四层键位为参考编写自己的 keymap。七、定制与后续学习路径基于以上源码分析你可以按如下路径进一步定制 SharkPCB自定义键位复制alpha/keymaps/default/到alpha/keymaps/你的用户名/并修改keymap.c键位语法参考 docs/keymap.md高级用法如 Mod-Tap、Tap-Hold参考 docs/mod_tap.md自定义 RGB 效果Beta 版可在keyboard.json的rgblight.animations中增删动画或通过 docs/feature_rgblight.md 了解运行时控制键码接线与矩阵原理想理解 COL2ROW 矩阵扫描机制可阅读 docs/how_a_matrix_works.md 与 docs/custom_matrix.md测试与验证仓库的 tests/ 目录提供了 QMK 单元测试框架可参照 docs/unit_testing.md 为自己的键位逻辑编写测试。总结SharkPCB 是一个展示 QMK 数据驱动配置与分层键位设计的理想范例通过make acheron/shark/alpha:default与make acheron/shark/beta:default两条命令即可构建两代硬件固件借助 Bootmagic、物理复位键与QK_BOOT键码三种方式进入 DFU 刷写模式而其keyboard.jsonconfig.hkeymap.c的目录结构则清晰展示了现代 QMK 键盘「声明式硬件定义、命令式键位逻辑」的最佳实践。【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考