企业官网建设流程全解析

• 嵌入式
• 固件
• 驱动开发
• 硬件开发

converter/xmk是 QMK Firmware 仓库中一个特殊的 "键盘定义"：它不需要任何实体硬件，而是把任意 QMK 兼容 MCU 板变成一个由串口（Virtual Serial）命令行驱动的虚拟键盘。本文将从构建与刷写入手，深入keyboards/converter/xmk/目录下的源码，剖析其虚拟矩阵（CUSTOM_MATRIX = lite）、Shell 命令解析（xmk_shell）与 Bootloader 进入机制，并给出可直接复制使用的构建、刷写与调试命令。

一、这是什么：把 MCU 变成"串口驱动的键盘"

converter/xmk是 QMK 中对 𝑥MK 项目的键盘定义，其维护者为 Manna Harbour。与普通键盘固件不同，它的职责不是扫描物理矩阵，而是：

• 通过 USB 虚拟串口接收文本命令（如key press 3）；
• 解析命令后，把按键事件注入QMK 的矩阵扫描流程；
• 从而让 QMK 完整的事件处理管线（层切换、按键重映射、组合键、RGB 等）作用于外部传入的按键。

从 keyboards/converter/xmk/keyboard.json 可以看到它的"硬件配置"非常特殊：

• "processor": "atmega32u4"：以常见的 Pro Micro 兼容板（ATmega32U4）为目标平台；
• "bootloader": "caterina"：使用 Arduino Leonardo 风格的 Caterina Bootloader；
• "features": { "virtser": true }：启用 QMK 的虚拟串口（virtual serial）功能，这是接收命令的通道；
• "vid": "0xFEED", "pid": "0xD465"、"device_version": "1.0.0"：USB 描述符信息；
• 矩阵引脚cols与rows全部重复指向C2/D1：这不是真实的 GPIO 矩阵，而是为虚拟矩阵占位的"假引脚"，实际按键数据完全由串口命令提供。

二、构建与刷写：从源码到固件

converter/xmk在 QMK 中按普通键盘目标进行构建，构建前请先按 QMK 官方文档完成构建环境搭建与 make 指南的学习。

2.1 编译默认固件

make converter/xmk:default

该命令会编译 keyboards/converter/xmk/keymaps/default/keymap.c 中的默认键位，生成固件（如converter_xmk_default.hex）。

2.2 编译并刷写

make converter/xmk:default:flash

对于 ATmega32U4 与 Caterina Bootloader，QMK 会自动调用avrdude完成刷写。

2.3 不使用 qmk CLI、直接刷写预编译固件

若固件已预先编译好，在 Linux 上连接 Pro Micro 后可直接用avrdude刷入：

avrdude -p atmega32u4 -c avr109 -U flash:w:converter_xmk_default.hex:i -P /dev/ttyACM0

参数说明：

• -p atmega32u4：目标芯片型号；
• -c avr109：Caterina Bootloader 使用的 AVR109 协议；
• -U flash:w:converter_xmk_default.hex:i：将 hex 固件写入 flash，i表示 Intel HEX 格式；
• -P /dev/ttyACM0：设备串口路径，请按实际枚举结果调整。

三、进入 Bootloader 的四种方式

readme.md 列出了四种进入 Bootloader 的方式，前两种与本方案的"无实体键盘"特性直接相关：

1. Boot Shell 命令：向converter/xmk的 shell 发送boot命令，例如

   echo "boot" > /dev/ttyACM0

   这由 xmk_shell.c 中的xmk_shell()解析并调用reset_keyboard()实现。

2. 键位触发：在键位中映射QK_BOOT并在虚拟矩阵中触发该键，等效于触发复位进入 Bootloader。

3. 物理复位按键：短按 PCB 背面的复位按钮（部分板子是需短接的焊盘）。

4. Bootmagic 复位：按住矩阵 (0,0) 位置的键（通常是最左上角键或 Esc）的同时插入 USB。对虚拟矩阵而言，(0,0) 对应逻辑键 0，可通过key press 0之类命令按住它再重新枚举设备实现。

四、核心原理：虚拟矩阵与 Shell 命令

converter/xmk的精华在 rules.mk、xmk_matrix.c 与 xmk_shell.c 三个文件中。

4.1CUSTOM_MATRIX = lite：接管矩阵扫描

rules.mk 中：

SRC += xmk_matrix.c SRC += xmk_shell.c CUSTOM_MATRIX = lite

CUSTOM_MATRIX = lite是 QMK 提供的轻量自定义矩阵模式：固件不再扫描物理 GPIO，而是调用本键盘实现的matrix_scan_custom()。xmk_matrix.c 中：

bool xmk_changed = false; matrix_row_t xmk_rows[MATRIX_ROWS]; bool matrix_scan_custom(matrix_row_t current_matrix[]) { if (xmk_changed) { for (uint8_t row = 0; row < MATRIX_ROWS; row++) { current_matrix[row] = xmk_rows[row]; } xmk_changed = false; return true; } return false; }

即：只有外部命令使xmk_changed置位时，才把xmk_rows拷贝给 QMK 矩阵，返回true表示矩阵有变化；否则返回false，让 QMK 进入空闲路径，降低 CPU 占用。

