可编程指纹扩展坞键盘

1.1 系统架构

系统按 USB 数据链路、CH32V203 键盘控制链路 和 电源链路 拆分。USB-C 是整机唯一的上行接口，接入电脑后，CH334P 将 USB 数据分配给 CH32V203 HID 设备、2 个 USB-A 扩展口和指纹模块；CH32V203 负责按键扫描、编码器读取、RGB 指示和配置存储。

连接方式与无线设计取舍

从用户视角看，它是一把 USB-C 有线键盘；从硬件视角看，它是通过 USB Hub 汇聚到电脑的一组 USB 设备：键盘 HID、USB 指纹模块和两个可外接设备的 USB-A 下行口。这个结构决定了它不适合简单做成蓝牙、2.4G 或三模键盘。常见无线键盘只需要把按键 HID 数据发给电脑，而本项目还要让电脑枚举指纹模块、识别外接 U 盘或鼠标接收器，并管理两个 USB-A 下行口。USB Hub 本身必须有一条真实的 USB 上行链路连接电脑，才能完成这些标准 USB 设备的通信和供电。

如果只把按键部分改成无线，指纹模块和 USB-A 扩展口仍然需要 USB-C 线连接电脑，产品会变成“无线键盘 + 有线扩展坞”的混合形态。这样不仅会增加电池、充电、无线配对、状态提示和固件逻辑，还不能真正摆脱线缆。基于这个取舍，本项目选择用一根 USB-C 数据线同时完成键盘通信、指纹识别、USB 扩展和整机供电。

数据链路

键盘控制链路

电源链路

1.2 原理图设计

原理图分为三部分：第一部分为键盘矩阵与主控，第二部分为 USB 2.0 Hub 与指纹接口，第三部分为电源、滚轮和 RGB。这里按原理图中的实际电路说明实现细节，不再重复上一节的系统框图。

第一部分：键盘矩阵与主控

主控采用 CH32V203C8T6，属于 WCH CH32V203 系列增强型低功耗 RISC-V MCU。该芯片基于青稞 V4B 内核，最高支持 144MHz 系统主频，内置 64KB Flash 和 20KB SRAM，并带有 USB 2.0 全速设备接口，能够满足本项目的键盘 HID 通信、按键扫描、配置处理、编码器读取和 RGB 控制需求。从选型角度看，它可以作为 STM32F103C8T6 的 P2P 替代方案，同时综合性能约为后者的 3 倍。时钟由 MCU 内部时钟源完成配置，可生成 USB 通信所需的 48MHz 时钟。本应用无电池供电，VBAT 与 VDD 同源供电。

固件升级方面，CH32V203C8T6 在复位时会检测 BOOT0 状态。当 BOOT0 拉高后复位，芯片会进入系统自带的固件升级模式，此时可通过 USB 连接上位机更新固件，便于量产烧录和后续维护。

本项目使用 3 片 SN74HC165PW 串联扩展按键输入，每片提供 8 路并行输入，合计 24 路；其中 22 路用于按键，1 路用于滚轮按下开关，共实际使用 23 路，剩余 1 路固定上拉。如果使用传统键盘矩阵扫描，23 路输入通常需要 10 个 MCU IO（例如 4x6 或 5x5 矩阵）；改用移位寄存器后，只需要 SPI 时钟、数据输入、并行装载和使能等 4 个 IO 即可完成读取。SN74HC165PW 是 8 位并行输入、串行输出的移位寄存器，PW 为 TSSOP-16 封装，适合把多路开关量输入转换为串行数据。由于每个按键都是独立输入，不存在矩阵扫描中的鬼键和按键冲突问题，也不需要为每个按键额外串联二极管，从而降低物料成本和 PCB 布局难度。MCU 通过硬件 SPI 时序读取移位寄存器的串行输出，从而完成整组按键状态扫描。

此外还预留了外部 Flash，当前版本暂未使用，实际固件空间依赖 MCU 内部 Flash，因此该器件可不贴装。后期如果需要增加功能或存储空间，可以焊接外部 Flash 进行扩展。

第二部分：USB Hub 与指纹接口

