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)
```c
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`。

<!-- Checked and verified with SGM3833 boost/inverting PMIC removal and LCD_PWR_CTRL update changes V2 -->