三模键盘切换时怎样避免卡键并把电量判定做稳
三模键盘切换时怎样避免卡键并把电量判定做稳
三模键盘最容易被忽略的地方,不是把 USB、蓝牙和 2.4G WiFi 都接上,而是切换链路时如何处理“旧连接还按着一个键”的状态,以及无线工作几小时后电量判断是否会把瞬时压降误判成关机。
本文以 SimpleKey-Regression 的 ESP32-S3-WROOM-1 方案为对象,重新核对同一版本的 EDA 预览、PCB 正反面、Layout 顶底面和固件源码,抽出三条可以迁移到其他键盘和输入设备的工程规则:
- 链路切换必须是有边界的事务,切换窗口禁止继续发 HID 报告,成功后清空旧通道的按住键集合。
- 电池电压要先经过分压、ADC 校准和连续采样确认,再把低电告警与关机动作分开。
- 宣称“全键无冲”要看 HID 报告描述符和发送缓冲区,不能只看 README 的功能表。
文中的状态模型是独立编写的 C11 示例,验证的是状态转换和保护契约;它没有冒充项目固件,也没有把主机仿真结果写成整机实测。
先确认硬件和版本边界
项目主控为 ESP32-S3-WROOM-1,键区采用 4×5 矩阵,实际布置 19 个按键和一个 2u 空格,旁边是 EC11 旋钮。电池是带保护板的 103450 锂电池,标称 2000 mAh;充电和有线通信共用 Type-C 接口。

图1 项目主图。它只能证明项目页面展示的装配状态,不能替代本文对 EDA 和源码的核对。
项目页当前可见 Board1、固定板和 PCB1 的原理图/PCB 预览,BOM 里有器件、封装、供应商和料号。为了避免把不同 revision 拼在一起,本文的电路和布局图片都来自这次页面资源,实物照片只用于说明外形。

图2 装配正面,4×5 键区和 EC11 旋钮的机械关系。

图3 装配侧面。项目仓库还提供了固定板 DXF 和对应制版文件,外壳尺寸仍需按实际 PCB 版本复核。
下面的 EDA 缩略图是同一工程对象的页面预览,正文的 PCB 图则单独取了顶底面,避免把只显示一面的缩略图当成完整布线证据。

图4 Board1、固定板、原理图和 PCB1 的 EDA 预览汇总。复杂网络仍应回到编辑器查看,缩略图只用于版本对应关系。
矩阵和旋钮为什么要分开验收
固件的 pin_config.h 给出了可复核的 GPIO 分配:
- 矩阵列为 GPIO4~GPIO7,逐列驱动;
- 矩阵行为 GPIO8~GPIO12,下拉读取;
- EC11 的 A、B、按键分别为 GPIO13、GPIO14、GPIO21;
- USB D−/D+ 为 GPIO19/GPIO20;
- 电池采样为 GPIO1,采样开关为 GPIO17;
- 充电状态输入为 GPIO41 和 GPIO42。
工程文档给出的扫描周期是 5 ms,按键防抖窗口为 20 ms,编码器使用四倍频解码,长按判定为 800 ms。这里有两个容易被“能点亮”掩盖的风险。
第一,4×5 只是矩阵位置,不等于 20 个独立键。2u 空格占用两个位置后,软件的键位表仍要保持行列索引和实际键帽位置一致;改键时不能只修改上位机显示名称。第二,编码器 A/B 相通过 GPIO 边沿进入事件队列,旋转和按下是两类事件。若把长按切换模式也放到普通按键回调里,必须确保一次长按只触发一次模式请求,不能在 800 ms 之后每个扫描周期重复切换。
三种链路要有一个唯一的当前状态
项目 README 将三种连接方式定义为:
- 插入 USB 后使用有线 HID;
- BLE HID 最多保留三个配对槽;
- 2.4G WiFi 由键盘建立网络连接,再由主机程序把网络事件注入输入。
最后一项不是 ESP32-S3 直接向电脑声明的 USB/BLE HID。它依赖电脑端程序接收 [EVT] 输入并调用系统输入接口,所以“WiFi 模式已连上”至少要拆成网络连接、主机程序连接和事件注入成功三个状态。
固件的 hid_manager 采用延迟初始化策略。切换时先反初始化当前后端,等待 100 ms,再初始化目标后端;目标初始化失败时尝试恢复旧后端。成功切换后,它会清空键盘按住集合、清空 Consumer Control 位域,并让模式指示灯快闪三次。这组动作解决的是一个很具体的故障:旧主机还收到按下报告,而新通道没有收到释放报告,结果表现为“卡键”。