USB Hub 以 CH334P 为核心。CH334P 属于 WCH CH334/CH335 系列 USB 2.0 HUB 控制器，可将 1 路 USB 上行扩展为 4 路 USB 下行，支持 USB 2.0 高速、全速和低速设备，并支持高性能 MTT 模式，适合扩展坞和嵌入式 USB 扩展场景。本项目使用它把 USB-C 上行连接分配给键盘 MCU、指纹模块和两个 USB-A 扩展口，实现单线连接电脑的同时保留外设扩展能力。电路中 CH334P 使用 12MHz 晶振 X1，芯片内部集成晶振匹配电容，外围无需额外放置两颗负载电容，可减少器件数量并简化布局。USB-C 口 USB1 的 CC1/CC2 各接 5.1k 下拉电阻，用于 Type-C 设备识别；省略后在部分双 C 线连接场景下可能无法正常取电，所以不建议省略。

两个 USB-A 扩展口由 CH334P 的下行端口引出，供外接 U 盘、接收器、读卡器等低功耗 USB 外设使用。Hub 供电侧配置了大容量电容和高频退耦电容，用于缓冲外设插拔时的电压波动，提升 USB 扩展口工作稳定性。

指纹模块同样接入 CH334P 的下行端口，在电脑侧表现为独立 USB 指纹设备。键盘 MCU 只负责键盘控制，不参与指纹图像采集、认证或数据处理，因此指纹功能可以直接依赖操作系统和指纹模块自身驱动完成。

第三部分：电源、滚轮与 RGB

电源由 USB-C 输入 5V，经前级保护后生成系统 VBUS，再供给 USB Hub、USB-A 扩展口、指纹模块、RGB 和 3.3V LDO。前级保护预留了两种实现方式：推荐使用 CH213K 作为理想二极管/负载开关方案，提供反灌、过流、短路和过温保护，适合外设插拔频繁的扩展坞场景；如果只追求低成本，也可以改用肖特基二极管方案，但保护能力会相应降低。两种方案为二选一设计，实际焊接时不能同时贴装。

ME6211C33M5G-N 负责将 VBUS 稳压为 3V3。ME6211 系列是 CMOS 低压差 LDO，具备低噪声、高电源纹波抑制、低静态功耗和较快启动等特点，3.3V 型号最大输出电流可达 500mA，并兼容低 ESR 陶瓷电容。本项目用它为 CH32V203、CH334P 和指纹模块提供稳定 3.3V 供电；LDO 输入/输出侧布置大容量 MLCC 电容，用于降低 USB 外设插拔带来的电压波动。

滚轮使用 11mm 高度的增量式旋转编码器。A/B 相分别接 ENCODE_A / ENCODE_B，按下动作作为普通开关量进入 74HC165 扫描系统。编码器的 A 相、B 相串联 200Ω 电阻，用于限制触点切换瞬间由输入电容和寄生电容带来的冲击电流，减小触点烧蚀和异常短接对后级 IO 的影响，从而提升滚轮长期使用的可靠性。

RGB 指示灯采用单颗 WS2812 灯珠，由 VBUS 供电，LED_DIN 作为单线数据输入。这里不做大面积氛围灯，而是把灯光作为状态指示使用，用于区分当前映射层、提示设备状态和显示基础灯效；用户可在 KeyWine 中关闭灯光，硬件装配时也可以选择不贴装该器件。

1.3 PCB 设计

PCB 采用 2 层板设计，裸 PCB 尺寸控制在嘉立创 10×10cm 免费打样范围内，尽量兼顾成本、可制造性和后期装配便利性。板上集成键盘主控、USB Hub、指纹接口、电源保护、滚轮和 RGB 指示灯等电路，全部贴片器件都可以在嘉立创 SMT 完成贴装。考虑到绝大部分器件位于 PCB 背面，实际打样时建议只选择背面经济型 SMT，正面仅有 4 个器件，可后续手工焊接；如果选择双面器件贴装，则需要使用标准型 SMT，费用会明显增加。

布局要点

PCB 布局以“少绕路、短连接、少过孔”为基本原则，优先让相关器件靠近对应接口和输入区域，减少跨区域走线。

• 顶层只保留滚轮、滚轮按键、RGB 灯及其 100nF 退耦电容，其余贴片器件全部放在背面，方便焊接、检查和装配。
• 指纹 FPC 连接器放在背面，PCB 开槽给排线留出通道，指纹模块排线从正面穿到背面连接。
• USB-C 和两个 USB-A 扩展口布置在 PCB 边缘，方便外壳开孔和外设插拔；USB Hub 区域靠近接口布置，周围预留 VBUS 缓冲电容。
• 22 颗热拔插轴座按 5×5 操作区域排列，74HC165 移位寄存器放在按键区背面附近，方便就近接入各路按键信号，并把扫描数据汇总送到 MCU。

