# 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**: 0
- **Forks**: 0
- **Created**: 2025-06-13
- **Last Updated**: 2025-07-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 轻量级按键识别模块（增强注释版）

本项目是基于[大橙子疯](https://blog.csdn.net/qq_24130227)的轻量级按键动作识别软件框架，在原有代码基础上增加了更详细的注释和使用说明，便于学习和理解。

## 功能特点

- 移植方便，无需修改，只需提供读取相关IO状态函数
- 丰富的接口实现，支持单击、双击、多击、短按和长按等多种功能
- 代码量少，结构清晰，现已增加详细注释，更易于理解和使用
- 支持多个按键同时管理
- 支持按下/松开事件触发
- 回调函数机制，使用灵活

## 文件结构

- `cot_key.h`/`cot_key.c`: 核心按键处理模块，提供按键状态识别功能
- `key_manager.h`/`key_manager.c`: 按键管理层示例，负责初始化按键硬件并注册回调函数

## 使用说明

### 基本步骤

1. **初始化**：使用前初始化函数 `cotKey_Init`，添加所有按键
   
> 需要实现读取IO状态的函数，然后初始化结构体的 `pfnKeyState`即可。
   
2. **周期扫描**：周期调用函数 `cotKey_Scan`，入参为毫秒级的系统时长，用来扫描按键动作并触发回调函数处理

3. **添加监听**：通过函数 `cotKey_Listen` 添加回调函数监听按键操作状态

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
/* 在定时器中调用，假设定时器每20ms触发一次 */
static uint32_t s_keyTick = 0;

void TimerCallback(void)
{
    s_keyTick += 20; /* 累加固定的时间增量 */
    cotKey_Scan(s_keyTick);
}
```

#### 按键回调处理

```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)) /* 长按松开 */
        {
            /* 处理长按松开事件 */
        }
    }
}
```

## 配置项

### 按键模式

- 普通模式：支持按下/松开触发
- 长按模式：支持长按检测和周期触发
- 连击模式：支持连续点击次数检测
- 连击复合模式：支持连击和长按的复合检测

### 触发方式

- `COT_KEY_TRIGGER_WAY_PRESS`: 按下触发
- `COT_KEY_TRIGGER_WAY_LOSSEN`: 松开触发

## 适配指南

如需适配到其他硬件平台，只需修改 `key_manager.c` 中的 `InitKeyIo()` 函数和相关GPIO定义即可。

## 相比原版的改进

- 增加了详细的代码注释，解释每个函数的作用和参数含义
- 提供了更清晰的使用示例和代码结构说明
- 优化了API调用方式，更符合直觉
- 添加了按键管理层示例，便于快速集成到实际项目中

## 原项目信息

- 原作者：[大橙子疯](https://blog.csdn.net/qq_24130227?spm=1010.2135.3001.5343)
- 联系邮箱：`const_zpc@163.com`
- 原始代码：[轻量级按键识别模块](https://gitee.com/cot_package/cot_key)

## 许可证

MIT