STM32按键状态机：取代延时消抖，优雅实现单击双击长按

简介：面向嵌入式单片机开发者，STM32按键状态机工程围绕单击、双击、长按三类操作实现单按键多事件识别，运用定时器中断与状态机思想，将按键事件按时间窗口划分为短按和长按，可迁移至台灯调控、菜单切换等实际交互场景。压缩包共79个文件，以33个.h头文件、32个.c源文件为核心，含标准外设库、TIM定时器、按键驱动、串口打印及LED灯工程代码，另附hex固件、启动文件和README说明，整体约182KB，目录分级清楚，便于移植和二次开发。已有6787人浏览学习，适合初学STM32或希望规范按键处理逻辑的开发者。借助工程代码可掌握定时器中断配置、状态迁移设计及短按长按时间判定方法，也可根据需求调整状态机实现连按或组合键功能，进一步提升驱动代码的复用能力。

1. 为什么我不再用延时消抖：一次真实翻车

前阵子帮朋友调一个STM32项目，需求是单个按键同时支持单击、双击和长按三个操作。他第一版用的是最基础的延时消抖：按下延时20ms，抬起再延时20ms，单单测单击完全正常。等把双击逻辑一加进去，程序就开始"精神分裂"——消抖延时还没跑完，双击窗口已经溜走；单击动作刚想触发，长按计时又不知道从哪个节点算起。最后我在工位上把代码推倒重来，换成按键状态机，半小时把三个操作全部理顺。

这事其实不能全怪延时消抖。它是最多入门教程在教的方法，简单、直观，一个引脚加两个延时就能用。但它的核心缺陷是阻塞：延时期间CPU被挂起，整个系统都得等按键安静下来。单按键单功能时感觉不明显，一旦要把多个动作组合起来，消抖、等待双击、判断长按都是需要并发管理的时间轴，顺序执行的延时根本扛不住。状态机方案的本质，是把按键当成一个消息源，不管用户怎么按，驱动层只负责产出"按下"和"抬起"这类稳定事件，再由一套状态转移规则去判定最终应该输出哪个动作。

这套设计我在量产产品上反复用过：耳机侧键、手持设备功能键、面板菜单键，都是同一份代码改改参数就上。它不依赖具体库，HAL、LL、标准外设库都能接；裸机、RTOS也都能跑。接下来我把思路、代码、参数调节和踩坑点完整过一遍，想直接用的照着抄就行，想按自己项目改也完全来得及。和单纯背代码相比，我更建议你把背后的分层思路带走，后面换芯片、加按键、加手势，改起来都会顺手很多。

1.1 双击需求才是压垮延时方案的最后一根稻草

双击识别有个硬性前提：系统要记下"上次抬起的时间点"，并在一个固定时间窗口内判断是否再次按下。如果用延时等待来实现，第一次抬起后就要在延时里空等400ms，这期间主循环被卡死，屏幕刷新、传感器读取这些任务全部瘫痪。更麻烦的是长按还要持续监测按下时长，三种操作各有各的计时维度，用延时写就是三层嵌套地狱，改一个逻辑就要牵动另外两处，调试到自己都分不清当前在第几层。

状态机方案把这些复杂的并发计时拆成了另一个思路：每个操作对应一个状态，每次电平变化只是触发状态跳转的事件，时间流逝通过周期函数累加判断。各个时序互不阻塞，互不干扰，代码自然就清晰了。这也是我在面试里经常提醒候选人的点——按键驱动写得好不好，不是看你会不会读引脚，而是看你怎么管理时间这个隐形的输入。

1.2 状态机的本质：把连续时间轴切成离散事件

生活里有个很贴切的类比：状态机就像一个十字路口的信号灯，它不在乎路上有多少辆车，只关心当前是什么灯、来了什么车，然后决定放行还是等待。按键状态机也一样——它不在乎GPIO电平变化的每一个微小波动，只关心两件事：当前处于哪个状态，来了什么事件。

消抖层把不稳定的电平台阶过滤成稳定的"按下/抬起"消息，状态机层再依据这些消息和当前状态决定输出单击、双击还是长按。这种离散化的好处是，任何一个时刻系统的行为都是可预测、可复现的：按下、抬起、超时、长按，都被定义成了明确的触发条件。你不需要去推算"现在到底过了多少毫秒、用户按到第几下"，只需要查状态表，看当前状态应该做什么反应。

2. 按键状态机的三层骨架：扫描、识别、执行

2.1 扫描层：稳定的电平才配称为事件

