基于 Blue Pill STM32F103 的 Ortho60 正交线性键盘：QMK 固件配置与编译指南-平芜编程栈

基于 Blue Pill STM32F103 的 Ortho60 正交线性键盘：QMK 固件配置与编译指南

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

Ortho60 是 CannonKeys 出品、基于 STM32F103C8T6 Blue Pill 开发板的 12 列 × 5 行正交线性（Ortholinear）键盘。本文以该键盘在 QMK 固件仓库中的官方文档为主线，结合其 keyboard.json、config.h、默认键位等源码与配置，系统讲解硬件构成、数据驱动配置、默认键位设计，以及从编译到刷写固件的完整流程。读完本文，你将掌握 Ortho60 固件的构建命令、核心配置项含义，并具备自定义键位并重新编译固件的能力。

Ortho60 硬件概况与仓库中的工程结构

Ortho60 的核心硬件信息记录在其readme.md中：

键盘形态：12 列 × 5 行的正交线性布局（12x5 ortholinear keyboard），共 60 个键位，与经典的 60% 配列按键数量相当，但采用整齐的网格排布。
主控：Blue Pill STM32F103C8T6，这是一块基于 ARM Cortex-M3 内核的常见开发板，属于 QMK 的 ARM 支持家族。
维护者：Andrew Kannan（GitHub 用户名 awkannan1）。
支持的硬件：Blue Pill STM32F103C8T6。

在 QMK 仓库中，Ortho60 的完整工程位于keyboards/cannonkeys/ortho60/，由以下文件组成：

文件	作用
keyboard.json	数据驱动的键盘配置主体（矩阵引脚、USB 描述符、布局、背光/RGB 参数）
config.h	补充的 C 宏配置（PWM 背光、WS2812 SPI 驱动、特性裁剪）
halconf.h	ChibiOS HAL 层配置（启用 PWM 与 SPI 外设）
mcuconf.h	STM32 MCU 级配置（启用 TIM1 PWM）
keymaps/default/keymap.c	默认三层键位映射
readme.md	键盘官方说明文档

可以看到，Ortho60 完全采用 QMK 的“数据驱动配置（Data Driven Configuration）”模式，keyboard.json是配置的主战场，而config.h只保留少量无法用 JSON 表达的底层驱动细节。在 QMK 中，info.json（即本键盘的keyboard.json）会在编译时与config.h、rules.mk合并，动态生成固件所需的全部配置，同时它也是 QMK Configurator 等工具展示键盘的元数据来源，其字段规则由 data/schemas/keyboard.jsonschema 约束，详见 reference_info_json.md。

矩阵与布局：12×5 正交配列的底层实现

矩阵引脚与二极管方向

keyboard.json中定义了矩阵扫描所需的全部引脚：

"matrix_pins": { "cols": ["B11", "B10", "B1", "B0", "A7", "A6", "A5", "A4", "A3", "A2", "A1", "A0"], "rows": ["B3", "B4", "B5", "B6", "B7"] }, "diode_direction": "COL2ROW"

12 个列引脚与 5 个行引脚正好构成 12 × 5 = 60 个交叉点，每个交叉点对应一个按键；
diode_direction为COL2ROW，表示二极管方向为“列到行”，这是最常用的接法；
这些引脚直接映射到 STM32F103C8T6 的 GPIO（如 PA0~PA7、PB0、PB1、PB3~PB7、PB10、PB11）。

布局定义与社区布局

keyboard.json同时声明了两种布局：

LAYOUT_ortho_5x12：标准的 12×5 全网格布局，60 键全部按 1U 排列；
LAYOUT_1x2uC：将底部中央两个 1U 键位合并为 1 个 2U 空格（通过"w": 2宽度字段实现），即“1×2U 居中空格”的变体配列，适合习惯传统空格键长度的用户。

此外，键盘声明了"community_layouts": ["ortho_5x12"]，意味着它支持 QMK 社区共享的ortho_5x12布局——你可以直接复用其他同样采用该社区布局的键盘的键位方案，无需重复定义矩阵到物理键位的映射。

从矩阵与布局的对应关系看，默认键位中使用的LAYOUT_ortho_5x12(...)宏正是由keyboard.json中的布局定义在编译期生成的，这正是 QMK 数据驱动配置的核心工作方式。

