三模键盘切换时怎样避免卡键并把电量判定做稳

2026-11-177
精华项目

三模键盘切换时怎样避免卡键并把电量判定做稳

三模键盘最容易被忽略的地方,不是把 USB、蓝牙和 2.4G WiFi 都接上,而是切换链路时如何处理“旧连接还按着一个键”的状态,以及无线工作几小时后电量判断是否会把瞬时压降误判成关机。

本文以 SimpleKey-Regression 的 ESP32-S3-WROOM-1 方案为对象,重新核对同一版本的 EDA 预览、PCB 正反面、Layout 顶底面和固件源码,抽出三条可以迁移到其他键盘和输入设备的工程规则:

  1. 链路切换必须是有边界的事务,切换窗口禁止继续发 HID 报告,成功后清空旧通道的按住键集合。
  2. 电池电压要先经过分压、ADC 校准和连续采样确认,再把低电告警与关机动作分开。
  3. 宣称“全键无冲”要看 HID 报告描述符和发送缓冲区,不能只看 README 的功能表。

文中的状态模型是独立编写的 C11 示例,验证的是状态转换和保护契约;它没有冒充项目固件,也没有把主机仿真结果写成整机实测。

先确认硬件和版本边界

项目主控为 ESP32-S3-WROOM-1,键区采用 4×5 矩阵,实际布置 19 个按键和一个 2u 空格,旁边是 EC11 旋钮。电池是带保护板的 103450 锂电池,标称 2000 mAh;充电和有线通信共用 Type-C 接口。

SimpleKey 三模键盘实物

图1 项目主图。它只能证明项目页面展示的装配状态,不能替代本文对 EDA 和源码的核对。

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

键盘装配正面

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

键盘装配侧面

图3 装配侧面。项目仓库还提供了固定板 DXF 和对应制版文件,外壳尺寸仍需按实际 PCB 版本复核。

下面的 EDA 缩略图是同一工程对象的页面预览,正文的 PCB 图则单独取了顶底面,避免把只显示一面的缩略图当成完整布线证据。

同一版本 EDA 预览

图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 位域,并让模式指示灯快闪三次。这组动作解决的是一个很具体的故障:旧主机还收到按下报告,而新通道没有收到释放报告,结果表现为“卡键”。

PCB 正面

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

PCB 背面

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

PCB Layout 顶面

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

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 模型写成“已通过固件编译”;也没有进行实体键盘、无线距离、续航、温升或充放电实测。要接入真实固件,还需要:

  1. 用目标 ESP-IDF 版本编译原工程,确认 HID 描述符与报告结构;
  2. 在 USB、BLE、WiFi 三条链路上分别验证切换失败回滚和零报告;
  3. 用已知电压源校准 ADC,再在按键和无线发射同时发生时记录电压采样;
  4. 若需要 NKRO,先修改报告描述符和主机软件,再重新做跨平台兼容测试。

一套可复现的检查顺序

如果要复刻这个项目,建议按下面顺序减少返工:

  1. 在 EDA 中打开 Board1 和固定板,确认版本、BOM 和 PCB 顶底面属于同一组对象。
  2. 先按 pin_config.h 检查 GPIO4~GPIO21 的矩阵、编码器和 USB 复用,确认没有碰到 ESP32-S3 模组占用的 GPIO26~GPIO37。
  3. 用 Flash Download Tool 选择 ESP32-S3,按 0x0、0x8000、0x10000 写入 bootloader.bin、partition-table.bin 和 SimpleKey_TriMode.bin。
  4. 首次启动先用串口 status 查看当前模式,再用 mode usb、mode ble 等命令逐一验证后端切换;切换时按住的键必须在新通道中释放。
  5. 打开配置软件,先保存一个可恢复的键位方案,再测试改键、宏、EC11 旋转和长按切换。
  6. 电池验证从原始 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 表现仍应以实际装配和目标固件验证为准。

创作许可协议

本项目采用 None(不开放任何权利,保留所有权利) 进行许可。

评论(0)
- 没有更多了 -