PCB 设计截图：

PCB 位号图：

1.4 按键布局

5×5 紧凑网格布局，包含 22 颗热拔插轴体、滚轮模块（上滚/下滚/按下）和指纹识别模块，合计 24 个可独立编程的输入项。

物理布局

软件部分分为 KeyWine 控制软件和键盘固件。KeyWine 负责可视化配置，覆盖 Windows / macOS / Linux 三平台；固件运行在 MCU 主控上，实现输入扫描、协议上报、RGB 灯效和配置存储。配置写入设备后，键盘独立运行，无需 KeyWine 后台挂起。

2.1 KeyWine 控制软件

跨平台桌面应用，提供直观的图形化键盘配置界面。通过 USB HID 与键盘通信，自动检测设备连接状态，校验固件版本兼容性。

按键映射

简单说：按键映射就是给每个按键"分配任务"。按下某个键时，它执行什么操作（比如 Ctrl+C 复制、打开浏览器、播放音乐），都由你决定。你可以保存多套方案，切换场景时一键切换。

10 层映射方案：每层 24 个输入项（22 轴 + 滚轮上/下 + 滚轮按下），均可映射为标准键值、组合键（含修饰键）、多媒体键、鼠标按键或鼠标滚轮。支持普通触发（按下触发、松开取消）和切换触发（按下触发、再按取消）两种模式。滚轮上滚、下滚、按下作为独立输入项，与按键统一配置，随映射方案一起导入导出。每层可绑定 RGB 灯光方案，切换映射时自动同步灯光。可视化 5×5 矩阵布局，点击按键弹出编辑面板，实时显示当前按键状态，修改后写入设备。

RGB 灯光系统

10 组灯光方案，每组 5 个颜色节点 + 亮度控制。HSV 色相环 + 饱和度/亮度平面选色，实时渐变预览。内置「色彩轮回」预设一键应用。支持关闭 RGB / 切换方案，灯光开关控制。与映射层和宏绑定，切换映射或触发宏时自动切换灯光。

宏系统

简单说：宏就是"一键执行一连串操作"。比如你录制一组按键动作——先打开浏览器、再输入网址、按下回车，以后只要按一个键，这串操作就会自动依次完成，省去重复劳动。

10 个宏槽位，实时录制按下、松开、修饰键、等待时间。录制过程中支持暂停/继续（暂停时间不计入）。提供可视化时间轴和步骤列表，可缩放查看、手动添加/编辑/删除事件。合并阈值可调（录制时相邻按键间隔不超过阈值即视为同时按下）。每个宏槽位可在 5×5 矩阵上点选触发按键组合（多键同时按下触发），并绑定 RGB 灯光。所有配置写入设备 Flash，断电不丢失。

键盘设置

键盘设置：支持映射切换（Keymap FN）和灯光切换（RGB FN）两种 FN 快捷键功能，在 5×5 矩阵上逐键点选配置，24 位掩码独立控制，冲突检测自动提示。可设置启动默认映射层、默认灯光方案、兼容模式切换（引导协议 / 位图协议）、始终开启 RGB 灯效、心跳上报。所有设置写入 Flash，断电持久化。

配置管理

配置导入导出：支持单项导出/导入（按键映射、宏、RGB 灯光、键盘设置）和一键全量导出/导入。导出的配置文件可直接分享给其他用户，对方导入即可使用相同按键映射方案，轻松实现配置共享。导入时自动检测版本并适配，向后兼容旧版本配置文件。

固件升级

固件升级：按住滚轮插入数据线即可进入升级模式，KeyWine 自动检测设备并完成固件更新。无需额外烧录器，用户可自行获取最新功能与修复。

2.2 固件核心能力

全键无冲设计

键盘同时按下多个按键时，传统矩阵扫描方案会因为行列交叉导致信号串扰，产生「鬼键」——系统误判未按下的按键被按下，或者漏掉实际按下的按键。这在游戏和快捷键组合场景中会导致误操作。市面常见键盘多为 6 键无冲（6KRO），这是由 USB HID 引导协议的固定上报格式决定的——协议规定每次最多上报 6 个键值，超过 6 个按键同时按下时多出的按键会被丢弃。

