分享一款嵌入式開源按鍵框架程式碼工程MultiButton

一、工程簡介

　　MultiButton 是一個小巧簡單易用的事件驅動型按鍵驅動模組。

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

　　這個專案非常精簡，只有兩個檔案：

　　（1）可無限擴充套件按鍵；

　　（2）按鍵事件的回撥非同步處理方式可以簡化程式結構，去除冗餘的按鍵處理硬編碼，讓按鍵業務邏輯更清晰。

　　透過此工程可以學習到以下知識點：

　　（1）按鍵各種型別事件；

　　（2）狀態機的思想；

　　（3）單向連結串列語法。

　　工程支援如下的按鍵事件：

　　MultiButton 的按鍵狀態及軟體流程圖：

二、工程程式碼分析

　　注：在使用原始碼工程時稍微修改了兩個點，後續貼出修改後的完整程式碼，有需要檢視修改的同學可以將原始碼工程下載後進行對比，修改的點如下：

　　（1）將按鍵時間的相關引數透過介面定義進行初始化；

　　（2）修改按鍵長按期間一直觸發事件為真正的長按按鍵定時觸發事件。

　　在標頭檔案multi_button.h中包括：

　　（1）定義了按鍵時間相關引數；

　　（2）定義了按鍵的事件型別；

　　（3）定義按鍵連結串列結構體，這裡使用了位域操作，解決位元組的儲存空間問題。

#ifndef _MULTI_BUTTON_H_
#define _MULTI_BUTTON_H_
 
#include <stdint.h>
#include <string.h>
 
typedef struct ButtonPara {
  uint8_t ticks_interval;
  uint8_t debounce_ticks;
  uint16_t short_ticks;
  uint16_t long_ticks;
}ButtonPara;
 
typedef void (*BtnCallback)(void*);
 
typedef enum {
  PRESS_DOWN = 0,
  PRESS_UP,
  PRESS_REPEAT,
  SINGLE_CLICK,
  DOUBLE_CLICK,
  LONG_PRESS_START,
  LONG_PRESS_HOLD,
  number_of_event,
  NONE_PRESS
}PressEvent;
 
typedef struct Button {
  uint16_t ticks;
  uint8_t  repeat : 4;
  uint8_t  event : 4;
  uint8_t  state : 3;
  uint8_t  debounce_cnt : 3;
  uint8_t  active_level : 1;
  uint8_t  button_level : 1;
  uint8_t  button_id;
  uint8_t  (*hal_button_Level)(uint8_t button_id_);
  BtnCallback  cb[number_of_event];
  struct Button* next;
}Button;
 
#ifdef __cplusplus
extern "C" {
#endif
void button_para_init(struct ButtonPara para);
void button_init(struct Button* handle, uint8_t(*pin_level)(uint8_t), uint8_t active_level, uint8_t button_id);
void button_attach(struct Button* handle, PressEvent event, BtnCallback cb);
PressEvent get_button_event(struct Button* handle);
int  button_start(struct Button* handle);
void button_stop(struct Button* handle);
void button_ticks(void);
 
#ifdef __cplusplus
}
#endif
 
#endif

　　在原始碼檔案multi_button.c中包括：

　　（1）對按鍵時間引數進行初始化；

　　（2）對按鍵物件結構體進行初始化，初始化成員包括按鍵控制代碼，繫結GPIO電平讀取函式，設定有效觸發電平；

　　（3）初始化按鍵完成之後，進行按鍵繫結操作，將繫結按鍵結構體成員，按鍵觸發事件，按鍵回撥函式；

　　（4）按鍵啟動：也就是將按鍵加入連結串列當中，啟動按鍵。這裡選擇的插入方式是頭部插入法，在連結串列的頭部插入按鍵節點，效率高，時間複雜度為O(1)；

　　（5）按鍵刪除：將按鍵從當前連結串列中刪除。使用到了二級指標刪除一個按鍵元素。與連結串列中成員刪除方法相同；

　　（6）按鍵滴答函式：每間隔Nms觸發一次按鍵事件，驅動狀態機執行；

　　（7）讀取當前引腳的狀態，獲取按鍵當前屬於哪種狀態；

　　（8）按鍵處理核心函式，驅動狀態機。

#include "multi_button.h"
 
