QMK 复古改造：Numeric Keypad IIe 默认键位详解与 USB 转换实践

QMK 复古改造：Numeric Keypad IIe 默认键位详解与 USB 转换实践

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

导读

本文聚焦 QMK 固件仓库中keyboards/converter/numeric_keypad_iie这一经典改造项目——把苹果 Apple //e 时代的Numeric Keypad IIe（型号 A2M2003）外置数字键盘改装成现代 USB 键盘。文章以官方default键位图（readme）为核心，结合 keymap.c 源码与 keyboard.json 硬件配置，完整还原其按键映射、矩阵接线与编译烧录流程，让你能够理解并复现这一"旧硬件 + 新固件"的完整链路。

一、项目背景：从 Apple //e 主板接口到 USB

Numeric Keypad IIe 是苹果公司为 Apple //e 个人电脑推出的外置数字小键盘。它没有板载控制器，必须通过一根 DB15（外观同 VGA）固定线缆直接连接 Apple //e 主板的扩展接口。这意味着：键盘本身只有键轴矩阵和物理走线，没有任何"大脑"——这正是它能够被 QMK 复活的根本原因。

该项目（键盘维护者为 Adam Newbold）给出的参考改造方案是：

1. 使用键盘自带的 DB15 固定线缆；
2. 连接到一个 DB15 接线端子转接板（breakout board）；
3. 将转接板各引脚接到Arduino Micro（搭载 ATmega32U4 主控）上，由 QMK 固件负责扫描矩阵、生成 USB HID 报告。

支持硬件与器件信息：

• 硬件：Numeric Keypad IIe 内部 PCB（Apple 零件号 820.0081.c）
• 主控：ATmega32U4 微控制器
• 构建命令：make converter/numeric_keypad_iie:default

仓库中的converter目录下还汇集了其他类似的旧键盘转换项目（如adb_usb、ibm_terminal、sun_usb、xt_usb等，见 keyboards/converter），numeric_keypad_iie是其中针对 Apple 外设的典型案例，同一思路也适用于 M0110 等苹果经典键盘。

二、默认键位布局全景：与原装键帽一一对应

default键位图的设计原则非常朴素：所有按键都执行其原装键帽上印制的默认功能，不做任何自定义改动，最大限度还原 Apple //e 时代的操作习惯。

readme.md特别强调了唯一的例外与历史细节："Print" 键被映射为问号（?）。这是因为在 Apple //e 的 AppleSoft BASIC 环境中，问号?是PRINT命令的简写形式，因此原装键盘上这颗标有 "Print" 的键，其原始电气行为就是输出?——QMK 默认键位忠实地复刻了这一行为。

keymap.c中的布局注释以 ASCII 图示完整呈现了 24 键位结构：

+-------+ +-------+-------+-------+ +-------+-------+ | Esc | | 7 | 8 | 9 | | ( | ) | +-------+ +-------+-------+-------+ +-------+-------+ | <-- | | 4 | 5 | 6 | | - | / | +-------+ +-------+-------+-------+ +-------+-------+ | --> | | 1 | 2 | 3 | | + | * | +-------+ +--+-------+-------+-------+ +-------+-------+ | Space | | 0 | , | . | | Ret | Print | +-------+ +----------+-------+-------+ +-------+-------+

可以看到这是一块典型的四行数字键盘：左侧竖排是 Esc 与光标方向键（<--、-->、Space），中间是标准数字小键盘区，右侧是 Apple 风格的运算符号区（括号(、)、-、/、+、*），底行则是0、逗号、句号、回车与 Print。

三、源码级键位对照：每个按键的 QMK Keycode

keymap.c使用LAYOUT宏一次性定义全部 24 个键位，逐键对照如下（源码见 keymaps/default/keymap.c）：

其中几个值得注意的别名细节，可对照 quantum/keycodes.h 与 quantum/keymap_extras/keymap_us.h：