我习惯把整个按键驱动拆成三层。最底层是扫描层，每隔固定周期读取一次GPIO电平，连续几次读到相同电平才认为电平稳定，这个稳定状态发生变化时，才产生一个"按下"或"抬起"事件。

这样设计的原因是物理按键在按下和弹起的瞬间会产生机械抖动，抖动时间通常在5到20ms，个别手感差的按键能到30ms。如果读一次电平就直接下结论，极容易把一次按压拆成好几段脉冲，状态机收到的就是乱序事件流。扫描周期的选取直接影响消抖时长和响应速度，我一般取10ms，连续3次相同则确认，实际消抖大约20到30ms，既能滤掉抖动，又不至于让快速连击丢失。单片机的10ms扫描间隔对绝大多数人操作来说绰绰有余，人最快一秒也就按十几次，单次按压至少持续几十毫秒，根本不会漏。

2.2 识别层：一张表管住全部状态

中间层是状态机本体。它只接收扫描层送来的稳定事件，用四个状态完成所有判定：空闲IDLE、按下PRESSED、长按LONG_PRESSED、等待二次点击CLICK_WAIT。

按下时从空闲进入按下状态，按住超过长按阈值就转入长按状态；短按抬起后进入等待窗口，窗口内再按下则累积为第二次点击，窗口超时才输出对应的双击或单击。这里有一个关键设计思想：识别层不关心GPIO电平和消抖参数，只关心抽象事件；上层怎么消费这个按键，识别层也不关心。边界划分清楚之后，每一层都能独立测试、独立替换，这也是状态机方案能长期复用而不散架的根本原因。

2.3 执行层：回调函数与业务解耦

执行层是用户代码真正关心的地方。状态机识别出某个动作后，通过回调函数通知业务层，业务层只需要在回调里做具体事情：切换菜单、调节音量、点亮屏幕，随你定义。

回调机制的优点在于让驱动和业务彻底解耦。按键驱动不知道也不关心这个按键会去开灯还是暂停播放，它只负责把"单击""双击""长按"这些动作准确地上报出去。对裸机项目，回调里通常只做置标志位或把动作塞进一个全局事件队列，真正耗时的工作放到主循环处理；对RTOS项目，可以配合消息队列把动作发给对应任务。这样按键驱动的代码几乎不用改，业务怎么变都不影响它。

3. 可直接抄作业的STM32实现：代码逐段解读

3.1 参数与数据结构：所有手感都集中在这几个宏里

先定义参数宏，整个驱动可调的核心都集中在这里。产品调试阶段只需要改宏，不用碰逻辑，这是我认为一个驱动模块应该有的基本素养——参数和代码分离。

#define KEY_SCAN_PERIOD_MS 10 // 扫描周期，单位ms #define KEY_DEBOUNCE_CNT 3 // 连续稳定次数 #define KEY_LONG_PRESS_MS 1000 // 长按判定阈值 #define KEY_LONG_REPEAT_MS 300 // 长按重复上报间隔 #define KEY_DOUBLE_WINDOW_MS 400 // 双击等待窗口

长按判定设1000ms，双击等待窗口设400ms，这是多数消费类产品比较通用的手感区间。但这不是绝对的，后面我会专门讲这些参数怎么按产品场景调整。动作和状态的枚举定义如下：