#define EVENT_CB(ev)   if(handle->cb[ev])handle->cb[ev]((void*)handle)
#define PRESS_REPEAT_MAX_NUM  15 /*!< The maximum value of the repeat counter */
 
static struct ButtonPara buttonpara;
//button handle list head.
static struct Button* head_handle = NULL;
 
static void button_handler(struct Button* handle);
 
 
void button_para_init(struct ButtonPara para)
{
  buttonpara.ticks_interval = para.ticks_interval;
  buttonpara.debounce_ticks = para.debounce_ticks;
  buttonpara.short_ticks = para.short_ticks;
  buttonpara.long_ticks = para.long_ticks;
}
/**
  * @brief  Initializes the button struct handle.
  * @param  handle: the button handle struct.
  * @param  pin_level: read the HAL GPIO of the connected button level.
  * @param  active_level: pressed GPIO level.
  * @param  button_id: the button id.
  * @retval None
  */
void button_init(struct Button* handle, uint8_t(*pin_level)(uint8_t), uint8_t active_level, uint8_t button_id)
{
  memset(handle, 0, sizeof(struct Button));
  handle->event = (uint8_t)NONE_PRESS;
  handle->hal_button_Level = pin_level;
  handle->button_level = handle->hal_button_Level(button_id);
  handle->active_level = active_level;
  handle->button_id = button_id;
}
 
/**
  * @brief  Attach the button event callback function.
  * @param  handle: the button handle struct.
  * @param  event: trigger event type.
  * @param  cb: callback function.
  * @retval None
  */
void button_attach(struct Button* handle, PressEvent event, BtnCallback cb)
{
  handle->cb[event] = cb;
}
 
/**
  * @brief  Inquire the button event happen.
  * @param  handle: the button handle struct.
  * @retval button event.
  */
PressEvent get_button_event(struct Button* handle)
{
  return (PressEvent)(handle->event);
}
 
/**
  * @brief  Button driver core function, driver state machine.
  * @param  handle: the button handle struct.
  * @retval None
  */
static void button_handler(struct Button* handle)
{
  uint8_t read_gpio_level = handle->hal_button_Level(handle->button_id);
 
  //ticks counter working..
  if((handle->state) > 0) handle->ticks++;
 
  /*------------button debounce handle---------------*/
  if(read_gpio_level != handle->button_level) { //not equal to prev one
    //continue read 3 times same new level change
    if(++(handle->debounce_cnt) >= buttonpara.debounce_ticks) {
      handle->button_level = read_gpio_level;
      handle->debounce_cnt = 0;
    }
  } else { //level not change ,counter reset.
    handle->debounce_cnt = 0;
  }
 
  /*-----------------State machine-------------------*/
  switch (handle->state) {
  case 0:
    if(handle->button_level == handle->active_level) {  //start press down
      handle->event = (uint8_t)PRESS_DOWN;
      EVENT_CB(PRESS_DOWN);
      handle->ticks = 0;
      handle->repeat = 1;
      handle->state = 1;
    } else {
      handle->event = (uint8_t)NONE_PRESS;
    }
    break;
 
  case 1:
    if(handle->button_level != handle->active_level) { //released press up
      handle->event = (uint8_t)PRESS_UP;
      EVENT_CB(PRESS_UP);
      handle->ticks = 0;
      handle->state = 2;
    } else if(handle->ticks > buttonpara.long_ticks) {
      handle->event = (uint8_t)LONG_PRESS_START;
      EVENT_CB(LONG_PRESS_START);
      handle->state = 5;
    }
    break;
 
  case 2:
    if(handle->button_level == handle->active_level) { //press down again
      handle->event = (uint8_t)PRESS_DOWN;
      EVENT_CB(PRESS_DOWN);
      if(handle->repeat != PRESS_REPEAT_MAX_NUM) {
        handle->repeat++;
      }
      EVENT_CB(PRESS_REPEAT); // repeat hit
      handle->ticks = 0;
      handle->state = 3;
    } else if(handle->ticks > buttonpara.short_ticks) { //released timeout
      if(handle->repeat == 1) {
        handle->event = (uint8_t)SINGLE_CLICK;
        EVENT_CB(SINGLE_CLICK);
      } else if(handle->repeat == 2) {
        handle->event = (uint8_t)DOUBLE_CLICK;
        EVENT_CB(DOUBLE_CLICK); // repeat hit
      }
      handle->state = 0;
    }
    break;
 
  case 3:
    if(handle->button_level != handle->active_level) { //released press up
      handle->event = (uint8_t)PRESS_UP;
      EVENT_CB(PRESS_UP);
      if(handle->ticks < buttonpara.short_ticks) {
        handle->ticks = 0;
        handle->state = 2; //repeat press
      } else {
        handle->state = 0;
      }
    } else if(handle->ticks > buttonpara.short_ticks) { // SHORT_TICKS < press down hold time < LONG_TICKS
      handle->state = 1;
    }
    break;
 
  case 5:
    if(handle->button_level == handle->active_level) {
      //continue hold trigger
      if(handle->ticks > buttonpara.long_ticks) {
      handle->event = (uint8_t)LONG_PRESS_HOLD;
      EVENT_CB(LONG_PRESS_HOLD);
      handle->ticks = 0;
      }
    } else { //released
      handle->event = (uint8_t)PRESS_UP;
      EVENT_CB(PRESS_UP);
      handle->state = 0; //reset
    }
    break;
  default:
    handle->state = 0; //reset
    break;
  }
}
 
