一个小巧简单易用的事件驱动型按键驱动模块

1. MultiButton

本期给大家带来的开源项目是 MultiButton，一个小巧简单易用的事件驱动型按键驱动模块，作者 0x1abin，目前收获 222 个star，遵循 MIT 开源许可。

这个项目非常精简，只有两个文件，可无限量扩展按键，按键事件的回调异步处理方式可以简化程序结构，去除冗余的按键处理硬编码，让你的按键业务逻辑更清晰。

MuliButton 支持如下的按钮事件：

事件说明PRESS_DOWN按键按下，每次按下都触发PRESS_UP按键弹起，每次松开都触发PRESS_REPEAT重复按下触发，变量repeat计数连击次数SINGLE_CLICK单击按键事件DOUBLE_CLICK双击按键事件LONG_RRESS_START达到长按时间阈值时触发一次LONG_PRESS_HOLD长按期间一直触发

GIthub地址：https://github.com/0x1abin/MultiButton

2. 使用MultiButton

2.1. 准备一份裸机工程

需要掌握使用HAL库读取GPIO输入的函数、串口的使用、printf重定向、以及systick的使用：

STM32CubeMX | 04-使用GPIO进行按键检测

STM32CubeMX | 06-使用USART发送和接收数据（查询模式）

STM32CubeMX | 09-重定向printf函数到串口输出的多种方法

本文中我使用小熊派IoT开发板，主控为STM32L431RCT6：

配置外部时钟：

按键GPIO配置：

打印串口配置：

时钟配置：

配置工程，生成代码，重定向printf，printf可以正常打印后进行下面的步骤。

2.2. 移植MultiButton

① 复制MultiButton源码到裸机工程中：

② 添加MultiButton源码到项目中：

此时编译没有问题。

2.3. 编写MultiButton应用代码

在main.c文件中编写以下代码。

① 包含头文件

/* USER CODE BEGIN Includes */

#include   //要使用printf

#include 'multi_button.h'

/* USER CODE END Includes */

② 定义一个按键结构（按键对象）

/* USER CODE BEGIN PV */

//申请一个按键结构

struct Button button1;

/* USER CODE END PV */

③ 初始化按键对象

初始化按键对象使用的API为：

第一个参数为刚刚创建的按键对象的指针；

第二个参数为绑定按键的GPIO电平读取接口；

第三个参数为设置有效触发电平；

首先在main函数之前实现一个GPIO电平读取接口：

/* USER CODE BEGIN 0 */

//按键状态读取接口

uint8_t read_button1_GPIO()

{

return HAL_GPIO_ReadPin(KEY1_GPIO_Port, KEY1_Pin);

}

/* USER CODE END 0 */

初始化按键对象的代码在main函数中，while(1)之前编写，如下：

/* USER CODE BEGIN 2 */

printf('MultiButton Test...rn');

//初始化按键对象

button_init(&button1, read_button1_GPIO, 0);

/* USER CODE END 2 */

④ 注册按键事件

注册按钮事件的API如下：

第一个参数为按钮对象指针；

第二个参数为MultiButton支持的按钮事件；

第三个参数为要注册的该事件回调函数；

MultiButton支持的按钮事件枚举如下：

首先在main函数之前定义这两个事件的回调函数，回调函数有两种写法。

第一种适合于按键事件较少的情况：

//按键1按下事件回调函数

void btn1_press_down_Handler(void* btn)

{

printf('---> key1 press down! <---rn');

}

//按键1松开事件回调函数

void btn1_press_up_Handler(void* btn)

{

printf('***> key1 press up! <***rn');

}

在main函数中，while(1)之前注册这两个回调函数：

//注册按钮事件回调函数

button_attach(&button1, PRESS_DOWN, btn1_press_down_Handler);

button_attach(&button1, PRESS_UP, btn1_press_up_Handler);

第二种适合于按键事件较多的情况，如果每个按键都要写 7 个回调函数，那么代码量会非常的大，所以可以将这 7 个回调函数写在一起，一次性全部注册，回调函数如下：

void button_callback(void *button)

{

    uint32_t btn_event_val;

    btn_event_val = get_button_event((struct Button *)button);

    switch(btn_event_val)

    {

     case PRESS_DOWN:

         printf('---> key1 press down! <---rn');

      break;

     case PRESS_UP:

         printf('***> key1 press up! <***rn');

      break;

     case PRESS_REPEAT:

         printf('---> key1 press repeat! <---rn');

      break;

     case SINGLE_CLICK:

         printf('---> key1 single click! <---rn');

      break;

     case DOUBLE_CLICK:

         printf('***> key1 double click! <***rn');

      break;

     case LONG_RRESS_START:

         printf('---> key1 long press start! <---rn');

      break;

     case LONG_PRESS_HOLD:

         printf('***> key1 long press hold! <***rn');

      break;

}

}

