# Agile Button

## 1、介绍

Agile Button 是基于 RT-Thread 实现的 button 软件包，提供 button 操作的 API。

- 按键操作的状态变化为：`未按下  ——>  按下  ——>  未按下`。

- 为了消除干扰，默认的消抖时间为 15ms，可以通过 `agile_btn_set_elimination_time` API 更改消抖时间。

- 间隔在 500ms 内的连续操作，记为多次操作，更改对象的 `repeat_cnt` 属性，通过该属性可获取连续操作次数。

- 在按下期间会计算对象的持续按下时间，可通过对象的 `hold_time` 属性获取。

```C
   ____          __      __          ____
__|    |__  ——>    |____|    ——>  __|    |__

```

Agile Button 提供了 4 种事件：

```C
BTN_PRESS_DOWN_EVENT
BTN_HOLD_EVENT
BTN_PRESS_UP_EVENT
BTN_CLICK_EVENT
```

可以通过 `agile_btn_set_event_cb` API 设置每个事件的触发回调。

- BTN_PRESS_DOWN_EVENT

从 `未按下  ——>  按下` 触发一次。

```C
   ____          __      __
__|    |__  ——>    |____|

```

- BTN_HOLD_EVENT

一直处于按下状态，默认每隔 1s 触发一次，可以通过 `agile_btn_set_hold_cycle_time` API 更改触发周期。

```C
__      __
  |____|

```

- BTN_PRESS_UP_EVENT

从 `按下  ——>  未按下` 触发一次。

```C
__      __          ____
  |____|    ——>  __|    |__

```

- BTN_CLICK_EVENT

一次完整的操作触发一次，即：`未按下  ——>  按下  ——>  未按下`。

**注意**：`BTN_PRESS_UP_EVENT` 也会被触发。

```C
   ____          __      __          ____
__|    |__  ——>    |____|    ——>  __|    |__

```

### 1.1、特性

1. 代码简洁易懂，充分使用 RT-Thread 提供的 API
2. 详细注释
3. 线程安全
4. 断言保护
5. API 操作简单

### 1.2、目录结构

| 名称 | 说明 |
| ---- | ---- |
| doc | 文档目录 |
| examples | 例子目录 |
| inc  | 头文件目录 |
| src  | 源代码目录 |

### 1.3、许可证

Agile Button package 遵循 LGPLv2.1 许可，详见 `LICENSE` 文件。

### 1.4、依赖

- RT-Thread 3.0+
- RT-Thread 4.0+

## 2、如何打开 Agile Button

使用 Agile Button package 需要在 RT-Thread 的包管理器中选择它，具体路径如下：

```
RT-Thread online packages
    peripheral libraries and drivers --->
        [*] agile_button: A agile button package
```

然后让 RT-Thread 的包管理器自动更新，或者使用 `pkgs --update` 命令更新包到 BSP 中。

## 3、使用 Agile Button

- 帮助文档请查看 [doc/doxygen/Agile_Button.chm](./doc/doxygen/Agile_Button.chm)

如果未使能 PKG_AGILE_BUTTON_USING_THREAD_AUTO_INIT:

1. agile_btn_env_init 初始化环境

2. 创建一个线程，周期调用 agile_btn_process，建议周期时间不要太长

- agile_btn_create / agile_btn_init 创建 / 初始化对象
- agile_btn_set_elimination_time 更改消抖时间，可忽略
- agile_btn_set_hold_cycle_time 更改持续按下触发周期时间，可忽略

  该操作也可在运行过程中执行

- agile_btn_set_event_cb 设置事件触发回调
- agile_btn_start 启动运行
- agile_btn_stop 运行过程中强制停止

### 3.1、示例

使用示例在 [examples](./examples) 下。

### 3.2、Doxygen 文档生成

- 使用 `Doxywizard` 打开 [Doxyfile](./doc/doxygen/Doxyfile) 运行，生成的文件在 [doxygen/output](./doc/doxygen/output) 下。
- 需要更改 `Graphviz` 路径。
- `HTML` 生成未使用 `chm` 格式的，如果使能需要更改 `hhc.exe` 路径。

## 4、联系方式 & 感谢

- 维护：马龙伟
- 主页：<https://github.com/loogg/agile_button>
- 邮箱：<2544047213@qq.com>