QMK 中 ai03 Soyuz 单 PCB 数字小键盘固件：键盘配置解析与键位定制实战

QMK 中 ai03 Soyuz 单 PCB 数字小键盘固件：键盘配置解析与键位定制实战

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

QMK 固件仓库中的ai03/soyuz是一款单 PCB（single-PCB）数字小键盘（numpad kit）的官方键盘定义，由 ai03 Design Studio 维护，基于 Atmel ATmega32U4 微控制器。本篇以 keyboards/ai03/soyuz/readme.md 为出发点，结合 keyboards/ai03/soyuz/keyboard.json 与两份随附键位文件，完整讲清这款键盘的硬件配置、矩阵引脚、两种内置布局宏、默认数字键盘键位的含义，以及如何仿照仓库现成示例编写自定义键码（custom keycode）——读完后你可以独立完成make ai03/soyuz:default编译，并理解每个配置项在构建系统中的实际作用。

一、键盘概况与维护信息

原 readme 中给出的基本事实如下：

• 键盘类型：single-PCB numpad kit（单 PCB 数字键盘套件）；
• 维护者：ai03（QMK 目录位于 keyboards/ai03/readme.md 所述的 ai03 定制 PCB 系列中）；
• 硬件支持：Soyuz PCB；
• 硬件获取：多家厂商渠道，清单以 PCB 仓库为准。

从 keyboards/ai03/soyuz/keyboard.json 可以看到更精确的硬件身份标识：

"usb": { "vid": "0xA103", "pid": "0x0018", "device_version": "0.0.1" }, "processor": "atmega32u4", "bootloader": "atmel-dfu", "manufacturer": "ai03 Design Studio"

这些字段的含义可参照 docs/reference_info_json.md：keyboard_name/manufacturer会作为 USB 产品/厂商字符串上报给主机；processor与bootloader决定编译工具链与烧录方式（AVR 工具链 + ATmega DFU）；vid/pid则是主机识别该键盘设备的唯一依据。由于使用atmel-dfu引导加载器，刷写流程可参考 docs/flashing.md 中针对 AVR DFU 的说明（qmk flash或dfu-util均可）。

二、编译命令与构建环境

原 readme 给出的构建入口命令是：

make ai03/soyuz:default

其中ai03/soyuz是键盘路径，default是键位名，对应 keyboards/ai03/soyuz/keymaps/default/keymap.c。QMK 的构建规则会自动把keyboards/ai03/soyuz/下的keyboard.json解析为编译参数（这是 QMK 数据驱动配置机制，详见 docs/reference_info_json.md），无需再手写rules.mk或config.h。

构建环境准备与 make 用法请分别参考仓库文档 docs/getting_started_make_guide.md、docs/getting_started_docker.md（Docker 方式）以及新手总入口 docs/newbs.md。若只想了解键盘本身有哪些功能选项，还可以运行make ai03/soyuz:default:help查看该键盘可用的 feature 开关。

三、矩阵配置：5 行 × 4 列与 COL2ROW 二极管方向

keyboard.json中的矩阵引脚定义：

"matrix_pins": { "cols": ["F4", "B3", "D7", "B5"], "rows": ["D4", "C6", "B6", "E6", "B4"] }, "diode_direction": "COL2ROW"

即 4 列（F4/B3/D7/B5）× 5 行（D4/C6/B6/E6/B4）共 20 个矩阵位置，二极管方向为COL2ROW（列驱动、行检测）。引脚命名F4、B3等是 ATmega32U4 的端口/引脚表示法。矩阵扫描原理可参阅 docs/how_a_matrix_works.md。

该键盘在features中声明了：

"features": { "bootmagic": false, "command": true, "extrakey": true, "mousekey": true, "nkro": true }

• command: true：启用命令模式，其中就包括MAGIC_KEY_NKRO（N键切换 N-Key Rollover），见 docs/features/command.md；
• extrakey: true：启用KC_LCTL、KC_LSFT等修饰/控制键与KC_P*数字小键盘键码；
• mousekey: true：启用鼠标键；
• nkro: true：编译期默认开启 NKRO，绕开 AVR 双列按键的固件模拟滚转限制（AVR 双列硬件下通常只能达到 2KRO，NKRO 通过固件手段提升滚转能力）；
• bootmagic: false：关闭 Bootmagic 恢复键（进入 DFU 的方式改为command模式下的R键或 RESET 键）。

另外qmk.locking被显式开启：

"qmk": { "locking": { "enabled": true, "resync": true } }

含义是启用锁键（Caps Lock 等）支持，并在连接时以物理开关状态重新同步锁键 LED 状态，字段语义同样定义在 docs/reference_info_json.md 的qmk一节。对数字键盘这类常用 Caps Lock 的设备，这一默认开启是合理的。

四、两种内置布局：ortho_5x4 与 numpad_5x4

keyboard.json声明了"community_layouts": ["ortho_5x4", "numpad_5x4"]，并定义了各自的LAYOUT_*宏。两者都由 20 个矩阵坐标构成，但物理形状不同：

1. LAYOUT_ortho_5x4：标准 5 行 × 4 列正交布局，每个键位都是 1U，x/y与矩阵[row, col]一一对应；
2. LAYOUT_numpad_5x4：按标准数字键盘形态排布的布局宏，其中包含宽/高键位：