使用这种回调函数的时候需要在MultiButton的源码中添加一行代码：

注册回调函数的代码如下：

//注册按钮事件回调函数

button_attach(&button1, PRESS_DOWN,       button_callback);

button_attach(&button1, PRESS_UP,         button_callback);

//button_attach(&button1, PRESS_REPEAT,     button_callback);

//button_attach(&button1, SINGLE_CLICK,     button_callback);

//button_attach(&button1, DOUBLE_CLICK,     button_callback);

//button_attach(&button1, LONG_RRESS_START, button_callback);

//button_attach(&button1, LONG_PRESS_HOLD,  button_callback);

⑤ 启动按键 启动按键的API如下：

接着在main函数中，while(1)之前编写代码，启动按键：

//启动按键

button_start(&button1);

⑥ 设置一个5ms间隔的定时器循环调用后台处理函数

这里就要用到systick了，在main函数的while(1)循环中编写如下代码：

  /* Infinite loop */

  /* USER CODE BEGIN WHILE */

  while (1)

  {

    /* USER CODE END WHILE */

    /* USER CODE BEGIN 3 */

  //每隔5ms调用一次后台处理函数

  button_ticks();

  HAL_Delay(5);

  }

  /* USER CODE END 3 */

2.4. 实验现象

编译、下载之后，每次按下Key1时打印按下提示，松开Key1时打印松开提示：

2.5. 扩展实验

在注册回调函数时将这按下和松开屏蔽，将单击和双击打开进行测试：

//注册按钮事件回调函数

//button_attach(&button1, PRESS_DOWN,       button_callback);

//button_attach(&button1, PRESS_UP,         button_callback);

//button_attach(&button1, PRESS_REPEAT,     button_callback);

button_attach(&button1, SINGLE_CLICK,     button_callback);

button_attach(&button1, DOUBLE_CLICK,     button_callback);

//button_attach(&button1, LONG_RRESS_START, button_callback);

//button_attach(&button1, LONG_PRESS_HOLD,  button_callback);

再测试长按：

//注册按钮事件回调函数

//button_attach(&button1, PRESS_DOWN,       button_callback);

//button_attach(&button1, PRESS_UP,         button_callback);

//button_attach(&button1, PRESS_REPEAT,     button_callback);

//button_attach(&button1, SINGLE_CLICK,     button_callback);

//button_attach(&button1, DOUBLE_CLICK,     button_callback);

button_attach(&button1, LONG_RRESS_START, button_callback);

button_attach(&button1, LONG_PRESS_HOLD,  button_callback);

3. MultiButton设计思想解读

3.1. 面向对象思想

MultiButton中每个按键都抽象为了一个按键对象，每个按键对象是独立的，系统中所有的按键对象使用单链表串起来，结构如下：

其中在变量后面跟冒号的语法称为位域，使用位域的优势是节省内存。

比如在这个结构体中，本来 6 个uint8_t 类型的变量需要占用 6 个字节，但使用位域语法后，这6个变量只占用两个字节：

3.2. 按键对象单链表

MultiButton自己定义了一个头指针：

//button handle list head.

static struct Button* head_handle = NULL;

用户插入一个按键对象的代码如下：

//启动按键

button_start(&button1);

那么，button_start插入新的按键对象之后，单链表长啥样呢？

理解了 button_start 的源码就很好知道答案了：

第一次插入时，因为head_hanler 为 NULL，所以只需要执行while之后的代码，

按照它的插入于原理，如果再插入一个buuton2按键对象，结果是不是可以猜出来了呢？

没错，它长这样：

这样做是不是有点不符合常理？后插入Button2竟然在button1前面，凭什么？

这又不是排队抢鸡蛋，在前在后没什么关系的。只是这样的插入方法在代码算法上会非常简洁，两行代码完成插入。

3.3. 状态机处理思想

MultiButton中使用状态机来处理每个按键对象（的状态），比如在上述应用中根据Systick提供的时基信号，每隔5ms调用一次 button_tick()，该函数会依次调用状态机对单链表上的所有按键对象进行遍历处理：

根据上一节的单链表讲解，系统中定义的链表头指针 head_handle 永远指向最后一个插入的按键对象，所以无需任何参数即可遍历整个单链表上的对象，非常之牛逼。

使用 button_handler 来对按键对象的状态进行处理，该函数源码如下：

（读源码的时候只需要记住该函数每隔5ms进入一次就很好分析了）

① 读取当前引脚状态

调用该按键对象注册的读取状态函数进行读取：

② 读取之后，判断当前状态机的状态，如果有功能正在执行（state不为0），则按键对象的tick值加1（后续一切功能的基础）：

③ 按键消抖（连续读取3次，15ms，如果引脚状态一直与之前不同，则改变按键对象中的引脚状态）：

④ 状态机（整个设计的灵魂所在）