typedef enum { KEY_ACT_NONE = 0, KEY_ACT_SINGLE, // 单击 KEY_ACT_DOUBLE, // 双击 KEY_ACT_LONG_START, // 长按开始 KEY_ACT_LONG_REPEAT, // 长按重复触发 KEY_ACT_LONG_END // 长按释放 } key_action_t; typedef enum { KEY_EVT_NONE = 0, KEY_EVT_PRESSED, // 稳定按下事件 KEY_EVT_RELEASED // 稳定抬起事件 } key_evt_t; typedef enum { KEY_STATE_IDLE = 0, KEY_STATE_PRESSED, KEY_STATE_LONG_PRESSED, KEY_STATE_CLICK_WAIT } key_state_t;

动作枚举里的LONG_REPEAT很多人会忽略，但做音量长按连续加减、台灯无级调光这类功能非常有用，按住不松手就能周期性输出事件。按键结构体则把硬件引脚信息、滤波状态、状态机状态、输出回调全部收进一个对象：

typedef struct { GPIO_TypeDef *port; // 引脚所属端口 uint16_t pin; // 引脚号 uint8_t active_level; // 按下时电平：1为高电平按下，0为低电平按下 uint8_t stable_level; // 当前稳定的电平状态 uint8_t db_cnt; // 消抖计数 uint8_t state; // 当前状态机状态 uint16_t press_tick; // 按下持续计时 uint16_t repeat_tick; // 长按重复计时 uint16_t wait_tick; // 双击等待计时 uint8_t click_cnt; // 连续点击次数 void (*on_action)(key_action_t action); } key_t;

把硬件信息、滤波状态、状态机状态和回调全部放一个结构体，好处是一份代码可以管理任意多个按键，后面做矩阵键盘只需要定义结构体数组，不需要复制粘贴驱动逻辑。

3.2 消抖扫描与事件生产：给电平变化加一道门槛

扫描函数每个周期调用一次。它做的事情很简单：读引脚电平，和上次稳定电平比较，不一样就累计计数，连续KEY_DEBOUNCE_CNT次才翻转稳定电平，同时产生对应事件。这个写法相当于给电平变化加了一道"门槛"，杂散抖动过不了门槛，自然就被过滤掉。

void key_scan(key_t *k) { uint8_t raw = (HAL_GPIO_ReadPin(k->port, k->pin) == k->active_level) ? 1 : 0; if (raw != k->stable_level) { if (++k->db_cnt >= KEY_DEBOUNCE_CNT) { k->db_cnt = 0; k->stable_level = raw; key_evt_dispatch(k, raw ? KEY_EVT_PRESSED : KEY_EVT_RELEASED); } } else { k->db_cnt = 0; } }

有人会问：为什么不把消抖也放进状态机里？那样状态会多出"按下消抖中""抬起消抖中"，状态表会膨胀一倍，维护成本变高。把消抖放在扫描层，状态机只接收已经稳定的边沿事件，逻辑划分更干净。这个分离思路和实际项目里的"接口层下沉"是一个道理——底层把脏活累活干完，上层才能专注业务。

3.3 状态机事件分发：核心逻辑拆开看

事件分发是状态机的核心。所有事件进来都先切到当前状态，再看这个状态下能接受什么事件，做出对应的动作和状态跳转。这里不要写一堆if嵌套，直接把每种状态写成一个case，后面加状态、加动作都清晰得多。

void key_evt_dispatch(key_t *k, key_evt_t evt) { switch (k->state) { case KEY_STATE_IDLE: if (evt == KEY_EVT_PRESSED) { k->state = KEY_STATE_PRESSED; k->press_tick = 0; k->click_cnt = 1; } break; case KEY_STATE_PRESSED: if (evt == KEY_EVT_RELEASED) { k->state = KEY_STATE_CLICK_WAIT; k->wait_tick = 0; } break; case KEY_STATE_LONG_PRESSED: if (evt == KEY_EVT_RELEASED) { k->state = KEY_STATE_IDLE; if (k->on_action) { k->on_action(KEY_ACT_LONG_END); } } break; case KEY_STATE_CLICK_WAIT: if (evt == KEY_EVT_PRESSED) { k->state = KEY_STATE_PRESSED; k->press_tick = 0; k->click_cnt++; } break; default: break; } }

特别注意LONG_PRESSED状态的释放处理：这里直接回到IDLE并上报LONG_END，而不会进入CLICK_WAIT。这就是长按释放不触发单击的关键。没有这个分支，长按一松开系统就会把它当成一次普通短按，屏幕上就会同时出现长按和单击两个动作，交互逻辑立刻乱套。这个细节我在很多开源项目里都见人踩过，所以特意单独点出来。

3.4 定时逻辑：长按、重复、双击窗口全靠它驱动

周期处理函数每10ms调用一次，负责所有和时间相关的判定。它不借助任何硬件定时器，纯粹靠调用次数乘扫描周期来计算时间，这样代码可以平移到任何平台，也方便在单元测试里手动模拟。函数里三个分支分别对应按下计时、长按重复计时、双击窗口计时。

void key_tick(key_t *k) { switch (k->state) { case KEY_STATE_PRESSED: k->press_tick++; if (k->press_tick * KEY_SCAN_PERIOD_MS >= KEY_LONG_PRESS_MS) { k->state = KEY_STATE_LONG_PRESSED; k->repeat_tick = 0; if (k->on_action) { k->on_action(KEY_ACT_LONG_START); } } break; case KEY_STATE_LONG_PRESSED: k->repeat_tick++; if (k->repeat_tick * KEY_SCAN_PERIOD_MS >= KEY_LONG_REPEAT_MS) { k->repeat_tick = 0; if (k->on_action) { k->on_action(KEY_ACT_LONG_REPEAT); } } break; case KEY_STATE_CLICK_WAIT: k->wait_tick++; if (k->wait_tick * KEY_SCAN_PERIOD_MS >= KEY_DOUBLE_WINDOW_MS) { if (k->click_cnt >= 2) { if (k->on_action) { k->on_action(KEY_ACT_DOUBLE); } } else { if (k->on_action) { k->on_action(KEY_ACT_SINGLE); } } k->state = KEY_STATE_IDLE; k->click_cnt = 0; } break; default: break; } }

PRESSED分支里，按下时间累计达到1000ms，直接切到LONG_PRESSED并上报LONG_START。这意味着长按动作可能在用户还没有松手时就先触发，这也是大多数产品的预期行为——比如按住电源键，屏幕先响应长按，松手再执行后续动作。而CLICK_WAIT分支的判单判双，是通过窗口超时来完成的，具体逻辑下面用状态转移表汇总更直观。

3.5 初始化、周期调用与回调

static key_t g_key; void key_init(key_t *k, GPIO_TypeDef *port, uint16_t pin, uint8_t active_level, void (*cb)(key_action_t)) { k->port = port; k->pin = pin; k->active_level = active_level; k->stable_level = !active_level; k->db_cnt = 0; k->state = KEY_STATE_IDLE; k->click_cnt = 0; k->on_action = cb; } void key_periodic(void) { key_scan(&g_key); key_tick(&g_key); }

使用时，在main里先初始化：

key_init(&g_key, GPIOC, GPIO_PIN_13, 0, on_key_action);

这是典型的低电平按下接法，GPIOC13拉低表示按下。然后配置一个10ms周期的定时器中断，在中断里调用key_periodic。回调函数里写业务逻辑：

void on_key_action(key_action_t action) { switch (action) { case KEY_ACT_SINGLE: printf("action: single\r\n"); break; case KEY_ACT_DOUBLE: printf("action: double\r\n"); break; case KEY_ACT_LONG_START: printf("action: long start\r\n"); break; case KEY_ACT_LONG_REPEAT: printf("action: long repeat\r\n"); break; case KEY_ACT_LONG_END: printf("action: long end\r\n"); break; default: break; } }

我把五种动作全部列出来了，实际产品不一定全用。比如某个按键只做单击和长按，那就在回调里忽略DOUBLE和LONG_REPEAT，代码不用动。这套接口设计的好处是，后续要给按键增加动作类型，只需要在枚举里加一项、在回调里加一个case，驱动本身不用大改。

3.6 一张状态转移表看懂全部行为

把上面的代码逻辑浓缩成状态转移表，排错的时候对着表查比对着代码猜快得多：

这张表也是我写代码之前先画的。先明确每一个状态在什么条件下做什么事，再落成代码，基本不会写出绕来绕去的逻辑。反过来，如果你拿到一段按键代码看不懂，把它还原成状态转移表，思路也就立刻清晰了。

4. 这些参数和边界，实测后才知道

4.1 消抖次数、双击窗口、长按阈值怎么定

三个时间参数是互相牵制的。消抖次数设太小，机械抖动没滤干净，一次按下可能被拆成多次事件；设太大，快速连击会丢。我在普通轻触开关上用20到30ms消抖很稳，但如果是手感很差的锅仔片或者受潮老化的按键，可能要把消抖放宽到50ms。

双击窗口影响的是操作手感。400ms是多数人觉得自然的区间：太快，老年人或手速慢的用户会按不出双击；太慢，普通的两次单击又容易被误判成一个双击。长按阈值主要看产品语义，1000ms是通用值，但像"关机需长按3秒"这种强确认操作，就应该单独拉高到3000ms，防止误触。我调参的方法很笨但很有效：把参数定义成宏，样机阶段反复试，直到团队所有人都觉得"手感对了"再定稿。

4.2 长按后松手，绝不触发单击

这是最容易踩的坑。如果没有LONG_PRESSED状态的分流，长按释放时就会走进CLICK_WAIT，然后窗口超时输出一个SINGLE。结果就是用户长按调音量，松手的瞬间又跳出一个单击切换界面，属于典型的事故现场。

代码里的设计是进入长按状态后，释放事件单独处理，直接回IDLE并上报LONG_END，完全绕开双击等待窗口。如果你在别人的代码里看到"长按和单击同时出现"的诡异现象，九成是这里的分流没做对。哪怕你自己重新设计状态机，也要确保长按释放这条路径被单独覆盖，不要让它漏进短按判定逻辑。

4.3 单击输出延迟：双击功能的代价与取舍

双击判定存在一个天然代价：第一次短按抬起后，系统并不能立刻确定这是单击还是双击，必须等满400ms窗口超时。于是单击动作的输出会被延后大约400ms，这是所有"单击+双击"共存方案都绕不开的取舍。

对大多数菜单、设置类界面，400ms延迟用户基本无感。但如果你做一个游戏按键、相机快门，单击要求毫秒级响应，双击又不能丢，那就要换策略。我见过一种折中方案：短按抬起后先立即上报单击，假如窗口内又按下一次，再补报一个"单击撤销+双击确认"的修正消息，由上层自行处理。这种做法响应快但业务处理复杂，会引入撤销逻辑的额外成本，我只有在性能要求特别苛刻的产品上才用，常规项目老老实实等窗口超时反而更稳。

4.4 悬浮电平、按到一半松手、连击乱序

还有几个边界情况要留神。第一，引脚悬空时电平不稳定，硬件上最好加上拉或下拉电阻，软件侧在初始化时要把stable_level设置成非按下电平，防止上电瞬间误触发。第二，按下不足一个扫描周期就松开，消抖层不会认为它按下过，也不会进入状态机，相当于被忽略，这是正常现象，不算bug，人手的正常按键操作远长于这个时间。第三，连续快速点击超过两次时，比如三击甚至四击，当前状态会在PRESSED和CLICK_WAIT之间往返，click_cnt会累加到3、4，窗口超时只会输出DOUBLE，不会输出三击。如果你未来想做三击和四击，只要把超时分支改成按click_cnt值分发即可，状态机骨架完全不用动。

5. 把状态机塞进真实项目：中断、RTOS与多按键

5.1 轮询还是定时器中断

扫描周期必须稳定，否则以周期推算出的各种时间阈值全部会漂。我在裸机上一般用一个基础定时器产生10ms中断，在中断里调用key_periodic，这是最稳的做法。主循环可能因为串口打印、Flash写入这些耗时操作产生抖动，但只要定时器中断优先级合理，按键扫描就不受影响。

如果你不想占用一个定时器，也可以在主循环里轮询，前提是主循环单次执行时间要远小于扫描周期，并且不要在按键扫描附近放长阻塞。需要特别说明的是，中断里执行扫描和状态机本身非常快，几个微秒的事，不会把系统压垮。真正要注意的是不要在回调里做耗时业务，这个习惯比选哪种扫描方式更重要。

5.2 多按键复用与事件队列

多个按键时，不需要复制粘贴代码，只要准备多个key_t结构体，在key_periodic里循环处理即可。以两个按键为例，初始化两个结构体，周期函数里依次调用两个按键的扫描和tick，回调函数通过参数区分是哪个按键触发的。如果按键数量多，就把结构体定义成数组，配合for循环遍历。

真正要注意的是回调执行时机：如果回调直接在中断里执行业务，等于把一个长操作塞进了中断上下文，很容易影响系统实时性。我习惯在回调里只做一件事——把动作写进一个全局环形队列，返回后再由主循环或专用任务去消费。这样按键扫描和业务执行节奏完全分开，系统结构更健康。

5.3 RTOS和低功耗场景的注意点

在RTOS里，如果能保持定时器中断扫描，就沿用裸机方案，按键驱动跑在中断上下文，业务消费放到任务里，配合消息队列使用非常顺手。如果坚持把扫描放进一个任务，务必让该任务优先级足够高，避免按键扫描被其他任务长时间打断导致丢事件。

低功耗场景要特别小心：睡眠时定时器可能停摆，如果用户按着按键从睡眠中唤醒，唤醒瞬间的时间基准很可能不对，导致本来只按了200ms却被判定成1000ms长按。我的处理方式是在唤醒流程里主动重置所有按键状态机，让用户唤醒后重新按键，不做跨睡眠周期的事件拼凑。这个坑在带低功耗需求的产品里特别常见，等你在测试中发现"睡一晚起来按键疯了"的时候，往往就是这里的问题。

5.4 从单击双击长按继续扩展

这套骨架的扩展性比想象中强。做连按计数，改CLICK_WAIT超时分支；做组合键，可以给每个按键动作编号，在上层维护一个动作掩码；做手势滑动，也只是把扫描层从读GPIO换成读ADC或编码器。状态机的核心思想——分层、事件驱动、状态转移——是通用的，换硬件只是换扫描层，识别和执行层基本原样保留。

我在新项目里一般先搭这套按键状态机再写业务逻辑，相当于给产品先配好一套稳定的输入交互入口，后面所有功能都在这套入口上长出来。回头再看，当初那版延时消抖被推翻其实是件好事，逼着我把按键驱动真正做成了可复用的模块。希望这篇笔记也能帮你少走一段弯路。

本文还有配套的精品资源，点击获取