# cotKey **Repository Path**: MagicBude/cot_key ## Basic Information - **Project Name**: cotKey - **Description**: 嵌入式设备常用的按键动作识别模块组件代码 - **Primary Language**: C - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 0 - **Created**: 2025-06-13 - **Last Updated**: 2026-11-04 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 轻量级按键识别模块 本模块提供普通、长按、连击和连击复合模式,支持多按键管理及事件回调。 ## 功能特点 - 核心易于移植,只需提供读取按键逻辑状态的函数 - 丰富的接口实现,支持单击、双击、多击、短按和长按等多种功能 - 代码量少,结构清晰 - 支持多个按键同时管理 - 支持按下/松开事件触发 - 回调函数机制,使用灵活 ## 文件结构 - `cot_key.h`/`cot_key.c`: 核心按键处理模块,提供按键状态识别功能 - `key_manager.h`/`key_manager.c`: 按键管理层示例,负责初始化按键硬件并注册回调函数 ## 使用说明 ### 基本步骤 1. **初始化**:使用前初始化函数 `cotKey_Init`,添加所有按键 > 需要实现读取 IO 状态的函数,然后初始化结构体的 `pfnKeyState` 即可。按下返回 `COT_KEY_ON`,松开返回 `COT_KEY_OFF`;配置数组在组件使用期间须保持有效。 2. **添加监听**:初始化后通过 `cotKey_Listen` 注册回调,并配置所需的按键模式 3. **周期扫描**:周期调用 `cotKey_Scan`,传入累计毫秒时间,而非本次扫描间隔 4. **处理回调**:在回调函数中调用其他函数进一步识别按键的动作,做出相应处理 ### 代码示例 #### 初始化按键 ```c /* 按键初始化函数示例 */ void FML_KEY_Init(void) { static cotKeyCfg_t s_keyTable[KEY_MAX_NUM] = { { .pfnKeyState = ReadKey0 }, /* 第一个按键的读取函数 */ { .pfnKeyState = ReadKey1 }, /* 第二个按键的读取函数 */ { .pfnKeyState = ReadKey2 }, /* 第三个按键的读取函数 */ }; /* 初始化按键 IO */ InitKeyIo(); /* 初始化 COT按键模块 */ cotKey_Init(s_keyTable, KEY_MAX_NUM); /* 注册按键回调 */ cotKey_Listen(KEY0, OnKey0Press); cotKey_Listen(KEY1, OnKey1Press); cotKey_Listen(KEY2, OnKey2Press); /* 配置按键模式 - 这里使用长按模式示例 */ cotKey_ConfigLongPressMode(KEY0, 1500, 500); /* 1.5秒长按,0.5秒重复 */ } ``` #### 按键扫描 ```c /* 在主循环中周期性调用 */ void MainLoop(void) { /* 将实际经过的毫秒数累加,向扫描函数传入累计时间 */ static uint32_t s_keyTick = 0; uint32_t time_elapsed = GetTimeElapsed(); /* 例如10ms, 20ms等 */ s_keyTick += time_elapsed; cotKey_Scan(s_keyTick); /* 其他任务... */ } ``` 或者在固定周期的定时器中调用: ```c /* 在定时器中调用,假设定时器每 20 ms 触发一次 */ static uint32_t s_keyTick = 0; void TimerCallback(void) { s_keyTick += 20; /* 累加固定的时间增量 */ cotKey_Scan(s_keyTick); } ``` 此方式要求定时回调按固定周期执行,不漏调用;若发生延迟或丢失,累计时间会偏离实际经过时间,应改用实际系统毫秒计数。 `cotKey_Scan()` 会在调用上下文中同步执行按键读取函数和事件回调。若定时器回调运行于中断,读取函数和业务回调须满足中断上下文要求,避免阻塞、耗时输出或使用不允许在中断中调用的接口;不得同时从其他中断、主循环或任务访问组件。也可在中断中仅设置标志,由主循环执行扫描。 在 STM32 HAL 工程中,也可以直接使用系统毫秒计数: ```c /* 在主循环或同一任务中周期调用 */ cotKey_Scan(HAL_GetTick()); ``` 回调在扫描函数内同步执行,应尽快返回,不重入扫描。使用定时器调度时,可在中断中设置标志,由主循环执行扫描。以上均为接入片段,GPIO、系统时基及业务函数由应用工程提供。 #### 按键回调处理 ```c /* 按键回调函数示例 */ static void OnKeyPress(cotKey_t key) { if (!cotKey_IsLongPress(key)) /* 判断是否触发了长按 */ { if (cotKey_IsTriggerWayMet(key, COT_KEY_TRIGGER_WAY_PRESS)) /* 按下触发 */ { /* 处理按键按下事件 */ } if (cotKey_IsTriggerWayMet(key, COT_KEY_TRIGGER_WAY_LOSSEN)) /* 松开触发 */ { /* 处理按键松开事件 */ } } else { if (cotKey_IsTriggerWayMet(key, COT_KEY_TRIGGER_WAY_PRESS)) /* 长按触发 */ { /* 处理长按事件 */ } if (cotKey_IsTriggerWayMet(key, COT_KEY_TRIGGER_WAY_LOSSEN)) /* 长按松开 */ { /* 处理长按松开事件 */ } } } ``` ## 配置项 ### 按键模式 - 普通模式:支持按下/松开触发,可配置按住重复触发,重复间隔为 0 时关闭 - 长按模式:支持长按检测和周期触发 - 连击模式:支持连续点击次数检测 - 连击复合模式:识别单个按键的连击或首次持续按下,不表示多个按键同时按下的组合键 ### 触发方式 - `COT_KEY_TRIGGER_WAY_PRESS`: 按下触发 - `COT_KEY_TRIGGER_WAY_LOSSEN`: 松开触发 连续两次采样一致后才更新确认状态,单次采样毛刺不会改变确认状态;这不是固定毫秒数的消抖。重复及连击间隔小于 65535 ms 时采用超过判定,间隔为 65535 ms 时在计时饱和后触发。 长按时长从确认按下累计到确认松开;若松开这轮才达到阈值,只报告长按松开,不补发长按进入。复合模式的首次持续按下使用相同规则,已有点击后的连击流程保持原有行为。 ## 适配指南 如需适配到其他硬件平台,修改 `key_manager.c` 中的 `InitKeyIo()`、状态读取函数和相关 GPIO 定义。核心组件无需依赖该管理层,可直接接入自己的状态读取函数和业务回调。 主机测试的运行命令和覆盖范围见 [测试说明](tests/README.md)。主机测试不代替 GPIO、时基及目标板运行验证。 ## 原项目信息 - 原作者:[大橙子疯](https://blog.csdn.net/qq_24130227?spm=1010.2135.3001.5343) - 联系邮箱:`const_zpc@163.com` - 原始代码:[轻量级按键识别模块](https://gitee.com/cot_package/cot_key) ## 许可证 [MIT](LICENSE)