• KC_LEFT_PAREN是 US 键位扩展中KC_LPRN的别名（keymap_us.h）；
• KC_QUESTION是KC_QUES的别名（keymap_us.h）；
• KC_KP_COMMA对应 HID Usage 0x0085（keycodes.h），并拥有别名KC_PCMM（keycodes.h）；
• 数字与运算键沿用了 docs/keycodes_basic.md 中标准 Keypad 键码表（KC_KP_SLASH→KC_PSLS、KC_KP_ASTERISK→KC_PAST等），基于 HID Keyboard/Keypad Usage Page (0x07) 定义，因此这些键在现代操作系统下同样具备 Keypad 语义（如 Num Lock 开启时输入数字、关闭时可能触发 Home/End/方向等双功能，见 docs/keycodes_basic.md）。

由于default键位只有一个 0 号图层，若想在此基础上增加自定义图层（例如按住 Esc 切换为符号层），可直接在keymaps/default/keymap.c中追加[1] = LAYOUT(...)定义，QMK 会自动将其识别为附加层。

四、硬件接线与矩阵配置：COL2ROW 六列四行

keyboard.json中记录了这块 Apple PCB 在 QMK 下的完整硬件定义，是复刻硬件改装的直接依据：

"matrix_pins": { "cols": ["D1", "D0", "D4", "C6", "D7", "E6"], "rows": ["B0", "B2", "D2", "D3"] }, "diode_direction": "COL2ROW", "processor": "atmega32u4", "bootloader": "caterina"

解读要点：

• 矩阵规模：6 列 × 4 行，共 24 个交叉点，恰好对应 24 颗按键，说明键盘没有冗余矩阵位。
• 二极管方向：COL2ROW，即二极管阴极朝向列线（从列读入、行输出驱动），这是接线转接板时最重要的方向约束——接反会导致整块键盘无响应。
• 主控与引导：atmega32u4+caterina（Arduino Micro 的默认引导程序），编译产物可通过 Arduino 标准的 DFU/串口方式烧录。
• USB 标识：VID0xFEED、PID0x0000，设备版本0.0.1，device_version字段可自行调整。
• 功能开关：command: true（调试命令）、console: true（调试输出）、extrakey: true（媒体键）、mousekey: true（鼠标键）均已启用，而bootmagic与nkro关闭，保持轻量。

keyboard.json中的LAYOUT定义同时给出了每个物理按键在矩阵中的位置（matrix: [行, 列]）与屏幕坐标（x/y），例如顶行7位于矩阵[0,5]、8位于[3,2]、9位于[3,3]，底行长条0键还带有"w": 1.5的宽度属性。这套信息一方面驱动 QMK 的矩阵扫描逻辑，另一方面也可用于 docs/reference_info_json.md 描述的可视化布局生成。

五、编译与烧录：从源码到固件

确保构建环境就绪后，在仓库根目录执行：

make converter/numeric_keypad_iie:default

• converter/numeric_keypad_iie是键盘目录的路径标识；
• default即 keymaps/default 键位图。

如需生成并烧录到 Arduino Micro，可追加:flash目标（make converter/numeric_keypad_iie:default:flash）。首次接触 QMK 的用户，建议先阅读 docs/getting_started_introduction.md 完成开发环境搭建，再参考 docs/getting_started_make_guide.md 了解 Make 目标语法；新手可从 docs/newbs.md 的入门路线开始。

编译产物的验证方式也很直接：由于keyboard.json启用了console功能，可以在固件运行后通过 QMK 的调试命令查看矩阵扫描与键值上报，确认 DB15 转接板各引脚与矩阵定义一一对应。

六、改造要点总结

1. 硬件改造：Numeric Keypad IIe 无板载控制器，DB15 线缆 → 转接板 → Arduino Micro（ATmega32U4）是官方参考路径，接线必须严格对照keyboard.json的 6 列 4 行引脚表。
2. 固件配置：COL2ROW二极管方向、caterina引导程序决定了板级行为；default键位图忠实复刻原装键帽功能，无需额外配置即可使用。
3. 历史细节：Print 键输出?不是疏忽，而是对 AppleSoft BASIC 中?=PRINT简写的原样保留，这也让默认键位具有档案级的历史还原意义。
4. 扩展空间：24 键矩阵、单一图层只是起点，后续完全可以在LAYOUT基础上添加自定义功能层、宏或组合键，把这块 40 年前的键盘变成现代生产力小键盘。

通过本文的键位对照表、矩阵接线说明与构建命令，你可以独立复现或进一步改造这一复古 USB 转换项目。

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