QMK 固件实战1upkeyboards pi40RP2040 正交 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 PicoRP2040主控的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 PicoRP2040主控processor字段为RP2040bootloader为rp2040采用 Pico 自带的 BOOTSEL 进入 UF2 刷写模式可选模块旋转编码器1 个A/B 引脚为 GP14/GP13、SSD1306 OLEDI2CSCLGP17、SDAGP16、每键在开关内的 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配置基本一致差异主要在空格键区的矩阵映射与设备版本号版本目录device_version空格键区矩阵映射特点mit_v1_0/keyboard.json1.0.0底部行使用[3,6]等矩阵位置2u 空格对应matrix: [0,12]位于 y4 行中间mit_v1_1/keyboard.json1.1.0顶部第一行首列使用[0,12]作为隐藏的第 13 列对应旋钮位附近按键空格区映射与 v1.0 略有调整grid_v1_1/keyboard.json1.1.0顶部[0,12]同样独立映射RGB layout 中第 4 行[3,5]坐标为 (102,56) 居中对齐这些差异对普通用户透明——三者在编译时都通过LAYOUT_ortho_4x12暴露 481旋钮区键位的同一接口刷写时按自己 PCB 丝印版本选择即可默认编译目标已按grid_v1_1处理。编译与刷写两条命令搞定固件readme 给出了 pi40 的标准构建流程前提是按 QMK 官方流程搭好构建环境如qmk setup# 编译默认键位固件 make 1upkeyboards/pi40:default # 编译并直接进入刷写流程 make 1upkeyboards/pi40:default:flash:default对应 keymaps/default/ 目录下的默认键位keymap.crules.mk:flash会先编译再调用与bootloader: rp2040匹配的刷写工具RP2040 走 UF2 拖拽 / 自动挂载方式。若想切换为 VIA 键位readme 中提到固件支持 VIA可配置旋钮、矩阵灯光与最多 10 层通常使用make 1upkeyboards/pi40:viaVIA 所需的能力在keyboard.json中已具备dynamic_keymap.layer_count 10定义了 10 个动态层对应 readme 所述的最多 10 层同时开启了rgb_matrix、encoder、oled等特性。进入 Bootloader 的两种方式readme 明确给出了两种进入刷写模式的方法源码配置与之呼应Bootmagic reset矩阵短路法按住矩阵 (0,0) 位置即左上角第一个键的同时插入 USB。该能力来自features.bootmagic trueQMK 在启动时检测特定矩阵位置是否被按住从而跳过固件启动直接进入 BootloaderBOOTSEL 按钮硬件法按住 Pico 板上的 BOOTSEL 按钮再插入 USB。这是 RP2040 芯片自带的硬件引导机制与固件无关任何状态下都可用也是最可靠的恢复手段。默认键位与旋钮映射四层方案实战默认键位定义在 keymaps/default/keymap.c采用经典的Qwerty / Lower / Raise / Adjust四层结构enum layer_names_ONE~_FOUR第 0 层_ONEQwerty标准字母区旋钮上方独立键位为RM_TOGG开关 RGB底部为MO(3)Adjust、Ctrl/Alt/GUI、MO(1)Lower、双空格其中一枚配合MO(2)Raise、方向键四枚第 1 层_TWOLowerKC_TILD等符号键、F1~F12、ISO 补充键、Home/End 与媒体控制KC_MUTE位于旋钮上方、右下为 Next/Vol-/Vol/Play第 2 层_THREERaise数字行、-[]\、PgUp/PgDn旋钮上方同样为KC_MUTE第 3 层_FOURAdjust集中 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.cI2C 走 GP16/GP17对应 halconf.h 中HAL_USE_I2C TRUE与 mcuconf.h 中启用 I2C0RP_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 所列默认显示内容的源码实现当前层get_highest_layer(layer_state)取最高激活层映射为 One~Ten超过 9 层显示 Undefined与 VIA 的 10 层上限呼应Caps / Num / Scroll 锁定状态通过host_keyboard_led_state()读取主机 LED 状态分别输出Cap(x)/Cap( )、Num(x)/Num( )、Scrl(x)/Scrl( )当前 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亮度上限为 1500~255 区间既保证 WS2812 灯珠驱动引脚 GP0driver: vendor亮度足够又控制整板电流与发热sleep: true启用 RGB 自动休眠键盘闲置一段时间后灯效自动关闭以省电每颗灯的物理坐标在rgb_matrix.layout中逐点定义x/y坐标 matrix行列 flagsflags1 表示键位灯、flags4 表示普通 RGB 效果参与位这是动画效果如渐变方向、reactive 扩散能正确贴合键位形状的关键。小结与延伸阅读pi40 是一个把 RP2040 的灵活性发挥得比较充分的小型正交键盘四层键位 旋钮映射 自绘 OLED 状态页 40 种 RGB 动画全部在 QMK 的数据驱动配置keyboard.json/info.json与少量板级代码config.h/pi40.c中完成。上手路线建议按 readme 命令make 1upkeyboards/pi40:default编译make 1upkeyboards/pi40:default:flash刷写验证默认四层与旋钮/OLED/RGB 行为参考 keymaps/default/keymap.c 修改自己的键位或切换到 via 键位用图形界面调整层与旋钮如需深入 OLED 渲染与 RGB 布局可从 pi40.c 与各版本keyboard.json的rgb_matrix.layout入手学习 QMK 的板级编程接口。相关背景资料可继续阅读仓库内的 keymap.md键位与层机制、feature_rgb_matrix.mdRGB 矩阵配置、feature_encoders.md旋钮映射以及 feature_oled_driver.mdOLED 驱动其中涵盖了本键盘所用全部特性的通用配置方法。【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考