/**
  * @brief  Start the button work, add the handle into work list.
  * @param  handle: target handle struct.
  * @retval 0: succeed. -1: already exist.
  */
int button_start(struct Button* handle)
{
  struct Button* target = head_handle;
  while(target) {
    if(target == handle) return -1;  //already exist.
    target = target->next;
  }
  handle->next = head_handle;
  head_handle = handle;
  return 0;
}
 
/**
  * @brief  Stop the button work, remove the handle off work list.
  * @param  handle: target handle struct.
  * @retval None
  */
void button_stop(struct Button* handle)
{
  struct Button** curr;
  for(curr = &head_handle; *curr; ) {
    struct Button* entry = *curr;
    if(entry == handle) {
      *curr = entry->next;
//      free(entry);
      return;//glacier add 2021-8-18
    } else {
      curr = &entry->next;
    }
  }
}
 
/**
  * @brief  background ticks, timer repeat invoking interval 5ms.
  * @param  None.
  * @retval None
  */
void button_ticks(void)
{
  struct Button* target;
  for(target=head_handle; target; target=target->next) {
    button_handler(target);
  }
}

三、工程程式碼應用

　　以在freertos中應用為例，包括：

　　（1）按鍵物件的定義及時間引數定義；

　　（2）按鍵回撥函式包括讀取按鍵電平函式和各按鍵事件處理函式的編寫；

　　（3）按鍵初始化操作及啟動按鍵功能；

　　（4）在while(1)中新增按鍵滴答函式。

#define TICKS_INTERVAL    5  //按鍵狀態輪詢週期，單位ms
#define DEBOUNCE_TICKS    3  //MAX 7 (0 ~ 7) 去抖時間次數，此為15ms/TICKS_INTERVAL=3次
#define SHORT_TICKS       (300 /TICKS_INTERVAL) //短按時間次數，300ms/TICKS_INTERVAL 
#define LONG_TICKS        (2000 /TICKS_INTERVAL) //長按時間次數，2000ms/TICKS_INTERVAL
         
enum Button_IDs {
  btn1_id,
  btn2_id,
  btn3_id,
};
struct ButtonPara btnpara = {TICKS_INTERVAL, DEBOUNCE_TICKS, SHORT_TICKS, LONG_TICKS};
struct Button btn1;
struct Button btn2;
struct Button btn3;
 
//According to your need to modify the constants.
 
uint8_t read_button_GPIO(uint8_t button_id)
{
  // you can share the GPIO read function with multiple Buttons
  switch(button_id)
  {
    case btn1_id:
      return GPIO_ReadInputDataBit(GPIOE,GPIO_Pin_4);
    case btn2_id:
      return GPIO_ReadInputDataBit(GPIOE,GPIO_Pin_3);
    case btn3_id:
      return GPIO_ReadInputDataBit(GPIOE,GPIO_Pin_2);
    default:
      return 0;
  }
}
 
void BTN1_PRESS_DOWN_Handler(void* btn)
{
  printf("BTN1_PRESS_DOWN_Handler!\r\n");
}
 
void BTN1_PRESS_UP_Handler(void* btn)
{
  printf("BTN1_PRESS_UP_Handler!\r\n");
}
 