外设配置：背光、RGB 灯带与底层驱动的协同

Ortho60 出厂自带两套灯光系统：单色 PWM 背光与WS2812 RGB 灯带，它们在keyboard.json、config.h、halconf.h、mcuconf.h四层文件中协同配置。

背光（Backlight）

keyboard.json中的背光配置：

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

pin：背光 PWM 输出引脚为 PA8；
levels：6 级可调亮度（BL_UP/BL_DOWN键码可循环调节）；
breathing：启用“呼吸灯”效果。

在底层，PA8 对应 STM32 的 TIM1 通道 1，因此 config.h 中指定了 PWM 驱动与通道：

#define BACKLIGHT_PWM_DRIVER PWMD1 #define BACKLIGHT_PWM_CHANNEL 1

而 halconf.h 与 mcuconf.h 分别开启了 HAL 层的 PWM 外设与 MCU 层的 TIM1：

/* halconf.h */ #define HAL_USE_PWM TRUE #define HAL_USE_SPI TRUE /* mcuconf.h */ #undef STM32_PWM_USE_TIM1 #define STM32_PWM_USE_TIM1 TRUE

这两份文件均由qmk chibios-confmigrate命令基于平台模板自动生成（文件头注释中有明确的生成命令记录），读者通常无需手动修改。

WS2812 RGB 灯带

keyboard.json中声明了 16 颗 WS2812 RGB LED 与多种动画效果：

