QMK 固件实战：1upkeyboards pi40（RP2040 正交 4x12 键盘）配置、编译、刷写与 OLED/旋钮/RGB 详解

QMK 固件实战：1upkeyboards pi40（RP2040 正交 4x12 键盘）配置、编译、刷写与 OLED/旋钮/RGB 详解

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

导读

pi40 是 1upkeyboards 推出的一款基于Raspberry Pi Pico（RP2040）主控的4x12 正交线性（ortholinear）键盘，采用固定的 2u 空格键布局，并以「高引脚可玩性」著称：旋转编码器、SSD1306 OLED、每键 WS2812 RGB 灯珠均可选装，未使用的 GPIO 与电压引脚全部引出到主板上供玩家自由扩展。本文以 keyboards/1upkeyboards/pi40/readme.md 为主线，结合仓库内 info.json、config.h、pi40.c 与三个 PCB 版本的keyboard.json源码，完整讲解：硬件规格与引脚分配、三种板型差异、编译与刷写命令、两种进入 Bootloader 的方式，以及默认键位、编码器映射、OLED 信息屏与 RGB 矩阵动画的底层实现，帮助读者从零构建并深度定制自己的 pi40 固件。

硬件与引脚概览：一块"引脚全引出"的 RP2040 正交板

根据 readme 与 info.json 的描述，pi40 的核心特征可以归纳为：

• 4x12 正交线性配列：4 行、12 列，共 48 个键位，其中底部固定一枚 2u 空格键（LAYOUT_ortho_4x12布局）；
• Raspberry Pi Pico（RP2040）主控：processor字段为RP2040，bootloader为rp2040，采用 Pico 自带的 BOOTSEL 进入 UF2 刷写模式；
• 可选模块：旋转编码器（1 个，A/B 引脚为 GP14/GP13）、SSD1306 OLED（I2C，SCL=GP17、SDA=GP16）、每键在开关内的 WS2812 RGB LED（数据脚 GP0）；
• 扩展性：所有未使用的 GPIO 与可用的电压引脚均被引出到主板边缘，方便玩家自行焊接传感器、蜂鸣器或其他外设。

以 grid_v1_1/keyboard.json 为例，矩阵扫描定义为COL2ROW（列驱动、行读取）：

"diode_direction": "COL2ROW", "matrix_pins": { "rows": ["GP21", "GP20", "GP19", "GP18"], "cols": ["GP1", "GP2", "GP3", "GP4", "GP5", "GP6", "GP7", "GP8", "GP9", "GP10", "GP11", "GP12", "GP22"] }

注意列引脚共有13 个（GP1~GP12 外加 GP22），其中 GP22 对应 2u 空格键在矩阵中的位置。USB 标识为vid: 0x6F75, pid: 0x5600，由maintainer: ziptyze维护。

三个 PCB 版本的区别

仓库在keyboards/1upkeyboards/pi40/下提供了三份keyboard.json，对应不同 PCB 版本，其matrix_pins、encoder、ws2812、rgb_matrix.layout配置基本一致，差异主要在空格键区的矩阵映射与设备版本号：

这些差异对普通用户透明——三者在编译时都通过LAYOUT_ortho_4x12暴露 48+1（旋钮区）键位的同一接口，刷写时按自己 PCB 丝印版本选择即可（默认编译目标已按grid_v1_1处理）。

编译与刷写：两条命令搞定固件

readme 给出了 pi40 的标准构建流程（前提是按 QMK 官方流程搭好构建环境，如qmk setup）：

# 编译默认键位固件 make 1upkeyboards/pi40:default # 编译并直接进入刷写流程 make 1upkeyboards/pi40:default:flash

• :default对应 keymaps/default/ 目录下的默认键位（keymap.c+rules.mk）；
• :flash会先编译，再调用与bootloader: rp2040匹配的刷写工具（RP2040 走 UF2 拖拽 / 自动挂载方式）。

若想切换为 VIA 键位（readme 中提到固件支持 VIA，可配置旋钮、矩阵灯光与最多 10 层），通常使用：

make 1upkeyboards/pi40:via

VIA 所需的能力在keyboard.json中已具备：dynamic_keymap.layer_count = 10定义了 10 个动态层（对应 readme 所述的"最多 10 层"），同时开启了rgb_matrix、encoder、oled等特性。

进入 Bootloader 的两种方式

readme 明确给出了两种进入刷写模式的方法，源码配置与之呼应：

1. Bootmagic reset（矩阵短路法）：按住矩阵 (0,0) 位置（即左上角第一个键）的同时插入 USB。该能力来自features.bootmagic = true，QMK 在启动时检测特定矩阵位置是否被按住，从而跳过固件启动直接进入 Bootloader；
2. BOOTSEL 按钮（硬件法）：按住 Pico 板上的 BOOTSEL 按钮再插入 USB。这是 RP2040 芯片自带的硬件引导机制，与固件无关，任何状态下都可用，也是最可靠的恢复手段。

默认键位与旋钮映射：四层方案实战

默认键位定义在 keymaps/default/keymap.c，采用经典的"Qwerty / Lower / Raise / Adjust"四层结构（enum layer_names：_ONE~_FOUR）：

• 第 0 层_ONE（Qwerty）：标准字母区；旋钮上方独立键位为RM_TOGG（开关 RGB）；底部为MO(3)Adjust、Ctrl/Alt/GUI、MO(1)Lower、双空格（其中一枚配合MO(2)Raise）、方向键四枚；
• 第 1 层_TWO（Lower）：KC_TILD等符号键、F1~F12、ISO 补充键、Home/End 与媒体控制（KC_MUTE位于旋钮上方、右下为 Next/Vol-/Vol+/Play）；
• 第 2 层_THREE（Raise）：数字行、-=[]\、PgUp/PgDn，旋钮上方同样为KC_MUTE；
• 第 3 层_FOUR（Adjust）：集中 RGB 控制——QK_BOOT（软重启进刷写）、RM_TOGG、RM_NEXT、RM_HUEU/HUED、RM_SATU/SATD、RM_VALU/VALD，以及KC_DEL。

