企业官网建设流程全解析

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_firmware

Ortho48 是 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 Kannan
• Hardware Supported（硬件支持）：Blue Pill STM32F103C8T6

Ortho48 是 CannonKeys 键圈（keyboards/cannonkeys）旗下众多配列产品之一，该厂商在同一仓库中还有 ortho60、ortho75 以及基于 RP2040 的 ortho48v2 等衍生产品。需要注意：v2 与 v1 是两套不同主控的独立键盘，本文聚焦 v1（Blue 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" }

这意味着：

• 处理器（processor）：STM32F103（Cortex-M3，72MHz，64KB 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 引导方案一致；
• 引导程序（bootloader）：stm32duino，即通过 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 的厂商 ID；
• pid: 0x4F48为 Ortho48 的产品 ID；
• device_version: 0.0.1为设备版本号。

操作系统正是通过 VID/PID 识别该键盘设备。

3.2 功能开关（features）

"features": { "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 Rollover）；
• rgblight：启用 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": "COL2ROW"

• 12 个列引脚、4 个行引脚，构成12x4 = 48 键的完整矩阵；
• diode_direction: "COL2ROW"表示二极管方向为“列到行”，即每个按键的二极管的阴极（或阳极）统一朝向行线/列线，这是矩阵硬件焊接时必须与固件保持一致的关键参数，焊反方向会导致整块键盘无响应或串键。

3.4 背光（backlight）配置

"backlight": { "pin": "A8", "levels": 6, "breathing": true }

• pin: "A8"：背光 PWM 输出引脚（PA8 复用为 TIM1_CH1）；
• levels: 6：6 档背光亮度（含关闭共 6 级）；
• breathing: true：支持“呼吸”灯效。

底层实现上，config.h 补充了两条硬件绑定：

#define BACKLIGHT_PWM_DRIVER PWMD1 #define BACKLIGHT_PWM_CHANNEL 1

即背光 PWM 使用 ChibiOS 的 PWM 驱动 1（PWMD1）、通道 1。对应的 HAL 使能位于 halconf.h（HAL_USE_PWM TRUE）与 mcuconf.h（STM32_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 LED；
• animations：一次性开启了 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_4x12

Ortho48 在 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 层（_LOWER）

Lower 层承载符号与功能键：

• 第一行：~ ! @ # $ % ^ & * ( )；
• 第二行：Del+F1~F6，以及_ + { } |；
• 第三行：F7~F12与 ISO 键位（S(KC_NUHS)、S(KC_NUBS)）；
• 第四行：QK_BOOT（进入刷写模式）、KC_MNXT / KC_VOLD / KC_VOLU / KC_MPLY（多媒体控制）。

5.3 Raise 层（_RAISE）

Raise 层与 Lower 对称，承载数字行与常用符号：

• 第一行：` 1 2 3 4 5 6 7 8 9 0；
• 第二行：Del+F1~F6，以及- = [ ] \；
• 第三行：F7~F12+PgUp / PgDn；
• 第四行：UG_TOGG / UG_NEXT（RGB 开关与模式切换）、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）的途径：

1. 键位触发：默认键位 Lower 层第四行第一个键就是QK_BOOT，按下后 MCU 立即复位进入 stm32duino 引导程序；
2. 硬件复位：使用 Blue Pill 板载的复位键（RST）配合 BOOT0 跳线（BOOT0=1 时上电进入串口引导），这是 stm32duino bootloader 的标准流程；
3. 串口工具刷写：通过 USB-TTL 转接器连接 USART1（PA9/PA10），使用stm32flash等工具烧录编译产物，注意stm32duino引导需要将固件烧写到 0x08002000 偏移处（bootloader 自身占用的偏移地址），QMK 的编译产物已经按此处理，直接烧录即可。

Ortho48 的姊妹型号 ortho48v2 采用 RP2040 主控，刷写方式完全不同（Bootmagic 复位、物理复位键、RESET键码三种方式，且支持 USB 拖拽烧录），使用前务必区分。

6.3 固件体积与裁剪提示

Ortho48 同时启用了 PWM 背光、SPI WS2812 RGB（10 种动画）以及大量 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）、WS2812（SPI2）、9 颗 RGB LED、双配列（LAYOUT_ortho_4x12/LAYOUT_1x2uC）与社区配列ortho_4x12全部定义在 keyboard.json；
• 默认键位：三层设计 +QK_BOOT一键刷写入口，键位源码见 keymaps/default/keymap.c；
• 刷写注意：bootloader 为stm32duino，与 ortho48v2（RP2040）流程完全不同。

无论你是想为 Ortho48 定制键位，还是想参考它在 Blue Pill 上驱动背光与 WS2812 的实现方式，这个键盘目录都是一份值得直接阅读的完整范例。

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