QMK 固件定制实战1upkeyboards 1upSuper16v3 编译、刷写与配置全解析【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware1upSuper16v3 是 1upkeyboards 推出的一款 4×4 正交宏键盘macropad最大的亮点在于顶行最多可搭载四颗旋转编码器并同时具备开关内 per-key 可寻址 RGB 与 32 颗 1mm 底光 RGB LED。本文以 QMK 官方仓库中 1upSuper16v3 的 readme 为主体结合其 keyboard.json 数据驱动配置、默认键位 与 QMK 的编码器/灯光文档完整讲解这款基于 RP2040 的键盘固件从编译、刷写到键位与编码器深度定制的全过程。读完本文你将能够独立完成该键盘固件的构建与烧录并能看懂、修改其矩阵、编码器与 RGB 配置。硬件概览与固件特性根据 readme 与 keyboard.json1upSuper16v3 的核心规格如下形态4×4 正交宏键盘顶行可选装最多 4 颗旋转编码器EC11 兼容主控Raspberry Pi RP2040processor: RP2040接线方式开关矩阵采用直接引脚direct pins直连每个按键独立占用一个 GPIO无需行列扫描矩阵灯光开关内 per-key 可寻址 RGBWS2812 驱动 32 颗 1mm 底光 RGB实现明亮顺滑的动态灯效固件特性bootmagicBootmagic 复位、encoder编码器、extrakey媒体/系统键、mousekey鼠标键、rgb_matrixRGB 矩阵并默认关闭nkroUSB 标识vid: 0x6F75、pid: 0x5610、设备版本1.0.0厂商为 1upkeyboards维护者为 ziptyze。从仓库目录看该键盘遵循 QMK 的“数据驱动配置data-driven configuration”模式整块键盘的定义全部收敛在 keyboard.json 中不依赖传统的config.h与rules.mk这与 data_driven_config.md 描述的现代 QMK 键盘配置方式一致。目录结构与配置文件解读1upSuper16v3 在仓库中的目录结构非常精简keyboards/1upkeyboards/1upsuper16v3/ ├── keymaps/ │ └── default/ │ ├── keymap.c # 默认键位与编码器映射 │ └── rules.mk # 键位级编译选项ENCODER_MAP_ENABLE ├── keyboard.json # 键盘级全部硬件与功能配置 └── readme.md # 官方说明文档keyboard.json一块键盘的“总装图”keyboard.json中值得逐项解读的关键配置矩阵直连引脚matrix_pins.direct——4 行 4 列直接映射到 16 个 GPIOmatrix_pins: { direct: [ [GP23, GP24, GP4, GP5], [GP19, GP27, GP1, GP8], [GP18, GP28, GP0, GP9], [GP17, GP16, GP15, GP11] ] }第 0 行第 0 列对应GP23即 readme 中 Bootmagic 复位所用的“左上角第一颗按键”。旋转编码器encoder.rotary——按顺序定义了顶行 4 颗编码器的 A/B 引脚encoder: { rotary: [ {pin_a: GP20, pin_b: GP21}, {pin_a: GP25, pin_b: GP26}, {pin_a: GP2, pin_b: GP3}, {pin_a: GP6, pin_b: GP7} ] }编码器的行为细节可对照 docs/features/encoders.mdEC11 兼容编码器在 QMK 中通过ENCODER_A_PINS/ENCODER_B_PINS定义若旋向反了可交换 A/B 或使用ENCODER_DIRECTION_FLIP每档脉冲数可用ENCODER_RESOLUTION/ENCODER_RESOLUTIONS调整。1upSuper16v3 未额外定义这些宏说明采用 QMK 默认解析度。RGB 矩阵rgb_matrix——驱动为ws2812LED 布局通过坐标x/y与标志位flags描述 32 颗底光 LEDflags: 2和 16 颗开关内 LEDflags: 4的位置并启用了sleep: true休眠时关闭灯效。同时开启了一大批内置动画cycle_all、breathing、rainbow_beacon、typing_heatmap、solid_reactive系列等。WS2812 数据线定义在ws2812段驱动vendor引脚GP29。动态键位dynamic_keymap——layer_count: 10表示支持 10 层键位动态切换可用 QMK 的dynamic keymap机制在运行时读写键位无需重新编译。键位布局layouts与社区布局community_layouts——定义LAYOUT_ortho_4x4并将ortho_4x4声明为社区布局意味着可以在布局共享库中复用他人为 4×4 正交板编写的键位。编译与刷写构建环境就绪后参见 getting_started_introduction.md 与 getting_started_make_guide.md编译默认键位make 1upkeyboards/1upsuper16v3:default刷写默认键位make 1upkeyboards/1upsuper16v3:default:flashRP2040 主控通过 USB 刷写使用:flash目标时 QMK 会自动查找进入刷写模式的设备。新手如需完整流程可参考 newbs.md 与 newbs_flashing.md。进入 Bootloader 的两种方式readme 明确指出该键盘进入 bootloader 有两种途径Bootmagic 复位按住矩阵 (0,0) 位置的按键即左上角第一颗键再插入 USB。该功能由features.bootmagic: true启用物理复位键按住 PCB 背面的复位按钮的同时插入 USB 线。此外从默认键位的第二层Layer 1可以看到一个QK_BOOT键位码它允许在运行时直接把键盘踢进 bootloader属于第三种便捷方式。默认键位数字小键盘 RGB 控制层default/keymap.c定义了两层键位方向与 readme 及 keyboard.json 中的矩阵坐标一致Layer 0 —— 数字小键盘布局[0] LAYOUT_ortho_4x4( KC_P7, KC_P8, KC_P9, KC_PMNS, KC_P4, KC_P5, KC_P6, KC_PPLS, KC_P1, KC_P2, KC_P3, KC_PSLS, MO(1), KC_P0, KC_PDOT, KC_PENT );左下角MO(1)为层切换键按住进入第二层其余按键覆盖数字 0–9、加减乘除与回车可以直接当作独立数字小键盘使用。Layer 1 —— RGB 控制与复位层[1] LAYOUT_ortho_4x4( RM_TOGG, RM_HUEU, RM_SATU, RM_VALU, RM_NEXT, RM_HUED, RM_SATD, RM_VALD, RM_SPDD, RM_SPDU, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, KC_TRNS, QK_BOOT );该层集中了 RGB 矩阵控制键码RM_TOGG开关、RM_HUEU/RM_HUED色相加减、RM_SATU/RM_SATD饱和度加减、RM_VALU/RM_VALD亮度加减、RM_NEXT切换动画、RM_SPDU/RM_SPDD动画速度加减右下角QK_BOOT一键进入刷写模式。未定义的按键用KC_TRNS透传到下一层。编码器映射四颗编码器统一控制音量default/rules.mk只有一行ENCODER_MAP_ENABLE yes按 docs/features/encoders.md 的说明ENCODER_MAP_ENABLE应只在键位层启用“This should only be enabled at the keymap level”它会让编码器事件走正常的 QMK 键码处理管线从而与普通键位一样支持分层行为。对应地keymap.c 中通过ENCODER_CCW_CW()宏为每一层、每一颗编码器指定逆时针/顺时针动作#if defined(ENCODER_MAP_ENABLE) const uint16_t PROGMEM encoder_map[][NUM_ENCODERS][NUM_DIRECTIONS] { [0] { ENCODER_CCW_CW(KC_VOLD, KC_VOLU), ENCODER_CCW_CW(KC_VOLD, KC_VOLU), ENCODER_CCW_CW(KC_VOLD, KC_VOLU), ENCODER_CCW_CW(KC_VOLD, KC_VOLU) }, [1] { ENCODER_CCW_CW(KC_TRNS, KC_TRNS), ENCODER_CCW_CW(KC_TRNS, KC_TRNS), ENCODER_CCW_CW(KC_TRNS, KC_TRNS), ENCODER_CCW_CW(KC_TRNS, KC_TRNS) } }; #endifLayer 0 上四颗编码器全部映射为音量调节逆时针KC_VOLD减音量、顺时针KC_VOLU加音量Layer 1 上全部透传KC_TRNS。QMK 默认行为下即使不定义任何映射编码器也会作为音量键工作这里显式定义后每颗编码器的功能都可通过改这一张表按层定制。动手定制如何把这块板改造成你想要的样子以现有配置为基础你可以做几类典型的二次定制仓库只读以下均为本地用户态修改方式改键位复制keymaps/default为keymaps/mine编辑keymap.c中LAYOUT_ortho_4x4(...)的键码例如把KC_P7换成KC_A、KC_ENT换成LT(2, KC_ENT)等然后用make 1upkeyboards/1upsuper16v3:mine编译改编码器功能将encoder_map某一颗编码器改为ENCODER_CCW_CW(KC_PGDN, KC_PGUP)翻页或ENCODER_CCW_CW(MS_WHLU, MS_WHLD)滚轮并确认features.mousekey已开启以支持鼠标类键码调整 RGB 动画rgb_matrix.animations中各动画开关可直接在 keyboard.json 中增删再重新编译烧录运行时可借助默认第二层的RM_*键码即时预览效果利用动态键位dynamic_keymap.layer_count: 10提供了 10 层动态层配合 QMK Configurator 或 VIA 类工具可免编译改键扩展层数默认键位只用到 0/1 两层但键盘本身支持 10 层动态键位可在keymap.c中继续追加[2]、[3]等层并配合MO()/LT()使用。小结1upSuper16v3 是 QMK 生态中“数据驱动 RP2040 编码器 全键 RGB”组合的典型代表硬件定义全部集中在 keyboard.json键位与编码器行为集中在 keymaps/default编译刷写只需两条make命令。理解它的配置结构后无论是修改键位、给编码器换功能还是裁剪 RGB 动画都能通过少量改动快速完成并可直接套用到其他基于keyboard.json的 QMK 键盘上。【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考