图5 同一版本 PCB 顶面。USB、主控和电池相关网络的实际位置应以 EDA 网络为准,不要仅凭实物照片猜引脚。

图6 同一版本 PCB 底面。底面图用于检查回流路径和器件背面关系,不能用顶面镜像替代。

图7 PCB Layout 顶面,保留原工程的层和方向。

图8 PCB Layout 底面。上下两张图属于同一个 PCB 对象,不能把其他 revision 的布局混入这组证据。
电量判断不是把 ADC 数值乘二
工程源码把 GPIO1 配成 ADC1_CH0,前端是 100 kΩ/100 kΩ 分压,GPIO17 控制 2N7002 让采样支路可以断开。换算关系的第一步确实是把 ADC 端电压乘二,但在 ESP32-S3 上还要先使用 ADC 校准结果,随后才是电池电压和电量表的映射。
项目里的 OCV 表以 3.35 V~4.20 V 为工作范围,低电告警锚点为 3.55 V,自动关机锚点为 3.35 V。关机并不是一次读到 3.35 V 就执行,而是约 1 s 间隔连续确认三次,用来过滤无线发射或按键动作造成的瞬间压降。充电检测另外使用 TP4056 的开漏状态脚,不能把“正在充电”当成电池电压已经稳定。
这套策略还不能推出真实剩余续航。锂电池的 OCV 会受负载、电芯温度和老化影响;分压电阻的误差、ADC 校准条件和采样开关导通电阻也会进入结果。可迁移的做法是保留“测量、校准、告警、关机”四层接口,让上位机能看到原始电压、校准电压和告警原因,而不是只显示一个整数百分比。

