4、按键输入检测：GPIO输入模式配置、digitalRead函数、按键消抖原理与软件实现

按键，是嵌入式系统里最基础、也最容易被忽视的输入设备。你想想看，一个简单的开关动作，背后却藏着电平跳变、机械抖动、软件滤波这一连串问题。我刚开始做项目时，就因为在按键消抖上偷了懒，结果产品在客户现场频繁误触发，被售后同事追着骂了整整一周。

这一章，咱们就把按键输入这件事彻底讲透。从GPIO输入模式配置，到digitalRead的正确用法，再到消抖的几种软件实现——每一步我都会结合自己的踩坑经历来说。

4.1 GPIO输入模式配置

ESP32的GPIO引脚，默认是输入模式。但默认归默认，实际用的时候还是得显式配置一下。我习惯在setup()里把所有用到的引脚都明确声明，这样代码可读性更好，也方便后期维护。

void setup() {
    pinMode(KEY_PIN, INPUT);          // 浮空输入
    // 或者
    pinMode(KEY_PIN, INPUT_PULLUP);   // 内部上拉输入
    // 或者
    pinMode(KEY_PIN, INPUT_PULLDOWN); // 内部下拉输入
}

这里有个关键点：外部电路决定你用哪种模式。

4.2 digitalRead函数——别小看它

digitalRead(pin)，返回值只有两种：HIGH（1）或 LOW（0）。但你真的了解它的行为吗？

我曾经在一个项目里，用digitalRead读取一个按键，发现偶尔会读到错误电平。排查了半天，最后发现是GPIO引脚没有配置模式——默认输入，但内部上下拉都没开，引脚悬空，读到的值完全是随机的。

所以，使用digitalRead前，请确认三件事：

1. 引脚模式已配置——pinMode()必须调用过。
2. 外部电路正确——按键按下时，电平能稳定拉到VCC或GND。
3. 引脚号别搞错——ESP32的GPIO编号和开发板丝印可能不一致，建议用宏定义。

#define KEY_PIN  0   // 开发板上的BOOT按键，默认上拉

void setup() {
    Serial.begin(115200);
    pinMode(KEY_PIN, INPUT_PULLUP);
}

void loop() {
    int val = digitalRead(KEY_PIN);
    Serial.printf("Key state: %d\n", val);
    delay(100);
}

4.3 按键消抖——为什么需要？

机械按键，说白了就是两片金属簧片。按下时，它们不会干净利落地接触，而是会弹跳几次——就像你扔一个乒乓球到桌上，它会弹几下才停住。

这个弹跳过程，持续时间通常为5~20ms。在这段时间里，digitalRead会读到一连串的0和1交替变化。如果不做处理，你的程序可能会把一次按键识别成多次。

我在做智能家居面板时，就遇到过这个问题：用户按一下“开灯”，灯却闪了好几下。后来用示波器一看，按键信号上全是毛刺。

4.4 软件消抖的三种实现

硬件消抖（加RC滤波或施密特触发器）当然可靠，但会增加BOM成本。大多数场景下，软件消抖完全够用。下面是我常用的三种方法。

4.4.1 延时消抖（最简单，但阻塞）

bool readKeyDebounceDelay(int pin) {
    if (digitalRead(pin) == LOW) {      // 检测到按下
        delay(20);                       // 等20ms，跳过弹跳期
        if (digitalRead(pin) == LOW) {  // 再次确认
            return true;                 // 确实按下了
        }
    }
    return false;
}

优点：代码简单，容易理解。
缺点：delay()会阻塞程序，20ms内干不了别的事。如果系统里还有LED闪烁、串口通信等任务，就别用这个。

4.4.2 状态机消抖（非阻塞，推荐）

#define DEBOUNCE_TIME  20   // 消抖时间，单位ms

static int lastState = HIGH;
static unsigned long lastChangeTime = 0;

bool readKeyDebounceFSM(int pin) {
    int currentState = digitalRead(pin);
    bool keyPressed = false;

    if (currentState != lastState) {
        lastChangeTime = millis();  // 记录电平变化时刻
    }

    if ((millis() - lastChangeTime) > DEBOUNCE_TIME) {
        // 电平稳定超过20ms，认为有效
        if (currentState == LOW) {
            keyPressed = true;
        }
    }

    lastState = currentState;
    return keyPressed;
}

这个方法的精髓在于：不等待，只记录。每次循环都检查当前电平，如果发现变化就记下时间戳。只有当电平稳定超过20ms后，才判定为有效按键。

4.4.3 连续采样消抖（抗干扰更强）

bool readKeyDebounceSample(int pin) {
    static int count = 0;
    static int stableState = HIGH;

    int currentState = digitalRead(pin);

    if (currentState == stableState) {
        count = 0;
    } else {
        count++;
        if (count >= 5) {          // 连续5次采样都不同，才翻转状态
            stableState = currentState;
            count = 0;
            if (stableState == LOW) {
                return true;
            }
        }
    }
    return false;
}

这种方法适合噪声较大的环境。每次采样间隔（由主循环周期决定）如果稳定在5ms左右，连续5次不同就意味着至少25ms的稳定变化，可靠性很高。

4.5 三种消抖方法对比

4.6 本章知识结构图

下面这张图，把按键输入检测的完整流程串起来了。从GPIO配置到消抖判定，每一步都对应着实际代码。

4.7 完整示例：按键控制LED

把上面学到的知识串起来，写一个完整的例子：按键按下时，LED翻转状态。

#define KEY_PIN   0
#define LED_PIN   2

void setup() {
    Serial.begin(115200);
    pinMode(KEY_PIN, INPUT_PULLUP);
    pinMode(LED_PIN, OUTPUT);
    digitalWrite(LED_PIN, LOW);
}

void loop() {
    if (readKeyDebounceFSM(KEY_PIN)) {
        static bool ledState = false;
        ledState = !ledState;
        digitalWrite(LED_PIN, ledState);
        Serial.printf("LED: %s\n", ledState ? "ON" : "OFF");
    }
    // 这里可以干其他事，不会被阻塞
}

嗯，按键输入检测这部分，核心就这些。配置模式、读取电平、消抖处理，三步走。别嫌消抖麻烦——你想想看，一个没有消抖的按键，就像一扇关不严的门，风一吹就嘎吱响。咱们做产品，得让用户每次按下都有确定性的反馈。