企业官网建设流程全解析

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_C，USB PID 为0x5368；
• Release 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.md（make 命令详解）；如果是 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 种方式：

1. Bootmagic reset（魔术键复位）：按住矩阵 (0,0) 位置的键（通常是左上角按键或 Esc 键）再插入 USB 线；
2. 物理复位按钮：按下 PCB 背面的复位按钮。Beta 版本需要持续按住至少五秒；
3. 键码触发：按下默认键位中映射了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.bin（Alpha 版，PID 对应 0x5368；Beta 版换成 0x5369）；
• QMK Toolbox：图形化工具，选择对应的*bin文件后点击 Flash 即可。

更完整的刷写流程与各平台驱动配置可参考 docs/flashing.md。如果系统提示设备未被识别，通常是缺少 DFU 驱动或未真正进入 DFU 状态，请回到上一节重新确认进入方式。

四、源码深析：Alpha 版硬件定义

alpha/keyboard.json 完整定义了 Alpha 版的硬件属性，可以逐项解读：

其中背光在 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 的全面升级：

• 处理器升级为 STM32F411，USB 设备版本为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 1；
• RGB 灯带：WS2812 可寻址灯带接 B15 引脚，共 24 颗 LED（led_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指定 PWM+DMA 输出方式；rgblight的animations段一口气启用了 breathing、rainbow_mood、rainbow_swirl、snake、knight、christmas、static_gradient、rgb_test、alternating、twinkle 共 10 种动画模式；
• EEPROM：使用 I2C 外挂 EEPROM（"driver": "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 平台级设置，一般无需修改。

六、默认键位解析：两套风格截然不同的 keymap

Alpha：功能完整的四层键位

alpha/keymaps/default/keymap.c 定义了 4 个层：_QWERTY、_LOWER、_RAISE、_ADJUST，并定义了LOWER、RAISE、ADJUST三个层切换宏（MO()瞬时层切换）。其设计是典型的 40% 键盘分层思路：

• QWERTY 层：标准字母区，空格分成左右两个KC_SPC，底部右起为方向键（Left/Down/Up/Right），LOWER、RAISE 分别位于空格两侧，方便拇指触发；
• Lower 层：数字上档符号（~!@#$%^&*()）、F1–F12、_+{}|、背光控制（BL_TOGG、BL_UP、BL_DOWN）与媒体键（Next/Vol-/Vol+/Play）；
• Raise 层：数字键与对应符号、-=[]\、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：

1. 自定义键位：复制alpha/keymaps/default/到alpha/keymaps/<你的用户名>/并修改keymap.c，键位语法参考 docs/keymap.md，高级用法（如 Mod-Tap、Tap-Hold）参考 docs/mod_tap.md；
2. 自定义 RGB 效果：Beta 版可在keyboard.json的rgblight.animations中增删动画，或通过 docs/feature_rgblight.md 了解运行时控制键码；
3. 接线与矩阵原理：想理解 COL2ROW 矩阵扫描机制，可阅读 docs/how_a_matrix_works.md 与 docs/custom_matrix.md；
4. 测试与验证：仓库的 tests/ 目录提供了 QMK 单元测试框架，可参照 docs/unit_testing.md 为自己的键位逻辑编写测试。

总结

SharkPCB 是一个展示 QMK 数据驱动配置与分层键位设计的理想范例：通过make acheron/shark/alpha:default与make acheron/shark/beta:default两条命令即可构建两代硬件固件；借助 Bootmagic、物理复位键与QK_BOOT键码三种方式进入 DFU 刷写模式；而其keyboard.json+config.h+keymap.c的目录结构，则清晰展示了现代 QMK 键盘「声明式硬件定义、命令式键位逻辑」的最佳实践。

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