{"matrix": [2, 3], "x": 3, "y": 1, "h": 2}, {"matrix": [4, 1], "x": 0, "y": 4, "w": 2}, {"matrix": [4, 3], "x": 3, "y": 3, "h": 2}

从源码结构看，w: 2表示该键占 2U 宽（对应数字键盘的0键），h: 2表示占 2U 高（对应+与Enter键）。该布局在 QMK Configurator 的可视化界面中会以正确的物理比例展示，而LAYOUT_ortho_5x4则用于纯网格视图；两份键位文件当前都采用LAYOUT_ortho_5x4书写。

五、default 键位：标准数字键盘键码

仓库随附的 default 键位（keyboards/ai03/soyuz/keymaps/default/keymap.c）完整内容如下：

#include QMK_KEYBOARD_H const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { [0] = LAYOUT_ortho_5x4( /* Base */ KC_NUM, KC_PSLS, KC_PAST, KC_PMNS, KC_P7, KC_P8, KC_P9, KC_PPLS, KC_P4, KC_P5, KC_P6, KC_PPLS, KC_P1, KC_P2, KC_P3, KC_PENT, KC_P0, KC_P0, KC_PDOT, KC_PENT ) };

要点解析：

• PROGMEM与keymaps[][MATRIX_ROWS][MATRIX_COLS]是 QMK 键位表的标准声明方式：行数为 5、列数为 4，来自keyboard.json的matrix_pins；
• 所有键码均为KC_P*系列数字小键盘键码（KC_P0–KC_P9、KC_PDOT、KC_PENT、KC_PPLS、KC_PMNS、KC_PAST、KC_PSLS）与KC_NUM（Num Lock 切换），完整列表见 docs/keycodes.md；
• 布局上第一行是NUM / ÷ / × / −，底部两列是横跨两键位的0与Enter（在 1U 矩阵宏中各占一个键位，与真实 PCB 的 2U 物理键一一对应）。

六、1U 键位示例：自定义键码与 process_record_user

仓库还提供了一个1U键位（keyboards/ai03/soyuz/keymaps/1U/keymap.c），它是最有教学价值的部分——展示了如何为 Soyuz 这类小键盘增加自定义行为。完整键位表与处理函数：

enum custom_keycodes { DBLZERO = SAFE_RANGE }; const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { [0] = LAYOUT_ortho_5x4( /* Base */ KC_NUM, KC_PSLS, KC_PAST, KC_BSPC, KC_P7, KC_P8, KC_P9, KC_MINS, KC_P4, KC_P5, KC_P6, KC_PPLS, KC_P1, KC_P2, KC_P3, KC_EQL, DBLZERO, KC_P0, KC_PDOT, KC_PENT ) }; bool process_record_user(uint16_t keycode, keyrecord_t *record) { switch (keycode) { case DBLZERO: if (record->event.pressed) { SEND_STRING("00"); } break; } return true; }

这段代码示范了三个 QMK 核心机制：

1. SAFE_RANGE起始的自定义键码枚举：DBLZERO = SAFE_RANGE确保自定义键码从安全数值起分配，避免与 QMK 内置键码冲突；
2. process_record_user钩子：每个按键事件都会经过该用户函数，record->event.pressed为真表示按下瞬间，返回true表示事件已被处理、不再走默认行为；
3. SEND_STRING发送字符串：此处按下DBLZERO键即向系统发送00两个字符，等价于数字键盘上宽0键的“双击”语义。SEND_STRING的用法与限制见 docs/features/send_string.md。

与 default 键位的差异还体现在把部分修饰位置替换成了KC_BSPC、KC_MINS、KC_EQL等编辑类键码，说明该键位面向的是“在 1U 网格上更侧重编辑操作”的使用习惯。编译时通过make ai03/soyuz:1U即可产出该键位固件。

七、构建产物与刷写流程小结

结合上述信息，完整工作流为：

1. 准备 QMK 构建环境（make 工具链或 Docker，见 docs/getting_started_make_guide.md）；
2. make ai03/soyuz:default生成固件（AVR 编译产物为.hex，可用make ai03/soyuz:default:flash或qmk flash烧录）；
3. 进入 DFU 模式的方式：由于bootmagic关闭，可通过命令模式（command: true）按R键触发 DFU 重启，或短接 RESET 引脚；
4. 主机侧以 VID0xA103、PID0x0018识别该设备。

需要定制时，推荐的做法是复制keymaps/default目录为新键位、修改keymap.c中的LAYOUT_ortho_5x4(...)参数，然后以make ai03/soyuz:<新键位名>编译；布局宏的物理映射关系始终以 keyboards/ai03/soyuz/keyboard.json 中的layouts定义为唯一事实来源。

参考资料（仓库内路径）

• 键盘定义与 readme：keyboards/ai03/soyuz/readme.md、keyboards/ai03/soyuz/keyboard.json
• 键位实现：keyboards/ai03/soyuz/keymaps/default/keymap.c、keyboards/ai03/soyuz/keymaps/1U/keymap.c
• 文档：docs/reference_info_json.md（keyboard.json 字段）、docs/keycodes.md（键码）、docs/features/command.md（命令模式）、docs/features/send_string.md（SEND_STRING）、docs/how_a_matrix_works.md（矩阵原理）、docs/flashing.md（刷写）、docs/newbs.md（新手指南）

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