void BTN1_PRESS_REPEAT_Handler(void* btn)
{
  printf("BTN1_PRESS_REPEAT_Handler, repeatcount = %d!\r\n",btn1.repeat);
}
 
void BTN1_SINGLE_Click_Handler(void* btn)
{
  printf("BTN1_SINGLE_Click_Handler!\r\n");
}
 
void BTN1_DOUBLE_Click_Handler(void* btn)
{
  printf("BTN1_DOUBLE_Click_Handler!\r\n");
}
 
void BTN1_LONG_PRESS_START_Handler(void* btn)
{
  printf("BTN1_LONG_PRESS_START_Handler!\r\n");
}
 
void BTN1_LONG_PRESS_HOLD_Handler(void* btn)
{
  printf("BTN1_LONG_PRESS_HOLD_Handler!\r\n");
}
 
void BTN2_SINGLE_Click_Handler(void* btn)
{
  printf("BTN2_SINGLE_Click_Handler!\r\n");
}
 
void BTN2_DOUBLE_Click_Handler(void* btn)
{
  printf("BTN2_DOUBLE_Click_Handler!\r\n");
}
 
void BTN3_LONG_PRESS_START_Handler(void* btn)
{
  printf("BTN3_LONG_PRESS_START_Handler!\r\n");
}
 
void BTN3_LONG_PRESS_HOLD_Handler(void* btn)
{
  printf("BTN3_LONG_PRESS_HOLD_Handler!\r\n");
}
 
int main(void)
{ 
  button_para_init(btnpara);
  button_init(&btn1, read_button_GPIO, 0, btn1_id);
  button_init(&btn2, read_button_GPIO, 0, btn2_id);
  button_init(&btn3, read_button_GPIO, 0, btn3_id);
 
  button_attach(&btn1, PRESS_DOWN,       BTN1_PRESS_DOWN_Handler);
  button_attach(&btn1, PRESS_UP,         BTN1_PRESS_UP_Handler);
  button_attach(&btn1, PRESS_REPEAT,     BTN1_PRESS_REPEAT_Handler);
  button_attach(&btn1, SINGLE_CLICK,     BTN1_SINGLE_Click_Handler);
  button_attach(&btn1, DOUBLE_CLICK,     BTN1_DOUBLE_Click_Handler);
  button_attach(&btn1, LONG_PRESS_START, BTN1_LONG_PRESS_START_Handler);
  button_attach(&btn1, LONG_PRESS_HOLD,  BTN1_LONG_PRESS_HOLD_Handler);
 
  button_attach(&btn2, PRESS_REPEAT,     BTN2_PRESS_REPEAT_Handler);
  button_attach(&btn2, SINGLE_CLICK,     BTN2_SINGLE_Click_Handler);
  button_attach(&btn2, DOUBLE_CLICK,     BTN2_DOUBLE_Click_Handler);
  
  button_attach(&btn3, LONG_PRESS_START, BTN3_LONG_PRESS_START_Handler);
  button_attach(&btn3, LONG_PRESS_HOLD,  BTN3_LONG_PRESS_HOLD_Handler);
 
  button_start(&btn1);
  button_start(&btn2);
  button_start(&btn3);
  
 
  xTaskCreate((TaskFunction_t )key_task,             
                (const char*    )"key_task",           
                (uint16_t       )KEY_STK_SIZE,        
                (void*          )NULL,                  
                (UBaseType_t    )KEY_TASK_PRIO,        
                (TaskHandle_t*  )&KeyTask_Handler);              
    vTaskStartScheduler();          
}
 
 
void key_task(void *pvParameters)
{
  while(1)
  {
    button_ticks();
    vTaskDelay(5);      //5ms週期輪詢
  }
}

四、思考

　　使用中有如下問題值得思考：

　　（1）組合鍵和矩陣按鍵如何實現？

　　在函式uint8_t read_button_GPIO(uint8_t button_id)中進行組合鍵和矩陣按鍵返回值的自定義。

　　（2）多個按鍵時，按鍵引數進行區分？

　　去抖時間，短按時間，長按時間可以放在一個陣列中區分，各個按鍵定義各自的引數。

　　（3）現在按鍵事件較多的情況時，需要多個繫結的事件函式？

　　可以將按鍵事件函式統一放在一個陣列中進行初始化註冊。

---

↓↓↓更多技術內容和書籍資料獲取，入群技術交流敬請關注“明解嵌入式”↓↓↓