层切换使用MO()（按住临时激活）而非TG()，避免误锁层。所有_______表示透传（沿用下层定义）。

编码器映射：同一旋钮，四层四用

keymaps/default/rules.mk 仅一行：

ENCODER_MAP_ENABLE = yes

开启ENCODER_MAP_ENABLE后，keymap.c通过encoder_map数组按层为唯一旋钮分配行为：

[_ONE] = { ENCODER_CCW_CW(RM_PREV, RM_NEXT) }, // 第0层：切换上一/下一RGB动画 [_TWO] = { ENCODER_CCW_CW(KC_VOLD, KC_VOLU) }, // 第1层：音量减/加 [_THREE] = { ENCODER_CCW_CW(KC_VOLD, KC_VOLU) }, // 第2层：音量减/加 [_FOUR] = { ENCODER_CCW_CW(KC_VOLD, KC_VOLU) } // 第3层：音量减/加

旋钮的物理引脚在keyboard.json中定义为pin_a: GP14, pin_b: GP13。这就是 readme 所说的"VIA 提供旋钮配置选项"在键位层的实现基础——用户可以在 VIA 界面直接改各层的旋钮动作。

OLED 信息屏：logo 动画 + 实时状态

pi40 的 OLED 实现在 pi40.c 中，由 config.h 提供硬件接线与显示参数：

#define I2C1_SCL_PIN GP17 #define I2C1_SDA_PIN GP16 #define I2C_DRIVER I2CD0 #define OLED_BRIGHTNESS 128 #define OLED_FONT_H "keyboards/1upkeyboards/pi40/lib/glcdfont.c"

• I2C 走 GP16/GP17，对应 halconf.h 中HAL_USE_I2C TRUE与 mcuconf.h 中启用 I2C0（RP_I2C_USE_I2C0 TRUE）；
• 使用自定义字体 lib/glcdfont.c 渲染 logo 图形；
• OLED_BRIGHTNESS 128设定默认亮度。

屏幕逻辑（oled_task_kb）采用「开机 5 秒 logo → 切到信息页」的流程：

• SHOW_LOGO 5000：上电后前 5000ms 通过render_logo()将my_logo[]位图（PROGMEM 存储的 128x32 像素数组）以oled_write_raw_P写入屏幕；
• 之后clear_screen()清屏，再调用user_oled_magic()渲染信息页；
• oled_init_kb返回OLED_ROTATION_180，即屏幕旋转 180° 安装（适应 PCB 上不同朝向的插座）。

user_oled_magic()正是 readme 所列默认显示内容的源码实现：

1. 当前层：get_highest_layer(layer_state)取最高激活层，映射为 "One"~"Ten"，超过 9 层显示 "Undefined"（与 VIA 的 10 层上限呼应）；
2. Caps / Num / Scroll 锁定状态：通过host_keyboard_led_state()读取主机 LED 状态，分别输出Cap(x)/Cap( )、Num(x)/Num( )、Scrl(x)/Scrl( )；
3. 当前 RGB 模式名称：对rgb_matrix_get_mode()的返回值 1~44 逐一映射为动画名（Solid Color、Alphas Mods、Breathing、Rainbow Moving Chevron、Digital Rain、Typing Heatmap……），与info.json中开启的动画一一对应。

RGB 矩阵：全动画 + 亮度上限 + 睡眠

info.json 是固件级 RGB 能力的总开关：

• rgb_matrix.animations：将 QMK 全部内置动画（alphas_mods、gradient_up_down、breathing、cycle_、rainbow_、reactive 系列、splash 系列、digital_rain、typing_heatmap 等 40+ 种）统一置true，因此 VIA/键位中可以随时切换任意动画；
• max_brightness: 150：亮度上限为 150（0~255 区间），既保证 WS2812 灯珠（驱动引脚 GP0，driver: "vendor"）亮度足够，又控制整板电流与发热；
• sleep: true：启用 RGB 自动休眠，键盘闲置一段时间后灯效自动关闭以省电；
• 每颗灯的物理坐标在rgb_matrix.layout中逐点定义（x/y坐标 +matrix行列 +flags，flags=1 表示键位灯、flags=4 表示普通 RGB 效果参与位），这是动画效果（如渐变方向、reactive 扩散）能正确贴合键位形状的关键。

小结与延伸阅读

pi40 是一个把 RP2040 的灵活性发挥得比较充分的小型正交键盘：四层键位 + 旋钮映射 + 自绘 OLED 状态页 + 40+ 种 RGB 动画，全部在 QMK 的数据驱动配置（keyboard.json/info.json）与少量板级代码（config.h/pi40.c）中完成。上手路线建议：

1. 按 readme 命令make 1upkeyboards/pi40:default编译，make 1upkeyboards/pi40:default:flash刷写，验证默认四层与旋钮/OLED/RGB 行为；
2. 参考 keymaps/default/keymap.c 修改自己的键位，或切换到 via 键位用图形界面调整层与旋钮；
3. 如需深入 OLED 渲染与 RGB 布局，可从 pi40.c 与各版本keyboard.json的rgb_matrix.layout入手学习 QMK 的板级编程接口。

相关背景资料可继续阅读仓库内的 keymap.md（键位与层机制）、feature_rgb_matrix.md（RGB 矩阵配置）、feature_encoders.md（旋钮映射）以及 feature_oled_driver.md（OLED 驱动），其中涵盖了本键盘所用全部特性的通用配置方法。

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