# btnlib

**Repository Path**: siyunchen/btnlib

## Basic Information

- **Project Name**: btnlib
- **Description**: btnlib是一个专为嵌入式系统设计的按钮处理库，提供了完整的按钮事件检测功能，包括单击、双击、长按等常见交互方式。该库采用状态机设计，具有良好的稳定性和可扩展性，适用于各种需要按钮输入的嵌入式应用。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-10-27
- **Last Updated**: 2025-10-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Button Library (btnlib)

一个轻量级、易于集成的嵌入式按钮处理库，支持多种按钮事件检测。

## 简介

btnlib是一个专为嵌入式系统设计的按钮处理库，提供了完整的按钮事件检测功能，包括单击、双击、长按等常见交互方式。该库采用状态机设计，具有良好的稳定性和可扩展性，适用于各种需要按钮输入的嵌入式应用。

## 特性

- 支持多种按钮事件：
  - 单击事件（Short Press）
  - 双击事件（Double Click）
  - 长按事件（Long Press）及持续检测
  - 按下和释放事件
- 软件消抖处理，提高按键稳定性
- 支持多按钮管理
- 基于回调函数的事件通知机制
- 可配置的处理参数
- 使用链表管理多个按钮，内存占用小

## 使用方法

### 1. 定义按钮对象和IO读取函数

```c
btn_t button1;

bool read_button1_pressed(void *context) {
    // 返回按键是否被按下，true表示按下，false表示释放
    return HAL_GPIO_ReadPin(BUTTON1_GPIO_Port, BUTTON1_Pin) == GPIO_PIN_RESET;
}
```

### 2. 注册按钮并添加事件回调

```c
btn_register(&button1, read_button1_pressed, NULL);

btn_add_callback(&button1, BTN_EVENT_SINGLE, button1_single_callback);
btn_add_callback(&button1, BTN_EVENT_DOUBLE, button1_double_callback);
btn_add_callback(&button1, BTN_EVENT_LONG_PRESS_START, button1_long_press_start_callback);
```

### 3. 在主循环中定期调用处理函数

```c
while(1) {
    btn_process();
    HAL_Delay(BTN_PROCESS_PERIOD); // 确保处理周期为BTN_PROCESS_PERIOD
}
```

### 4. 实现回调函数

```c
void button1_single_callback(btn_t *obj, btn_event_t event) {
    // 处理单击事件
    printf("Button1 单击\n");
}

void button1_double_callback(btn_t *obj, btn_event_t event) {
    // 处理双击事件
    printf("Button1 双击\n");
}

void button1_long_press_start_callback(btn_t *obj, btn_event_t event) {
    // 处理长按开始事件
    printf("Button1 长按开始\n");
}
```

## 配置选项

可以通过修改以下宏定义来自定义按钮行为：

- `BTN_PROCESS_PERIOD`: 处理周期(ms)，即调用btn_process处理函数的周期
- `BTN_DEBOUNCE_NUM`: 连续多少次扫描读到不同电平才会更新状态(1 ~ 15)
- `BTN_LONG_PRESS_THRESHOLD`: 长按阈值(ms)，即超过多长时间视为长按
- `BTN_DOUBLE_HIT_THRESHOLD`: 双击阈值(ms)，即两次短按间隔不超过多少时间视为双击
- `BTN_LONG_PRESS_HOLD_PERIOD`: 长按保持事件触发周期(ms)
- `BTN_STATE_TIMEOUT_THRESHOLD`: 状态机超时阈值(ms)，防止状态机卡死

## API参考

### 核心函数

- `void btn_register(btn_t *obj, bool (*read_io_pressed)(void *context), void *context)`
  注册一个按钮对象
  
- `void btn_unregister(btn_t *obj)`
  注销一个按钮对象
  
- `void btn_add_callback(btn_t *obj, btn_event_t event, btn_callback_func cb)`
  添加指定事件的回调函数
  
- `void btn_process(void)`
  按钮事件处理函数，需要定期调用

### 事件类型

- `BTN_EVENT_PRESSED`: 按下事件
- `BTN_EVENT_RELEASED`: 释放事件
- `BTN_EVENT_SINGLE`: 单击事件
- `BTN_EVENT_DOUBLE`: 双击事件
- `BTN_EVENT_LONG_PRESS_START`: 长按开始事件
- `BTN_EVENT_LONG_PRESS_HOLD`: 长按保持事件
- `BTN_EVENT_LONG_PRESS_STOP`: 长按结束事件

## 注意事项

1. 确保`btn_process()`以固定周期`BTN_PROCESS_PERIOD`调用
2. 每个按钮对象需要独立的`btn_t`实例
3. 支持多按钮同时使用，通过链表管理
4. 事件回调函数中不要执行耗时操作

## 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解更多详情。