本项目从硬件层面彻底解决了这一问题。按键通过 SN74HC165PW 移位寄存器独立采集，每个按键都是单独输入通道，不走传统键盘矩阵扫描，因此从根本上不会产生矩阵鬼键，也不需要为每个按键额外串联二极管。22 颗轴体 + 滚轮上/下/按下，合计 24 个输入项均可同时按下并被正确识别。

软件上，固件同时支持 HID 引导协议和位图协议两种上报方式：

引导协议（Boot Protocol）

这是 USB HID 规范中定义的基础键盘协议，设计初衷是让键盘在操作系统驱动加载之前就能工作（例如 BIOS 设置界面）。协议规定每次上报固定 8 字节：1 字节修饰键状态 + 6 字节键值，因此最多只能同时上报 6 个普通按键。优点是所有操作系统和 BIOS 原生支持，无需额外驱动，兼容性最好；缺点是超过 6 个按键同时按下时，多出的按键会被丢弃。

位图协议（Bitmap Protocol）

这是 HID 规范中的扩展键盘协议，不再限制键值数量，而是用位图（bitmap）方式按位标记每个按键的按下/释放状态。每个按键对应位图中的一个 bit，所有按键的状态可以同时上报，因此能实现真正的全键无冲。主流操作系统（Windows、macOS、Linux）均支持此协议，但部分老旧主板的 BIOS 可能无法识别。

用户可通过 KeyWine 在两种协议之间动态切换——需要进入 BIOS 或使用老旧系统时选择引导协议，日常使用和游戏场景切换到位图协议以获得全键无冲体验。

按键滤波设计

机械按键在按下和释放的瞬间，触点会产生微小的弹跳和抖动，导致信号在高低电平之间快速跳变。如果不加处理，一次按键可能被识别为多次触发，影响使用体验。

本项目采用 3kHz 采样 + 2/3 多数投票 + 连续 2 次确认 的两级滤波策略：

第一级：多数投票滤波

每毫秒对所有按键采样 3 次，形成 3 个采样窗口。对每个按键，使用布尔代数 (a & b) | (b & c) | (a & c) 进行 2/3 多数投票——只要 3 次采样中有 2 次一致，就认为该次采样有效。这种方式可以在单条指令内同时处理 8 个按键，效率极高。

// 第一级：2/3 多数投票，布尔代数一次性处理 8 个按键
for (byte_idx = 0; byte_idx < HC165_COUNT; byte_idx++) {
    sample0 = key_sample_buffer[0][byte_idx];  // 第 1 次采样
    sample1 = key_sample_buffer[1][byte_idx];  // 第 2 次采样
    sample2 = key_sample_buffer[2][byte_idx];  // 第 3 次采样

    // 至少 2 个采样为 1 的位保留为 1
    key_filtered_state[byte_idx] = (sample0 & sample1)
                                 | (sample1 & sample2)
                                 | (sample0 & sample2);
}

第二级：状态机消抖

在多数投票之后，每按键维护一个独立的状态机，要求连续 2 次采样结果一致才触发状态转移。从"未按下"到"按下确认"需要连续 2 次检测到低电平，从"按下"到"释放确认"同样需要连续 2 次检测到高电平。两层过滤共同作用，既消除了机械抖动，又保证了按键响应的实时性。

// 第二级：每键独立状态机，连续 2 次确认才转移
for (key_idx = 0; key_idx < TOTAL_KEYS; key_idx++) {
    byte_idx = key_idx >> 3;
    bit_idx  = key_idx & 0x07;
    key_level = (key_filtered_state[byte_idx] >> bit_idx) & 1;
    state = &key_debounce_state[key_idx];

    switch (state->state) {
    case KEY_DEBOUNCE_IDLE:              // 空闲状态
        if (key_level == 0) {            // 低电平有效 = 按下
            state->sample_count++;
            if (state->sample_count >= 2) {
                state->state = KEY_DEBOUNCE_PRESSED;
                state->sample_count = 0;
            }
        } else {
            state->sample_count = 0;     // 不一致，重置计数
        }
        break;

    case KEY_DEBOUNCE_PRESSED:           // 按下状态
        if (key_level == 1) {            // 高电平 = 释放
            state->sample_count++;
            if (state->sample_count >= 2) {
                state->state = KEY_DEBOUNCE_IDLE;
                state->sample_count = 0;
            }
        } else {
            state->sample_count = 0;     // 不一致，重置计数
        }
        break;
    }
}

