QMK 固件编译指南CannonKeys Ortho48 —— 基于 Blue Pill STM32F103C8T6 的 12x4 正交线性键盘【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmwareOrtho48 是 CannonKeys 推出的一款 12x4 正交线性ortholinear配列键盘其核心亮点在于主控采用常见的 Blue Pill STM32F103C8T6 开发板。本文以仓库内 keyboards/cannonkeys/ortho48/readme.md 为骨架结合 keyboard.json、config.h、默认键位 keymap.c 等仓库源码系统讲解 Ortho48 的硬件定义、功能配置、默认键位设计与固件编译、烧录方法帮助你从零开始构建属于自己的 Ortho48 固件。一、Ortho48 概览从 readme 说起仓库中 Ortho48 的 readme 给出了最核心的定位信息A Blue Pill STM32F103C8T6-based 12x4 ortholinear keyboard.即这是一款基于Blue Pill STM32F103C8T6主控、采用12 列 x 4 行正交线性配列的键盘。同时 readme 明确了项目的维护关系Keyboard Maintainer固件维护者Andrew KannanHardware Supported硬件支持Blue Pill STM32F103C8T6Ortho48 是 CannonKeys 键圈keyboards/cannonkeys旗下众多配列产品之一该厂商在同一仓库中还有 ortho60、ortho75 以及基于 RP2040 的 ortho48v2 等衍生产品。需要注意v2 与 v1 是两套不同主控的独立键盘本文聚焦 v1Blue Pill 方案。二、硬件平台Blue Pill STM32F103C8T6 在 QMK 中的落地Ortho48 的 keyboard.json 中通过development_board: bluepill声明主控平台。QMK 在 data/mappings/defaults.hjson 中为bluepill定义了完整的平台映射bluepill: { board: STM32_F103_STM32DUINO, bootloader: stm32duino, processor: STM32F103 }这意味着处理器processorSTM32F103Cortex-M372MHz64KB Flash / 20KB RAM板级配置board复用 ChibiOS 的STM32_F103_STM32DUINO板定义对应源码位于 platforms/chibios/boards/STM32_F103_STM32DUINO/board/board.h其板名注释为 GENERIC STM32F103C8T6 board - stm32duino bootloader与 Blue Pill 社区通用的 stm32duino 引导方案一致引导程序bootloaderstm32duino即通过 STM32 的串口 USART1 引导模式BOOT0 拉高后经 USB-TTL 刷写进入这是 Blue Pill 最常见的免 ST-Link 刷写方式。从数据驱动的角度讲development_board字段会在编译时自动展开为 processor、board、bootloader 三项data/schemas/keyboard.jsonschema 中将其枚举为可选值之一属于 QMK 官方的标准开发板选项。三、数据驱动配置解析keyboard.json 全字段拆解Ortho48 采用 QMK 的>usb: { vid: 0xCA04, pid: 0x4F48, device_version: 0.0.1 }vid: 0xCA04为 CannonKeys 的厂商 IDpid: 0x4F48为 Ortho48 的产品 IDdevice_version: 0.0.1为设备版本号。操作系统正是通过 VID/PID 识别该键盘设备。3.2 功能开关featuresfeatures: { backlight: true, bootmagic: false, command: true, console: true, extrakey: true, mousekey: true, nkro: true, rgblight: true, sleep_led: true }backlight启用 PWM 背光配合下文 backlight 配置bootmagic关闭。意味着默认不启用“按住左上角键上电进入刷写模式”的 Bootmagic 复位需要刷写时依靠键位中的QK_BOOT或硬件复位command启用 QMK 命令行调试模式console启用调试控制台输出extrakey启用多媒体/系统键如音量、播放控制mousekey启用鼠标键功能nkro启用全键无冲N-Key Rolloverrgblight启用 RGB 灯效sleep_led启用 LED 睡眠指示。这些开关直接决定编译产物中包含哪些功能模块也影响固件体积。3.3 矩阵扫描定义matrix_pins: { cols: [B11, B10, B1, B0, A7, A6, A5, B14, A15, A0, C15, C14], rows: [B12, C13, A2, A1] }, diode_direction: COL2ROW12 个列引脚、4 个行引脚构成12x4 48 键的完整矩阵diode_direction: COL2ROW表示二极管方向为“列到行”即每个按键的二极管的阴极或阳极统一朝向行线/列线这是矩阵硬件焊接时必须与固件保持一致的关键参数焊反方向会导致整块键盘无响应或串键。3.4 背光backlight配置backlight: { pin: A8, levels: 6, breathing: true }pin: A8背光 PWM 输出引脚PA8 复用为 TIM1_CH1levels: 66 档背光亮度含关闭共 6 级breathing: true支持“呼吸”灯效。底层实现上config.h 补充了两条硬件绑定#define BACKLIGHT_PWM_DRIVER PWMD1 #define BACKLIGHT_PWM_CHANNEL 1即背光 PWM 使用 ChibiOS 的 PWM 驱动 1PWMD1、通道 1。对应的 HAL 使能位于 halconf.hHAL_USE_PWM TRUE与 mcuconf.hSTM32_PWM_USE_TIM1 TRUE两者共同把 STM32F103 的 TIM1 定时器配置为 PWM 输出源驱动 A8 引脚上的背光电路。3.5 RGB 灯效rgblight配置rgblight: { led_count: 9, 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 } }led_count: 9板上共 9 颗可寻址 RGB LEDanimations一次性开启了 10 种动画呼吸、彩虹情绪、彩虹旋涡、贪吃蛇、骑士、圣诞、静态渐变、RGB 测试、交替、闪烁编译时全部编入固件运行时通过键位的UG_NEXT等键码循环切换。3.6 WS2812 灯带驱动ws2812: { pin: B15, driver: spi }RGB LED 采用 WS2812 协议数据引脚为 PB15且使用 SPI 外设驱动而非 bit-bang 软件时序。这与 config.h 中的#define WS2812_SPI_DRIVER SPID2对应——SPI2 作为 WS2812 的数据发送器halconf.h 中的HAL_USE_SPI TRUE确保 SPI 外设可用。相比软件时序SPI 驱动 WS2812 的时序更稳定、CPU 占用更低。四、配列定义LAYOUT 与社区配列 ortho_4x12Ortho48 在 keyboard.json 中定义了两种物理配列LAYOUT_ortho_4x12标准 48 键 4x12最后一行 12 个 1U 键位LAYOUT_1x2uC最后一行中间两颗键合并为 1 颗 2U 空格见该 layout 中{matrix: [3, 5], x: 5, y: 3, w: 2}的宽度声明共 47 键。同时community_layouts: [ortho_4x12]声明 Ortho48 兼容社区标准配列ortho_4x12这意味着凡是支持该社区配列的键位方案例如 Planck、Preonic 等同类 4x12 键盘的键位都可以直接复用到 Ortho48 上极大地提升了键位方案的跨键盘可移植性。五、默认键位设计三层层级与自定义键码默认键位位于 keymaps/default/keymap.c定义了三个层与两个自定义键码#define _BASE 0 #define _RAISE 1 #define _LOWER 2 enum custom_keycodes { QWERTY SAFE_RANGE, LOWER, RAISE };5.1 基础层_BASE基础层就是标准 QWERTY 字母区 最底行功能键| Brite | Ctrl | Alt | GUI | Lower | Space(2U) | Raise | Left | Down | Up | Right |空格键使用两颗KC_SPC拼出 2U 宽度MO(_LOWER)、MO(_RAISE)为临时层切换键按住时进入 Lower/Raise 层BL_TOGG一键开关背光方向键直接放在最右下角无需组合键。5.2 Lower 层_LOWERLower 层承载符号与功能键第一行~ ! # $ % ^ * ( )第二行DelF1~F6以及_ { } |第三行F7~F12与 ISO 键位S(KC_NUHS)、S(KC_NUBS)第四行QK_BOOT进入刷写模式、KC_MNXT / KC_VOLD / KC_VOLU / KC_MPLY多媒体控制。5.3 Raise 层_RAISERaise 层与 Lower 对称承载数字行与常用符号第一行 1 2 3 4 5 6 7 8 9 0第二行DelF1~F6以及- [ ] \第三行F7~F12PgUp / PgDn第四行UG_TOGG / UG_NEXTRGB 开关与模式切换、BL_UP / BL_DOWN背光亮度调节、多媒体键。通过“空格两侧的 Raise/Lower 临时层”Ortho48 在 48 键的小配列上实现了完整数字区、符号区、F 区与多媒体控制这正是 ortholinear 小配列最典型的分层键位思路。六、固件编译与刷写6.1 编译命令readme 给出的标准编译命令为make cannonkeys/ortho48:default该命令在配置好 QMK 构建环境后执行其含义是编译keyboards/cannonkeys/ortho48键盘的default键位产物为可直接烧录的.bin固件。若想生成.hex或其他格式或指定其他键位可参考仓库内 docs/getting_started_make_guide.md 与 docs/newbs_getting_started.md 中的通用说明。6.2 进入刷写模式的方式虽然 Ortho48 关闭了 Bootmagic但固件内置了多种进入刷写bootloader的途径键位触发默认键位 Lower 层第四行第一个键就是QK_BOOT按下后 MCU 立即复位进入 stm32duino 引导程序硬件复位使用 Blue Pill 板载的复位键RST配合 BOOT0 跳线BOOT01 时上电进入串口引导这是 stm32duino bootloader 的标准流程串口工具刷写通过 USB-TTL 转接器连接 USART1PA9/PA10使用stm32flash等工具烧录编译产物注意stm32duino引导需要将固件烧写到 0x08002000 偏移处bootloader 自身占用的偏移地址QMK 的编译产物已经按此处理直接烧录即可。Ortho48 的姊妹型号 ortho48v2 采用 RP2040 主控刷写方式完全不同Bootmagic 复位、物理复位键、RESET键码三种方式且支持 USB 拖拽烧录使用前务必区分。6.3 固件体积与裁剪提示Ortho48 同时启用了 PWM 背光、SPI WS2812 RGB10 种动画以及大量 features在 STM32F103C8T6 的 64KB Flash 上是相对“丰满”的配置。若遇到空间不足readme 未展开、但 config.h 末尾保留了 QMK 标准裁剪注释/* disable debug print */ //#define NO_DEBUG /* disable print */ //#define NO_PRINT /* disable action features */ //#define NO_ACTION_LAYER //#define NO_ACTION_TAPPING //#define NO_ACTION_ONESHOT取消对应宏的注释即可关闭调试打印、动作特性等模块以压缩固件体积同理也可以在 keyboard.json 的features中关闭不需要的动画或功能如将rgblight置false这也是 QMK 数据驱动配置时代推荐的裁剪方式。七、总结Ortho48 是 QMK 仓库中一个非常典型的“Blue Pill 直插主控 正交小配列”示例readme 一句话定位Blue Pill STM32F103C8T6 驱动的 12x4 正交线性键盘维护者为 Andrew Kannan编译入口make cannonkeys/ortho48:default数据驱动配置USB 识别、矩阵引脚、背光TIM1 PWM、WS2812SPI2、9 颗 RGB LED、双配列LAYOUT_ortho_4x12/LAYOUT_1x2uC与社区配列ortho_4x12全部定义在 keyboard.json默认键位三层设计 QK_BOOT一键刷写入口键位源码见 keymaps/default/keymap.c刷写注意bootloader 为stm32duino与 ortho48v2RP2040流程完全不同。无论你是想为 Ortho48 定制键位还是想参考它在 Blue Pill 上驱动背光与 WS2812 的实现方式这个键盘目录都是一份值得直接阅读的完整范例。【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考