基于 RP2040 的 5x12 正交键盘 Ortho60 v2：QMK 固件配置、编译与刷写实战指南

基于 RP2040 的 5x12 正交键盘 Ortho60 v2：QMK 固件配置、编译与刷写实战指南

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

本文以 QMK Firmware 仓库中的 Ortho60 v2 键盘支持目录为核心，讲解这款由 CannonKeys 出品、板载 RP2040 主控的 5x12 正交线性（Ortholinear）键盘的固件结构、数据驱动配置、默认键位图、背光 PWM 底层实现，以及三种进入 Bootloader 的方式。读完本文，你将能够从零搭建构建环境、编译并刷写 Ortho60 v2 的固件，并能依据keyboard.json与config.h等文件自行裁剪键盘功能。

一、Ortho60 v2 键盘概览

根据 readme.md，Ortho60 v2 是一块 5 行 × 12 列的正交键盘，最大特点是由板载的RP2040 主控驱动，无需外接 Pro Micro 等控制器模块。其关键信息如下：

该目录下的文件非常精简，是典型的现代 QMK 数据驱动键盘结构：

keyboards/cannonkeys/ortho60v2/ ├── keymaps/default/keymap.c # 默认键位图（三层） ├── config.h # 背光 PWM 驱动与通道配置 ├── halconf.h # 启用 ChibiOS PWM HAL ├── mcuconf.h # 启用 RP2040 PWM6 外设 ├── keyboard.json # 数据驱动配置（矩阵/特性/布局） └── readme.md # 键盘说明文档

二、数据驱动配置：keyboard.json全解析

Ortho60 v2 采用 QMK 的数据驱动配置（Data-Driven Configuration）方式，硬件描述全部集中在 keyboard.json 中，无需编写传统rules.mk与大部分config.h。逐段解读如下。

2.1 基础标识

{ "keyboard_name": "Ortho60 v2", "maintainer": "awkannan", "manufacturer": "CannonKeys", "processor": "RP2040", "bootloader": "rp2040", "usb": { "vid": "0xCA04", "pid": "0x0019", "device_version": "0.0.1" }, "url": "https://cannonkeys.com" }

• processor与bootloader声明主控型号为 RP2040，对应 QMK 的rp2040引导加载器（UF2 格式），这也决定了固件编译目标与刷写方式。
• USB VID/PID 为0xCA04:0x0019，用于系统识别该键盘设备。

2.2 矩阵与二极管方向

"diode_direction": "COL2ROW", "matrix_pins": { "cols": ["GP7", "GP6", "GP5", "GP4", "GP3", "GP2", "GP1", "GP0", "GP13", "GP24", "GP23", "GP22"], "rows": ["GP27", "GP18", "GP19", "GP25", "GP26"] }

• 12 个列引脚 + 5 个行引脚，构成 5×12 = 60 键矩阵。
• diode_direction为COL2ROW，即二极管阳极接列、阴极接行，扫描时序由 QMK 矩阵扫描逻辑决定。关于矩阵扫描原理可参考 how_a_matrix_works.md。
• 引脚统一使用 QMK 的GPx命名法，对应 RP2040 的 GPIO 编号（注意与 PCB 上丝印编号不一定一致，详见 platformdev_rp2040.md）。

2.3 启用特性

"features": { "bootmagic": true, "extrakey": true, "mousekey": true, "nkro": true, "backlight": true, "encoder": true }

特性开关直接决定了固件链接哪些模块：

2.4 旋转编码器与背光

"encoder": { "rotary": [ {"pin_a": "GP28", "pin_b": "GP29"} ] }, "backlight": { "breathing": true, "levels": 15, "pin": "GP12" }

• 板载一路旋转编码器，A/B 相分别接GP28/GP29，可在键位图中通过ENCODER_CW/ENCODER_CCW自定义旋转行为（编码器驱动实现见 drivers/encoder）。
• 背光引脚为GP12，支持呼吸效果（breathing: true）与 15 级亮度调节。

2.5 布局LAYOUT_ortho_5x12