"ws2812": { "pin": "B15", "driver": "spi" }, "rgblight": { "led_count": 16, "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为 16，与正交配列常见的 16 键位（含空格位置）或 60 键位透光方案对应，具体灯珠布局取决于 PCB 设计；
driver使用SPI 驱动而非默认的 bit-banging（GPIO 逐位模拟）方式，对应 config.h 中的#define WS2812_SPI_DRIVER SPID2——灯带数据引脚 PB15 复用为 SPI2 的 MOSI，从而由硬件 SPI 外设高速驱动灯带，减轻 CPU 负担；
上述 10 种动画全部启用，覆盖了呼吸、彩虹流动、蛇形、骑士、圣诞、静态渐变、交替闪烁等常用 QMK RGB 效果。

其他特性开关

keyboard.json的features字段还启用了若干固件特性：

"features": { "backlight": true, "bootmagic": false, "command": true, "console": true, "extrakey": true, "mousekey": true, "nkro": true, "rgblight": true, "sleep_led": true }

包括 USB 额外按键（extrakey，媒体/系统键）、鼠标键（mousekey）、6 键无冲之上的 NKRO（nkro）、调试控制台（console）、休眠 LED（sleep_led）等；bootmagic被显式关闭（避免默认键位被魔术键干扰）。另外，qmk.locking开启了锁定键支持（enabled: true）并启用状态同步（resync: true）。这些布尔开关均遵循 reference_info_json.md 中features字典的约定。

默认键位剖析：三层键位图与自定义键码

Ortho60 的默认键位位于 keymaps/default/keymap.c，采用三层设计：

_BASE（第 0 层）：标准 QWERTY 布局；
_LOWER（第 1 层）：符号与功能键层；
_RAISE（第 2 层）：数字与符号层。

文件中通过enum custom_keycodes定义了自定义键码QWERTY、LOWER、RAISE（从SAFE_RANGE开始分配），并在各层使用MO(_LOWER)、MO(_RAISE)实现按住切换层。

基础层（BASE）

基础层遵循标准 QWERTY 指法，底部行依次为：

BL_TOGG, KC_LCTL, KC_LALT, KC_LGUI, MO(_LOWER), KC_SPC, KC_SPC, MO(_RAISE), KC_LEFT, KC_DOWN, KC_UP, KC_RGHT

BL_TOGG位于最左侧，用于开关背光；
两个空格键KC_SPC分别充当 LOWER 与 RAISE 的“拇指区”边界，中间是方向键（Left/Down/Up/Right）；
LOWER / RAISE 层通过按住对应拇指键触发，形成“层内打字”的典型正交键盘交互。

LOWER 层（符号层）

按住MO(_LOWER)时进入，提供：

完整符号输入：~ ! @ # $ % ^ & * ( )，以及_ + { } |；
功能键区：F1~F12；
ISO 附加键：S(KC_NUHS)（ISO ~）与S(KC_NUBS)（ISO |）；
媒体控制：KC_MNXT（下一曲）、KC_VOLD、KC_VOLU、KC_MPLY（播放/暂停）；
左下角放置QK_BOOT（进入刷写模式，等价于旧式RESET键码），方便免开壳进入 Bootloader。

RAISE 层（数字层）

按住MO(_RAISE)时进入，提供：

数字行1 2 3 4 5 6 7 8 9 0与符号- = [ ] \；
同样包含 F1~F12 与 ISO 附加键（KC_NUHS、KC_NUBS），以及KC_PGUP/KC_PGDN翻页键；
底部行改用 RGB 与背光控制键码：UG_TOGG（RGB 开关）、UG_NEXT（RGB 效果切换）、BL_UP、BL_DOWN（背光亮度调节）。

LOWER 与 RAISE 层均以_______（透明）保留大量未定义键位，表示这些位置保持上层映射不变。整个键位文件顶部还以 ASCII 示意图注明了每一层的物理排布，方便阅读。

编译固件：命令与流程

官方推荐编译命令

readme.md中给出的编译命令为：

make cannonkeys/ortho60:default

其中cannonkeys/ortho60是键盘在keyboards/目录下的路径，default是键位名。执行后 QMK 将编译出面向 Blue Pill STM32F103C8T6 的固件镜像（通常为.bin格式，因为 ARM 平台默认输出 bin）。

使用 QMK CLI 构建

更现代的方式是使用 QMK CLI。参照 newbs_building_firmware.md 的流程，可以先用qmk config将 Ortho60 设为默认键盘，减少后续命令的重复输入：

qmk config user.keyboard=cannonkeys/ortho60 qmk config user.keymap=default

随后直接编译：

qmk compile

如果未设置默认值，或需要为多个键盘/键位构建，则显式指定：

qmk compile -kb cannonkeys/ortho60 -km default

编译成功后输出会以类似下面的内容收尾（以 QMK 官方文档中的示例为准，具体数值依目标平台而异）：

Linking: .build/cannonkeys_ortho60_default.elf [OK] Creating load file for flashing: .build/cannonkeys_ortho60_default.bin [OK]

自定义键位并重新编译

想要打造自己的键位时，复制默认键位目录开始修改：

qmk new-keymap -kb cannonkeys/ortho60

然后在生成目录（如keyboards/cannonkeys/ortho60/keymaps/<你的用户名>/keymap.c）中编辑键位。修改时注意：

保持const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS]数组结构的逗号完整，任何多余或缺失的逗号都会导致编译失败；
每层键位数必须与LAYOUT_ortho_5x12宏的 60 个参数严格对应；
可复用LAYOUT_1x2uC变体布局或社区ortho_5x12布局。

修改完成后再次运行qmk compile -kb cannonkeys/ortho60 -km <你的键位名>即可得到新固件。

刷写与进一步学习

编译产物可通过 STM32 的 DFU/串口 Bootloader 刷入 Blue Pill（默认键位中已将QK_BOOT置于 LOWER 层左下角，按下即可进入刷写模式）。完整的刷写指引参见 newbs_flashing.md。

如果你是 QMK 新手，建议按以下仓库内文档循序渐进：

构建环境搭建：getting_started_introduction.md 与 newbs_getting_started.md；
make 编译系统说明：getting_started_make_guide.md；
新手完整指南：newbs.md；
info.json全部字段参考：reference_info_json.md；
数据驱动配置设计说明：data_driven_config.md。

总结

Ortho60 是 QMK 数据驱动配置在 ARM 平台上的典型范例：keyboard.json统一定义了矩阵、布局、背光、RGB 与特性开关，config.h与 ChibiOS 的halconf.h/mcuconf.h则补充 PWM、SPI 等底层驱动细节，默认键位以 LOWER / RAISE 双层复用拇指键实现 60 键正交配列的完整功能。掌握make cannonkeys/ortho60:default（或qmk compile -kb cannonkeys/ortho60 -km default）这一构建入口，再结合本文对各配置字段的解读，你就能高效地为这块 Blue Pill 键盘定制属于自己的固件。

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

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考