基于 RP2040 的 5x12 正交键盘 Ortho60 v2QMK 固件配置、编译与刷写实战指南【免费下载链接】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.mdOrtho60 v2 是一块 5 行 × 12 列的正交键盘最大特点是由板载的RP2040 主控驱动无需外接 Pro Micro 等控制器模块。其关键信息如下项目内容键盘形态5x12 Ortholinear主控RP2040树莓派 Pi 同款双核 ARM Cortex-M0键盘维护者Andrew Kannan硬件厂商CannonKeys固件目录keyboards/cannonkeys/ortho60v2/该目录下的文件非常精简是典型的现代 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 }特性开关直接决定了固件链接哪些模块特性作用bootmagic支持 Bootmagic 复位与启动时键位覆盖extrakey支持媒体键/系统键默认键位图中的KC_MNXT、KC_VOLU等依赖此项mousekey支持鼠标键模拟nkro支持全键无冲N-Key Rolloverbacklight启用背光子系统encoder启用旋转编码器子系统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_5x12keyboard.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该命令会读取 keyboard.json生成矩阵、特性与布局定义编译 keymaps/default/keymap.c 中名为default的键位图产出适用于 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 基础层_BASEQwerty[_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 HALhalconf.h 中#define HAL_USE_PWM TRUE #include_next halconf.h通过#include_next在保留 ChibiOS 默认配置的基础上仅追加开启 PWM 抽象层。5.3mcuconf.h启用 PWM6 外设mcuconf.h 中#include_next mcuconf.h #undef RP_PWM_USE_PWM6 #define RP_PWM_USE_PWM6 TRUE在 ChibiOS 默认配置之上将 RP2040 的 PWM6 外设标记为启用。三层配置叠加后QMK 背光子系统即可通过PWMD6的 A 通道驱动GP12输出 PWM实现 15 级亮度与呼吸效果。六、进入 Bootloader 的三种方式原文档明确给出了进入刷写模式的三种方式这是 Ortho60 v2 刷机流程中最关键的操作知识Bootmagic 复位按住矩阵 (0,0) 位置按键通常是左上角第一颗键或 Esc再插入 USB 线。该行为依赖keyboard.json中启用的bootmagic特性相关键码细节可参考 keycodes_magic.md。物理复位按钮将 PCB 背面的 Boot 开关拨到 1然后按下复位按钮或在 Boot 开关处于 0 时快速双击复位按钮对应 RP2040 的双击复位进入 UF2 引导模式机制见 platformdev_rp2040.md。键位图键码按下映射为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.mdGPIO 不兼容 5VRP2040 的 GPIO 不支持 5V 容忍接线与电平转换需特别注意避免损坏主控。GPIO 命名配置中使用GPxGPIO 编号与 PCB 丝印编号并非一一对应务必以 RP2040 数据手册引脚图为准。外设复用灵活RP2040 支持 GPIO 功能复用几乎所有引脚都可挂接 I2C/SPI/UART/PWM因此 Ortho60 v2 才能将矩阵、编码器、背光同时排布在较少的引脚上。二级引导加载程序RP2040 依赖外部 SPI FlashQMK 默认按W25Q080兼容芯片提供二级 bootloaderOrtho60 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考