stc32g128k/Docs/50_module-breakdown/mod-key.md

模块拆分 - 按键输入消抖与判定 (Docs/50_module-breakdown/mod-key.md)

本模块描述物理按键输入的检测、电平消抖、长按计时以及多事件防丢处理。

1. 模块职责说明

• 职责范围：
  1. 在系统上电时，将按键引脚 P0.1~P0.5 配置为高阻输入且开启内部上拉电阻（STC32G P0M0/P0M1/P0PU 寄存器配置）。
  2. 实现每 10ms 一次的硬件消抖滤波（采用 3 次扫描连续一致判定法，滤波时间约 20-30ms）。
  3. 支持侧边 ▲/▼ 键、确认键 ■，以及上部双并联 SOS 键的独立状态判定。
  4. 对上部双 SOS 按键进行逻辑并联处理：只要任意一个按键拉低，即视为 SOS 触发。
  5. 长按计时判定：
     • 长按 确认键 (■) 达 3 秒（300 个时基单位）触发主菜单切换或子页面放弃退出。
     • 长按 ▼ 键 达 2 秒（200 个时基单位）触发报警清除或 IPC 绑定退出。
  6. 防丢事件缓冲队列 (Ring Buffer)：
     • 为了防止高频按键或同时按下时发生丢键，本模块维护一个深度为 4 级的环形事件队列。按键扫描判定出的 KeyEvent 压入队列，主循环通过出队机制依次消费。

---

2. 数据结构定义

2.1 按键事件枚举 (KeyEvent)

typedef enum {
    KEY_EVENT_NONE,
    KEY_UP_SHORT,       // ▲ 键短按
    KEY_DOWN_SHORT,     // ▼ 键短按
    KEY_DOWN_LONG,      // ▼ 键长按 2 秒 (清除报警/退出)
    KEY_CONFIRM_CLICK,  // ■ 确认键短按
    KEY_CONFIRM_LONG,   // ■ 确认键长按 3 秒 (菜单切换)
    KEY_SOS_ACTIVE      // SOS 键触发 (不分长短按，秒级响应)
} KeyEvent;

---

3. 接口与函数说明

• void Key_Init(void)：配置 P0.1~P0.5 的 P0M1=0x00, P0M0=0x00（高阻模式），并设置 P0PU = 0x3E 使能上拉电阻。
• void Key_Scan_Process(void)： 在 Timer 1 10ms 中断分频中调用。
  • 读取引脚逻辑状态，并利用移位寄存器滤波判定。
  • 并联 SOS 状态：sos_pressed = (KEY_SOS1 == 0) || (KEY_SOS2 == 0)。
  • 累加各按键的计数器：key_up_hold, key_down_hold, key_confirm_hold, key_sos_hold。
  • 达到长按阈值时将对应事件写入环形队列。
• bit Key_Push_Event(KeyEvent evt)：将事件压入环形事件队列。若满则丢弃，返回 0。
• KeyEvent Key_Pop_Event(void)：主循环调用，从事件队列中读取未消费的事件。若空返回 KEY_EVENT_NONE。