写入矩阵的函数xmk_matrix_key(bool press, uint8_t key)按row = key / MATRIX_COLS、col = key % MATRIX_COLS计算键在矩阵中的位置，并用MATRIX_ROW_SHIFTER << col置位或清零对应位。它对外声明在 xmk_matrix.h。

4.2 Shell 命令：xmk_shell的解析逻辑

xmk_shell.c 定义了行缓冲（XMK_SHELL_LINE_LEN为 64 字节）与命令格式：

• key press N：按下键编号 N（十进制整数，strtol解析）；
• key release N：释放键编号 N；
• boot：调用reset_keyboard()进入 Bootloader；
• reset：调用soft_reset_keyboard()软复位。

对应源码中的宏定义：

#define XMK_SHELL_KEY "key " #define XMK_SHELL_KEY_PRESS "press " #define XMK_SHELL_KEY_RELEASE "release " #define XMK_SHELL_BOOT "boot" #define XMK_SHELL_RESET "reset"

命令通过虚拟串口到达：QMK 的 virtual serial 功能在收到每个字节时回调virtser_recv(const uint8_t ch)（该回调在 quantum/virtser.h 中声明、由virtser: true功能提供，键盘端实现）。virtser_recv以\r作为一行结束符，累积字符、以\0收尾后交给xmk_shell(line)执行。

注意：\n会被忽略（仅打印调试信息），因此实际发送命令时应以回车结束。

命令示例（Linux 下直写虚拟串口）：

# 按下键 3（对应默认键位中的逻辑索引 3） echo -ne "key press 3\r" > /dev/ttyACM0 # 释放键 3 echo -ne "key release 3\r" > /dev/ttyACM0 # 进入 Bootloader echo -ne "boot\r" > /dev/ttyACM0

4.3 键编号与键位布局的关系

键编号是矩阵中的线性索引，按行主序排列。默认键位使用LAYOUT_split_3x5_3社区布局（34 键、左右对称的 3 行 5 列 + 3 个拇指键），见 keymaps/default/keymap.c：

[0] = LAYOUT_split_3x5_3( KC_Q, KC_W, KC_F, KC_P, KC_B, KC_J, KC_L, KC_U, KC_Y, KC_QUOT, KC_A, KC_R, KC_S, KC_T, KC_G, KC_M, KC_N, KC_E, KC_I, KC_O, KC_Z, KC_X, KC_C, KC_D, KC_V, KC_K, KC_H, KC_COMM, KC_DOT, KC_SLSH, KC_ESC, KC_SPC, KC_TAB, KC_ENT, KC_BSPC, KC_DEL )

该布局的矩阵坐标定义在 keyboard.json 的LAYOUT_split_3x5_3中（共 34 个键位条目），并注册为社区布局split_3x5_3（参考 layouts/community/split_3x5_3/readme.md），因此你可以复用该社区布局下其他键盘的键位文件来快速定制自己的converter/xmk键位。按下"逻辑键 3"即对应键位表中第 4 个键（KC_P）。

五、调试与自定义：XMK_DEBUG 开关

converter/xmk预留了XMK_DEBUG编译开关，方便排查虚拟矩阵与 shell 行为：

• post_rules.mk 中，当XMK_DEBUG = yes时自动启用CONSOLE_ENABLE = yes并追加OPT_DEFS += -DXMK_DEBUG；
• config.h 在XMK_DEBUG下定义DEBUG_MATRIX_SCAN_RATE（开启矩阵扫描速率日志）；
• xmk.c 在XMK_DEBUG下于keyboard_post_init_kb()中打开debug_enable、debug_matrix、debug_keyboard，从而输出完整调试信息。

启用方式：在命令行追加变量即可，例如

make converter/xmk:default XMK_DEBUG=yes

此时 xmk_matrix.c 的xmk_matrix_key()与 xmk_shell.c 中的dprintf日志（如xmk_matrix_key: press: true, key: 3、xmk_shell: line: 'key press 3'）会输出到 CONSOLE，配合 QMK 的串口监视即可观察每一次按键注入与命令解析过程。

六、典型使用场景与限制

适用场景：把任意 QMK 兼容 MCU 板（Pro Micro 等）作为"可编程 HID 键盘引擎"，由上位机脚本通过串口动态发送按键——例如自动化测试键盘固件行为、为特种输入设备（眼动、脚踏、触摸屏）生成键盘事件，或作为研究 QMK 矩阵/事件管线的实验台。

需要明确的前提与限制：

• 该方案不扫描任何真实矩阵，实体按键需要自行映射为串口命令；
• 依赖virtser虚拟串口，因此要求操作系统能枚举出 CDC 串口设备，且命令以\r结尾；
• 刷写依赖 Caterina Bootloader（Pro Micro 常见），其他 Bootloader 需要修改keyboard.json中的"bootloader"字段；
• 键编号基于固定MATRIX_ROWS × MATRIX_COLS计算，超出范围（row >= MATRIX_ROWS）的键编号会被 xmk_matrix.c 静默忽略，属于预期行为。

七、小结

converter/xmk展示了一种"串口即键盘"的极简架构：30 行左右的矩阵注入代码加上 40 行左右的 shell 解析代码，就把 QMK 完整的事件处理管线开放给了外部程序，是理解 QMK 矩阵层、virtual serial 与 Bootloader 流程的绝佳参考实现。

• 嵌入式
• 固件
• 驱动开发
• 硬件开发