RGB 渐变动画

RGB 灯效采用渐变动画实现，支持 5 个颜色节点之间的平滑过渡。每组灯光方案包含 5 个颜色路径点，固件在相邻颜色之间进行线性插值，每段渐变 600 步，整体循环播放。

渐变计算使用定点数运算而非浮点数。CH32V203 没有硬件浮点单元（FPU），浮点运算需要软件模拟，一次浮点乘法可能需要上百个时钟周期；而整数运算只需 1 个周期。定点数的做法是：颜色分量左移 8 位转为整数（相当于放大 256 倍），步进值同样用整数表示，运算完成后右移 8 位还原。精度对于 0~255 的颜色值完全够用，性能却提升了一个数量级。

RGB 更新与按键扫描解耦：按键扫描运行在 3kHz 中断中，RGB 渐变每 5ms 更新一次，在主循环中执行。两者互不阻塞，保证按键响应不受灯效影响。

渐变计算还采用了预计算 + 增量更新的策略。每段渐变开始时，固件会预计算好步进值（step_r、step_g、step_b），这一步涉及除法运算，开销较大；但只在每段开始时执行一次。之后每帧更新只需做简单的加法（cur_r += step_r），600 步渐变中只有 1 次除法，其余 599 次都是加法。

// 渐变核心：定点数线性插值
cur_r += step_r;                    // 整数步进，
step_r = (end.r - start.r) << 8 / 600
cur_g += step_g;
cur_b += step_b;

out->r = (uint8_t)(cur_r >> 8);    // 右移还原为 0~255
out->g = (uint8_t)(cur_g >> 8);
out->b = (uint8_t)(cur_b >> 8);

本章提供完整的复刻指南，帮助你从零开始制作一台相同的可编程指纹扩展坞键盘。按照以下步骤操作，即可完成硬件组装、固件烧录和软件配置。

3.1 PCB 打样与贴装

3.2 外壳配件清单

PCB 板上的全部贴片器件（含主控、USB Hub、移位寄存器、LDO 等）已在仓库 BOM 文件中列出，此处不再重复。以下仅列出装配时需要额外准备的配件：

3.3 指纹模块选型与引脚定义

本项目使用的是成品 USB 指纹识别模块，而不是裸指纹传感器。模块通过 FPC 排线连接到 PCB，在电脑侧会作为独立 USB 指纹设备枚举；键盘主控不参与指纹图像采集、模板存储或认证流程。

复刻时建议直接采购上图所示的同款模块，可去 tb 或海鲜市场按图片和下方规格核对购买。这个位置受外壳开孔、模块外形尺寸、排线出线方向和 FPC 引脚顺序共同限制，可替代空间很小；即使其他 USB 指纹模块功能相近，也可能因为尺寸、触点面或 D+/D- 顺序不同而无法直接安装。模块本身还需要支持目标系统，例如 Windows Hello 或 Linux libfprint。

当前 PCB 使用 FPC1 连接指纹模块，连接器为 8P、0.5mm 间距、翻盖式下接触 FPC 座；排线需使用 8P、0.5mm 间距、反向 FPC 排线，推荐长度 6cm；信号触点外的固定焊脚接地。采购时应按下表核对图示模块的排线定义，若改用其他模块，通常需要同步修改外壳结构、FPC 转接或 PCB 引脚定义。

3.4 工具准备

复刻外壳时需要额外准备以下工具：

• 老虎钳或尖头钳：用于剪断六角轴，将 40mm 六角轴裁切到装配所需长度。
• 电烙铁或注塑螺母专用热压工具：用于加热并压入热熔 / 注塑螺母，将螺母固定到外壳底盖的螺丝柱内。
• 小十字螺丝刀：用于拧紧 M2×6 沉头螺丝，将底板与上壳固定在一起。

3.5 固件烧录

建议在装配外壳之前完成固件烧录。裸板状态下可直接通过 USB 连接电脑进行基础功能测试（按键响应、指纹识别、RGB 灯光等），如果存在虚焊、元件方向贴反等问题，裸板排查和返修的成本远低于装壳之后。

3.6 装配流程

外壳由 7 个零件组成，完整拆解与装配步骤请参考随附的装配说明。