单手操作电脑时真正打断节奏的往往是手掌在键盘和鼠标之间来回移动。输入几个字、移动指针、点击按钮再把手放回键位每次切换都要重新寻找位置。把轨迹球、滚轮和鼠标按键放进键盘首先解决的是这个动作链路。这款单手键盘采用 STM32G431CBU6提供左手小型、左手大型和右手大型三个版本。主体使用 57 颗键轴字符区之外还集成鼠标与方向控制。它的工程价值在于将不同类型的输入统一送入 QMK再经 USB 交给电脑。按键是离散状态轨迹球是位移增量滚轮是带方向的脉冲三者需要各自采集最后在报告层协同。三条输入路径汇入同一个 USB 设备字符键与鼠标按键通过矩阵采集轨迹球通过 SPI1 读取滚轮编码器使用独立的两根信号线。这样拆分后键位多少、指针如何移动以及滚轮如何转动分别由矩阵、指点设备驱动和编码器模块处理互相之间不需要借用对方的扫描时序。大键盘把 Type-C、滚轮、轨迹球和方向键做成独立小板主板上的 CON1 至 CON4 用于区分模块。小型版本的 Type-C 则位于控制板上。模块化既方便适应外壳也让故障定位更直接。字符输入正常而指针不动时应优先检查轨迹球支路而不是从整个键盘矩阵重新查起。供电同样要分清边界。控制板中能看到 ME6211C33M5G-N 稳压器将 VBUS 转为 3.3V供主控与相关电路使用。轨迹球小板的接口标注也是 3.3V。USB 上的 5V 和器件逻辑电平不能混为一谈排线插错位置可能同时影响供电和通信。Type-C 的两路 CC 各有 5.1kΩ 下拉使接口以受电端身份被识别这也是兼容 C-C 连接需要具备的硬件条件。用 20 根扫描线管理分散的按键共用配置给出了 6 行、14 列的矩阵使用 20 根 GPIO 覆盖最多 84 个坐标。实际布局并没有填满这些位置。以小型左手版本为例默认布局列出 64 个有效坐标其中还包括鼠标按键、滚轮按压和方向键不能把矩阵容量直接当成键轴数量。diode_direction:ROW2COL,matrix_pins:{cols:[A0,A1,A2,C4,B0,B1,B2,B7,B5,B3,B10,C11,C10,A15],rows:[B12,B15,C6,B13,B14,A8]}这里的ROW2COL描述二极管允许电流从行流向列不代表固件逐行拉低。QMK 对这种方向的处理是逐列选通将当前列拉低同时读取带上拉的行输入。某个按键闭合后对应行经开关与二极管连到低电平列行输入由高变低软件据此置位该坐标。逐键串联的二极管阻断了不希望出现的反向路径避免多个按键同时闭合时电流绕经其他开关形成虚假的按键位置。机械触点本身仍会抖动所以电气隔离之后还需要消抖不能把二极管和消抖看成同一件事。物理位置与发送给电脑的键值也相互独立。布局文件决定一个键对应哪个矩阵坐标键映射再决定这个坐标发送字符还是鼠标按钮。例如默认映射中的QK_MOUSE_BUTTON_1与普通字符键一样来自矩阵但最终进入鼠标按钮报告。调整外壳位置时应先保持坐标、电路与键映射一致不能只改键帽上的文字。轨迹球先变成位移再变成光标轨迹球小板采用 ADNS-9800 光学传感器。球面相对传感器运动后器件输出沿两个方向的相对位移主控不需要计算球的绝对角度。球座则负责维持稳定的球面距离与转动阻力机械结构会直接影响位移采集是否连续。固件中的接口定义与硬件网名对应如下。片选决定本次访问由哪个外设响应SCK 提供传输节拍MOSI 发送命令与配置MISO 返回状态和位移。MOTION 是运动提示线不承载坐标数据。#defineSPI_DRIVERSPID1#defineSPI_SCK_PINA5#defineSPI_MISO_PINA6#defineSPI_MOSI_PINA7#definePOINTING_DEVICE_CS_PINA4#definePOINTING_DEVICE_MOTION_PINA3#definePOINTING_DEVICE_TASK_THROTTLE_MS1#definePOINTING_DEVICE_INVERT_X1这段配置把任务节流设为 1ms但它只是固件调度参数不能据此宣称整机端到端延迟为 1ms。X 轴反向则用于适配传感器与球体的实际安装方向。如果只在电脑里调鼠标速度无法修正传感器坐标轴接反造成的方向错误。初始化阶段会从用户配置区取出灵敏度初始化传感器再写入 CPI。voidpointing_device_init_kb(void){wait_ms(10);user_config.TrackballDPIeeconfig_read_user();wait_ms(10);adns9800_init();wait_ms(10);pointing_device_set_cpi(user_config.TrackballDPI);}CPI 表示每英寸对应的计数决定相同球面位移产生多少计数。项目把默认值设为 3000用户调节函数按 1000 递增或递减限制在 1000 至 8000。这里改变的是传感器灵敏度电脑端的指针加速仍会进一步影响屏幕上的移动距离。一个容易忽略的细节是代码中定义了DPI_UP和DPI_DOWN并写好了按下事件的处理但所检查的小型版本默认键位表没有把这两个自定义键码放到可按的位置。因此存在调节函数不等于默认布局已经提供调节快捷键。需要这一功能时还要补上明确的键位或功能层。连续读取位移时字节顺序不能反ADNS-9800 驱动通过 Motion Burst 连续取得运动状态与位移。命令发出后程序等待规定的间隔再读取状态。如果运动标志有效先跳过观察字节然后按低字节、高字节的顺序读取 X、Y 增量。uint8_tdelta_x_lspi_read();uint8_tdelta_x_hspi_read();uint8_tdelta_y_lspi_read();uint8_tdelta_y_hspi_read();report.xconvertDeltaToInt(delta_x_h,delta_x_l);report.yconvertDeltaToInt(delta_y_h,delta_y_l);低字节先从总线上到达组装数值时高字节却要放在高 8 位两者并不矛盾。驱动随后将这组补码解释为有符号增量否则反方向移动就可能被错误当作很大的正数。数据再经过 HID 位移范围约束形成鼠标报告由 USB 发送给主机。因此排查轨迹球故障应沿着数据流推进。先检查 3.3V 与地再确认片选、时钟和收发线之后查看运动状态与增量是否变化最后检查方向变换和主机报告。若 SPI 没有正确返回数据反复修改 CPI 无法解决问题若增量已经正常而光标方向错误则应检查坐标方向配置。这里还有一个软件边界。传感器驱动允许通过弱函数提供 SROM 数据默认弱实现返回长度为零初始化会走无外部 SROM 上传分支。修改驱动或更换传感器时需要连同初始化条件一起核对不能只迁移四根 SPI 线与一个驱动名称。滚轮转动与按下走不同的链路滚轮的 A、B 两相连接 PA9 和 PA10两路信号相位的先后关系用来判断方向。共用配置中的ENCODER_RESOLUTION为 2决定累计多少编码状态变化才产生一次逻辑动作。分辨率与实际编码器不匹配时就可能出现一格触发次数不合适或动作不连贯的问题。constuint16_tPROGMEM encoder_map[][NUM_ENCODERS][NUM_DIRECTIONS]{[0]{ENCODER_CCW_CW(MS_WHLU,MS_WHLD)}};默认映射将两个方向转换为滚轮上翻与下翻。滚轮按压却是另一只机械开关经二极管进入按键矩阵并映射为鼠标中键。编码器旋转与开关按下共用一个外观部件却属于不同采集通道所以“能滚动但不能中键点击”时应检查开关、二极管和矩阵连接而不是只盯着 A、B 两相信号。先验证裸板再把手感装进外壳大型版本的键盘板采用 1.6mm 四层 FR-4小型版本采用 1.6mm 双层板。两种规格的轴体与结构不同左右大型版本也并非完全镜像采购与装配时需要让 PCB、固件和模型对应到同一版本。排线使用 0.5mm 间距、8P 接口装配要求是反向排线。判断连接方向时既要看 CON 标识也要看连接器接触面不能只凭排线颜色。首次烧录可按住控制板背面标有 B 的按钮再接入 USB进入 STM32 DFU已有相应固件后才可使用按住 ESC 上电的更新路径。比较稳妥的装配顺序是先连接模块只装 3 至 5 颗轴体、滚轮和轨迹球完成基本功能检查再装外壳、填充棉与其余键帽。这样能把电路问题与机械干涉分开定位。观察到的现象优先检查的位置判断依据USB 无法识别数据线、供电、D 与 D−、烧录状态设备尚未进入正常枚举阶段整行或整列按键失效对应扫描 GPIO、连接器与走线多个异常键共享同一根扫描线个别按键不稳定轴体接点、焊点与二极管局部触点问题常先于整体扫描问题指针方向相反传感器安装方向与轴向配置有位移说明采集链路已部分工作滚轮正常而中键无效按压开关与矩阵通道旋转与按下由不同电路采集轨迹球采用直径 25mm 的 PTFE 球体球座中安装 6 颗直径 2mm 的 PTFE 支撑球。球体是否受力均匀、打印件是否有毛刺都应在锁紧外壳前检查。电子部分能够稳定识别输入是装配的前提机械部分让输入动作轻、稳、连续才决定这套单手布局能否长期使用。把键盘与鼠标整合到一只手的活动范围内需要同时处理矩阵扫描、光学位移、编码器方向和机械支撑。STM32G431 将这些输入分路采集QMK 再把它们组织成电脑能识别的报告。沿着供电、信号、固件与结构逐层核对既能理解这款键盘为什么这样设计也能更有把握地修改键位、替换模块与调整手感。