keyboard.json中定义了唯一布局LAYOUT_ortho_5x12，为每个按键标注了矩阵坐标[row, col]与可视位置(x, y)。例如首行以`（matrix[0,0]）开头、以Del结尾，最底行则为Brite/Ctrl/Alt/Super/Lower/空格/Raise/方向键的经典正交布局。该布局名即是键位图中使用的宏名LAYOUT_ortho_5x12。

三、编译固件：从环境搭建到出固件

3.1 搭建构建环境

QMK 官方推荐使用qmk setup完成工具链、依赖与仓库克隆。全新的初学者请按照 newbs.md（完整新手指南）与 newbs_building_firmware_workflow.md（构建环境设置与工作流）操作；命令行的详细用法参见 getting_started_make_guide.md。

3.2 编译命令

在仓库根目录（本文所在工作目录即 QMK Firmware 仓库根目录）执行：

make cannonkeys/ortho60v2:default

该命令会：

1. 读取 keyboard.json，生成矩阵、特性与布局定义；
2. 编译 keymaps/default/keymap.c 中名为default的键位图；
3. 产出适用于 RP2040 的.uf2固件文件（默认位于qmk_firmware/.build/目录下）。

若要为其他键位图编译，将default替换为目标键位图目录名即可。

四、默认键位图深度解读：三层键位设计

默认键位图位于 keymaps/default/keymap.c，采用三层层叠设计，充分利用 60 键正交布局配合层切换实现全功能输入。

4.1 层与自定义键码声明

enum custom_layers { _BASE, _RAISE, _LOWER, }; enum custom_keycodes { QWERTY = SAFE_RANGE, LOWER, RAISE };

• 层名_BASE/_RAISE/_LOWER仅为可读性命名，实际层索引即枚举顺序。
• custom_keycodes中虽然声明了QWERTY、LOWER、RAISE，但默认键位图实际使用的是 QMK 内置的层切换键码MO(_LOWER)、MO(_RAISE)（按住切换），声明自定义键码仅保留了扩展空间。

4.2 基础层_BASE（Qwerty）

[_BASE] = LAYOUT_ortho_5x12( KC_GRV, KC_1, KC_2, KC_3, KC_4, KC_5, KC_6, KC_7, KC_8, KC_9, KC_0, KC_BSPC, KC_TAB, KC_Q, KC_W, KC_E, KC_R, KC_T, KC_Y, KC_U, KC_I, KC_O, KC_P, KC_DEL, KC_ESC, KC_A, KC_S, KC_D, KC_F, KC_G, KC_H, KC_J, KC_K, KC_L, KC_SCLN, KC_QUOT, KC_LSFT, KC_Z, KC_X, KC_C, KC_V, KC_B, KC_N, KC_M, KC_COMM, KC_DOT, KC_SLSH, KC_ENT, BL_TOGG, KC_LCTL, KC_LALT, KC_LGUI, MO(_LOWER), KC_SPC, KC_SPC, MO(_RAISE), KC_LEFT, KC_DOWN, KC_UP, KC_RGHT ),

• 标准 QWERTY 字母区与数字区，Backspace 与 Delete 分居首行/第二行末尾。
• 空格键拆分为左右两颗，中间夹层切换键：左空格旁为MO(_LOWER)，右空格旁为MO(_RAISE)。
• 右下角为方向键集群（KC_LEFT/DOWN/UP/RGHT）。
• 左下角BL_TOGG为背光开关（见下文背光章节）。

4.3 功能层_LOWER与_RAISE

_LOWER层聚焦符号输入与媒体控制：

[_LOWER] = LAYOUT_ortho_5x12( KC_TILD, KC_EXLM, KC_AT, KC_HASH, KC_DLR, KC_PERC, KC_CIRC, KC_AMPR, KC_ASTR, KC_LPRN, KC_RPRN, KC_BSPC, KC_TILD, KC_EXLM, KC_AT, KC_HASH, KC_DLR, KC_PERC, KC_CIRC, KC_AMPR, KC_ASTR, KC_LPRN, KC_RPRN, KC_DEL, KC_DEL, KC_F1, KC_F2, KC_F3, KC_F4, KC_F5, KC_F6, KC_UNDS, KC_PLUS, KC_LCBR, KC_RCBR, KC_PIPE, _______, KC_F7, KC_F8, KC_F9, KC_F10, KC_F11, KC_F12, S(KC_NUHS), S(KC_NUBS), KC_HOME, KC_END, _______, QK_BOOT, _______, _______, _______, _______, _______, _______, _______, KC_MNXT, KC_VOLD, KC_VOLU, KC_MPLY ),

• KC_TILD~KC_PIPE将数字键位映射为符号；KC_UNDS、KC_PLUS、KC_LCBR、KC_RCBR、KC_PIPE补齐键盘上未印出的符号。
• S(KC_NUHS)/S(KC_NUBS)为 ISO 布局用户提供~与|的移位组合。
• F1~F12 完整排布，KC_HOME/KC_END用于行首行尾。
• 左下角放置QK_BOOT（即RESET键码），按下即可直接进入刷写模式——这正是原文档所述第三种进入 Bootloader 的方式在默认键位图中的具体落点。
• 最底行右侧为媒体键KC_MNXT（下一曲）、KC_VOLD（音量减）、KC_VOLU（音量加）、KC_MPLY（播放/暂停）。

_RAISE层则侧重数字区重排与编辑键：

[_RAISE] = LAYOUT_ortho_5x12( KC_GRV, KC_1, KC_2, KC_3, KC_4, KC_5, KC_6, KC_7, KC_8, KC_9, KC_0, KC_BSPC, KC_GRV, KC_1, KC_2, KC_3, KC_4, KC_5, KC_6, KC_7, KC_8, KC_9, KC_0, KC_DEL, KC_DEL, KC_F1, KC_F2, KC_F3, KC_F4, KC_F5, KC_F6, KC_MINS, KC_EQL, KC_LBRC, KC_RBRC, KC_BSLS, _______, KC_F7, KC_F8, KC_F9, KC_F10, KC_F11, KC_F12, KC_NUHS, KC_NUBS, KC_PGUP, KC_PGDN, _______, _______, _______, BL_UP, BL_DOWN, _______, _______, _______, _______, KC_MNXT, KC_VOLD, KC_VOLU, KC_MPLY ),

• 提供-、=、[、]、\等标点，以及KC_PGUP/KC_PGDN翻页键。
• 左下角BL_UP/BL_DOWN与基础层的BL_TOGG配合，构成完整的背光调节方案。

三层配合MO()按住层切换机制（详见 feature_layers.md），使 60 键键盘可覆盖标准全尺寸键盘的全部输入能力。

五、背光 PWM 的底层实现：从 HAL 到通道

keyboard.json声明了背光引脚GP12，但 PWM 驱动如何落到 RP2040 外设上，则由目录下的三个头文件协同完成：

5.1config.h：指定 PWM 驱动与通道

config.h 中：

#define BACKLIGHT_PWM_DRIVER PWMD6 #define BACKLIGHT_PWM_CHANNEL RP2040_PWM_CHANNEL_A

将 QMK 背光 PWM 驱动绑定到 ChibiOS 的PWMD6，并指定使用该 PWM 的 A 通道（RP2040_PWM_CHANNEL_A）。

5.2halconf.h：启用 PWM HAL

halconf.h 中：

#define HAL_USE_PWM TRUE #include_next 

通过#include_next在保留 ChibiOS 默认配置的基础上，仅追加开启 PWM 抽象层。

5.3mcuconf.h：启用 PWM6 外设

mcuconf.h 中：

#include_next  #undef RP_PWM_USE_PWM6 #define RP_PWM_USE_PWM6 TRUE

在 ChibiOS 默认配置之上，将 RP2040 的 PWM6 外设标记为启用。三层配置叠加后，QMK 背光子系统即可通过PWMD6的 A 通道驱动GP12输出 PWM，实现 15 级亮度与呼吸效果。

六、进入 Bootloader 的三种方式

原文档明确给出了进入刷写模式的三种方式，这是 Ortho60 v2 刷机流程中最关键的操作知识：

1. Bootmagic 复位：按住矩阵 (0,0) 位置按键（通常是左上角第一颗键或 Esc），再插入 USB 线。该行为依赖keyboard.json中启用的bootmagic特性，相关键码细节可参考 keycodes_magic.md。
2. 物理复位按钮：将 PCB 背面的 Boot 开关拨到 "1"，然后按下复位按钮；或在 Boot 开关处于 "0" 时，快速双击复位按钮（对应 RP2040 的双击复位进入 UF2 引导模式机制，见 platformdev_rp2040.md）。
3. 键位图键码：按下映射为RESET的按键。默认键位图中，_LOWER层左下角的QK_BOOT即为此用途（见 keymaps/default/keymap.c）。

进入 Bootloader 后，RP2040 会以 USB 大容量存储（UF2）模式挂载，将编译产物.uf2文件拖入即可完成刷写；命令行用户也可使用qmk flash -kb cannonkeys/ortho60v2 -km default一键烧录，详细流程参见 newbs_flashing.md。

七、RP2040 平台注意事项

由于主控为 RP2040，使用与移植时需留意该平台特性（详见 platformdev_rp2040.md）：

• GPIO 不兼容 5V：RP2040 的 GPIO 不支持 5V 容忍，接线与电平转换需特别注意，避免损坏主控。
• GPIO 命名：配置中使用GPx（GPIO 编号），与 PCB 丝印编号并非一一对应，务必以 RP2040 数据手册引脚图为准。
• 外设复用灵活：RP2040 支持 GPIO 功能复用，几乎所有引脚都可挂接 I2C/SPI/UART/PWM，因此 Ortho60 v2 才能将矩阵、编码器、背光同时排布在较少的引脚上。
• 二级引导加载程序：RP2040 依赖外部 SPI Flash，QMK 默认按W25Q080兼容芯片提供二级 bootloader，Ortho60 v2 未在配置中覆写该项，说明其采用默认兼容的 Flash 方案。

八、总结

Ortho60 v2 是 QMK 数据驱动键盘配置的典型范例：仅凭 keyboard.json 一个文件即可完成主控、矩阵、特性、编码器、背光与布局的完整描述；配合 config.h、halconf.h、mcuconf.h 三个头文件精确控制 PWM 底层外设；默认键位图则展示了基于层的 60 键功能全覆盖方案。对开发者而言，无论是直接编译使用，还是参考其数据驱动写法移植自己的 RP2040 正交键盘，这份目录都是极佳的样板。

# 一键编译 Ortho60 v2 默认键位图 make cannonkeys/ortho60v2:default

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