企业官网建设流程全解析

QMK 固件定制实战：1upkeyboards 1upSuper16v3 编译、刷写与配置全解析

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

1upSuper16v3 是 1upkeyboards 推出的一款 4×4 正交宏键盘（macropad），最大的亮点在于顶行最多可搭载四颗旋转编码器，并同时具备开关内 per-key 可寻址 RGB 与 32 颗 1mm 底光 RGB LED。本文以 QMK 官方仓库中 1upSuper16v3 的 readme 为主体，结合其 keyboard.json 数据驱动配置、默认键位 与 QMK 的编码器/灯光文档，完整讲解这款基于 RP2040 的键盘固件从编译、刷写到键位与编码器深度定制的全过程。读完本文，你将能够独立完成该键盘固件的构建与烧录，并能看懂、修改其矩阵、编码器与 RGB 配置。

硬件概览与固件特性

根据 readme 与 keyboard.json，1upSuper16v3 的核心规格如下：

• 形态：4×4 正交宏键盘，顶行可选装最多 4 颗旋转编码器（EC11 兼容）；
• 主控：Raspberry Pi RP2040（"processor": "RP2040"）；
• 接线方式：开关矩阵采用直接引脚（direct pins）直连，每个按键独立占用一个 GPIO，无需行列扫描矩阵；
• 灯光：开关内 per-key 可寻址 RGB（WS2812 驱动）＋ 32 颗 1mm 底光 RGB，实现明亮顺滑的动态灯效；
• 固件特性：bootmagic（Bootmagic 复位）、encoder（编码器）、extrakey（媒体/系统键）、mousekey（鼠标键）、rgb_matrix（RGB 矩阵），并默认关闭nkro；
• USB 标识：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 个 GPIO：

"matrix_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.md：EC11 兼容编码器在 QMK 中通过ENCODER_A_PINS/ENCODER_B_PINS定义，若旋向反了可交换 A/B 或使用ENCODER_DIRECTION_FLIP，每档脉冲数可用ENCODER_RESOLUTION/ENCODER_RESOLUTIONS调整。1upSuper16v3 未额外定义这些宏，说明采用 QMK 默认解析度。

RGB 矩阵（rgb_matrix）——驱动为ws2812，LED 布局通过坐标（x/y）与标志位（flags）描述 32 颗底光 LED（flags: 2）和 16 颗开关内 LED（flags: 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:flash

RP2040 主控通过 USB 刷写（使用:flash目标时 QMK 会自动查找进入刷写模式的设备）。新手如需完整流程，可参考 newbs.md 与 newbs_flashing.md。

进入 Bootloader 的两种方式

readme 明确指出该键盘进入 bootloader 有两种途径：

1. Bootmagic 复位：按住矩阵 (0,0) 位置的按键（即左上角第一颗键）再插入 USB。该功能由features.bootmagic: true启用；
2. 物理复位键：按住 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) } }; #endif

Layer 0 上四颗编码器全部映射为音量调节（逆时针KC_VOLD减音量、顺时针KC_VOLU加音量）；Layer 1 上全部透传KC_TRNS。QMK 默认行为下，即使不定义任何映射，编码器也会作为音量键工作；这里显式定义后，每颗编码器的功能都可通过改这一张表按层定制。

动手定制：如何把这块板改造成你想要的样子

以现有配置为基础，你可以做几类典型的二次定制（仓库只读，以下均为本地用户态修改方式）：

1. 改键位：复制keymaps/default为keymaps/mine，编辑keymap.c中LAYOUT_ortho_4x4(...)的键码，例如把KC_P7换成KC_A、KC_ENT换成LT(2, KC_ENT)等，然后用make 1upkeyboards/1upsuper16v3:mine编译；
2. 改编码器功能：将encoder_map某一颗编码器改为ENCODER_CCW_CW(KC_PGDN, KC_PGUP)（翻页）或ENCODER_CCW_CW(MS_WHLU, MS_WHLD)（滚轮），并确认features.mousekey已开启以支持鼠标类键码；
3. 调整 RGB 动画：rgb_matrix.animations中各动画开关可直接在 keyboard.json 中增删，再重新编译烧录；运行时可借助默认第二层的RM_*键码即时预览效果；
4. 利用动态键位：dynamic_keymap.layer_count: 10提供了 10 层动态层，配合 QMK Configurator 或 VIA 类工具可免编译改键；
5. 扩展层数：默认键位只用到 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