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

模块拆分 - 按键扫描与事件判定 (Docs/50_module-breakdown/mod-key.md)

本模块描述按键状态消抖、长按和短按计时判定。支持 5 个物理按键到手环事件的映射。

1. 模块职责说明

• 职责范围：
  1. 在 1ms 定时器中断中建立 10ms 扫描计时周期。
  2. 对 5 个物理按键进行引脚电平扫描：
     • 侧边：KEY_UP SW1 (▲), KEY_DOWN SW2 (▼), KEY_CONFIRM (■)
     • 上部：KEY_SOS1 (SOS 1), KEY_SOS2 (SOS 2)
  3. 实现消抖检测（连续 20ms 检测到电平稳定才认定按键动作）。
  4. 对上部双 SOS 按键进行逻辑并联处理，保证按下任意一个均能触发求救。
  5. 对按住不放的行为进行计时累加，判定长按：
     • 长按 确认键 (CONFIRM / ■) 达 3 秒触发主菜单选择界面或退出当前页面。
     • 侧边 ▼ 键 长按达 2 秒产生长按退出/消除警报事件。
     • SOS 按键（SOS1 / SOS2）长按或短按，只要是非报警状态，一律触发 KEY_SOS_ACTIVE 本地报警呼救事件。
  6. 将按键判定结果转换为 KeyEvent 并注入按键事件缓冲区 key_event_buf。

2. 数据结构定义

按键事件枚举 (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键活动 (短按或长按，跳转至发送 SOS 报警)
} KeyEvent;

3. 接口与函数说明

• void Key_Scan_Process(void)： 在 Timer 1 ISR 中每 10ms 调度一次。
  • 读取 KEY_UP, KEY_DOWN, KEY_CONFIRM, KEY_SOS1, KEY_SOS2 的 GPIO 逻辑电平。
  • 计算并联 SOS 状态：is_sos_pressed = (KEY_SOS1 == 0) || (KEY_SOS2 == 0)。
  • 如果发现按键电平状态改变，进行计数消抖。
  • 如果按住不放，累加计时计数器（key_up_hold, key_down_hold, key_confirm_hold, key_sos_hold）。
  • 检测到 key_confirm_hold >= 300 达 3 秒时，注入 KEY_CONFIRM_LONG 中断事件。
  • 检测到 key_down_hold >= 200 达 2 秒时，注入 KEY_DOWN_LONG 中断事件。
  • 检测到并联 SOS 被按下时，注入 KEY_SOS_ACTIVE 事件。