图9 项目配套的配置软件。它可以读取键位和配置方案;电量曲线的可信度仍取决于设备端采样和校准。
代码里的 6KRO 边界必须说清楚
项目 README 使用了“全键无冲”的描述,但 hid_manager.c 的键盘报告状态只有 6 个普通键槽,槽位填满后会记录警告并丢弃第 7 个普通键。这个实现是 6KRO,不能按 NKRO 的语义对外承诺。
这不是否定键盘可用性,而是一个很适合在评审阶段提前发现的接口边界:
- 如果目标只是常规办公和多数游戏,6KRO 可能已经足够;
- 如果要实现真正的 NKRO,需要同时修改 HID 报告描述符、按键状态位图和主机端解析,不是把
keys[6]改成更大的数组就结束; - 模式切换清空状态的逻辑必须对修饰键和 Consumer Control 一起生效,否则仍可能留下 Ctrl、音量或媒体按键的“幽灵按住”。
下面的独立 C11 状态模型把这两个边界写成可测试的契约。它不调用 ESP-IDF,也不直接操作 GPIO,适合先在主机上验证切换和保护逻辑,再接入具体驱动。
/*
* tri_mode_contract.c
* Independent state contract, Copyright (c) 2026 Meizu Nanbiancheng.
* MIT License. This is not the project's firmware.
*/
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#define TM_KEY_SLOTS 6
#define TM_LOW_WARN_MV 3550
#define TM_SHUTDOWN_MV 3350
#define TM_SHUTDOWN_CONFIRM 3
typedef enum {
TM_MODE_NONE = 0, TM_MODE_USB, TM_MODE_BLE, TM_MODE_WIFI
} tm_mode_t;
typedef struct {
tm_mode_t current, pending;
bool switching;
uint8_t held[TM_KEY_SLOTS];
uint8_t consumer_bits;
uint8_t shutdown_count;
bool low_warning, shutdown;
} tm_ctx_t;
void tm_init(tm_ctx_t *c, tm_mode_t initial) {
if (c) *c = (tm_ctx_t){ .current = initial };
}
int tm_request_switch(tm_ctx_t *c, tm_mode_t next) {
if (!c || next < TM_MODE_USB || next > TM_MODE_WIFI ||
c->switching || next == c->current) return -1;
c->pending = next;
c->switching = true;
return 0;
}
void tm_complete_switch(tm_ctx_t *c, bool ok) {
if (!c || !c->switching) return;
if (ok) {
c->current = c->pending;
c->pending = TM_MODE_NONE;
for (size_t i = 0; i < TM_KEY_SLOTS; ++i) c->held[i] = 0;
c->consumer_bits = 0;
} else {
c->pending = TM_MODE_NONE; /* caller restores the old backend */
}
c->switching = false;
}
/* 1=new key, 0=duplicate, -1=switching/invalid/full */
int tm_press(tm_ctx_t *c, uint8_t key) {
if (!c || key == 0 || c->switching) return -1;
for (size_t i = 0; i < TM_KEY_SLOTS; ++i)
if (c->held[i] == key) return 0;
for (size_t i = 0; i < TM_KEY_SLOTS; ++i)
if (c->held[i] == 0) { c->held[i] = key; return 1; }
return -1;
}
int tm_battery_sample(tm_ctx_t *c, uint16_t mv) {
if (!c) return -1;
c->low_warning = mv < TM_LOW_WARN_MV;
if (mv <= TM_SHUTDOWN_MV) {
if (c->shutdown_count < TM_SHUTDOWN_CONFIRM) ++c->shutdown_count;
} else {
c->shutdown_count = 0;
}
if (c->shutdown_count >= TM_SHUTDOWN_CONFIRM) c->shutdown = true;
return c->shutdown ? 1 : 0;
}
这个模型故意没有“低于阈值立即关机”的捷径。tm_request_switch 锁住切换窗口,tm_complete_switch 只有在目标后端初始化成功后才改变当前模式;成功时同时清空 6 个普通键槽和 Consumer 位域。电量采样则把 3.55 V 告警与 3.35 V 连续确认关机分开。
验证结果和已知边界
本轮在主机上用 Python 3.12 对上述状态转移写了独立模型测试,覆盖五组情况:
| 测试 | 结果 |
|---|---|
| 6 个普通键全部占槽,第 7 个被拒绝 | 通过 |
| 切换窗口禁止新报告 | 通过 |
| 成功切换后模式更新、普通键和 Consumer 位域清空 | 通过 |
| 3.30 V 连续三次才进入关机态 | 通过 |
| 一次切换失败后保留旧模式,电压回升后清零确认计数 | 通过 |
测试输出为 tri-mode contract tests: 5 groups passed。当前环境没有 ESP-IDF 和 C 编译器,因此没有把这段 C11 模型写成“已通过固件编译”;也没有进行实体键盘、无线距离、续航、温升或充放电实测。要接入真实固件,还需要:
- 用目标 ESP-IDF 版本编译原工程,确认 HID 描述符与报告结构;
- 在 USB、BLE、WiFi 三条链路上分别验证切换失败回滚和零报告;
- 用已知电压源校准 ADC,再在按键和无线发射同时发生时记录电压采样;
- 若需要 NKRO,先修改报告描述符和主机软件,再重新做跨平台兼容测试。
一套可复现的检查顺序
如果要复刻这个项目,建议按下面顺序减少返工:
- 在 EDA 中打开 Board1 和固定板,确认版本、BOM 和 PCB 顶底面属于同一组对象。
- 先按
pin_config.h检查 GPIO4~GPIO21 的矩阵、编码器和 USB 复用,确认没有碰到 ESP32-S3 模组占用的 GPIO26~GPIO37。 - 用 Flash Download Tool 选择 ESP32-S3,按
0x0、0x8000、0x10000写入bootloader.bin、partition-table.bin和SimpleKey_TriMode.bin。 - 首次启动先用串口
status查看当前模式,再用mode usb、mode ble等命令逐一验证后端切换;切换时按住的键必须在新通道中释放。 - 打开配置软件,先保存一个可恢复的键位方案,再测试改键、宏、EC11 旋转和长按切换。
- 电池验证从原始 ADC 毫伏值开始,分别记录 3.55 V 告警、3.35 V 三次确认和充电状态脚,不能只看百分比。
工程来源和许可
硬件、EDA、固件和上位机工程来源于 SimpleKey-Regression 项目页,项目页标示 GPL 3.0。本次采用的是页面当前可见的 Board1、固定板、PCB1 预览以及对应的项目图片;图片做了等比缩放和排版裁剪,没有改动电路或伪造器件标注。
源码入口为 WEN454545/SimpleKey-Regression--,本轮核对的仓库提交为 da2b803253c8d2ae2a3a96a939d5be1c32473c00。项目源码和硬件文件继续按 GPL-3.0 处理,复用时保留原版权和许可文本。
文中的 tri_mode_contract.c 是独立编写的 MIT 示例,只验证状态机和阈值契约;测试范围是主机 Python 模型,不包含实体硬件测量。项目的电池、无线、键盘报告和 EMC 表现仍应以实际装配和目标固件验证为准。



