ESP32 Buttons: Wiring, Interrupts, and Debouncing Code

The Verdict: How to Wire and Read ESP32 Buttons

If you are wiring ESP32 buttons for a production build or a reliable bench prototype, stop polling the pin in your loop() and stop wiring external 10kΩ pull-up resistors. The ESP32-WROOM-32 has robust internal pull-ups and hardware interrupt capabilities that make external components redundant for 95% of use cases.

The default pick: Wire one leg of your tactile switch to GPIO 4 and the other to GND. Enable the internal pull-up in software, and use a pin-change interrupt with a 50ms software debounce timer. This frees your main loop for WiFi/Bluetooth tasks and eliminates the need for extra breadboard wiring.

Decision Tree: Polling vs. Interrupts & Pull-up Selection

Parts List and Pin Mapping for the ESP32-WROOM-32

This guide targets the ubiquitous ESP32-WROOM-32 DevKit V1 (the 30-pin or 38-pin variant sold by HiLetgo, KeeYees, and Freenove). Do not use the ESP32-C3 or ESP32-S3 without checking their specific GPIO matrices, as pin capabilities differ.

Complete Compilable Code: Interrupt-Driven Button Reading

The following code is fully compilable in the Arduino IDE (ensure you have the ESP32 Core by Espressif installed via Boards Manager). It uses a hardware interrupt to catch the press instantly, but defers the debounce logic to the main loop to prevent the ESP32's Real-Time Operating System (RTOS) from triggering a watchdog panic.

/*
 * ESP32 Interrupt-Driven Button with Software Debounce
 * Target: ESP32-WROOM-32 DevKit V1
 * Framework: Arduino (ESP32 Core)
 */

#define BUTTON_PIN 4
#define DEBOUNCE_DELAY_MS 50

// Volatile variables shared between ISR and main loop
volatile bool buttonPressPending = false;
volatile unsigned long isrTriggerTime = 0;

// State tracking for the main loop
bool lastButtonState = HIGH;
unsigned long lastDebounceTime = 0;

// The Interrupt Service Routine (ISR)
// IRAM_ATTR forces this function into fast instruction RAM
void IRAM_ATTR buttonISR() {
  buttonPressPending = true;
  isrTriggerTime = millis();
}

void setup() {
  Serial.begin(115200);
  while (!Serial) { delay(10); } // Wait for serial monitor
  
  Serial.println("ESP32 Button Interrupt Demo Starting...");
  
  // Configure pin with internal pull-up (Active LOW)
  pinMode(BUTTON_PIN, INPUT_PULLUP);
  
  // Attach interrupt to trigger on FALLING edge (High to Low)
  attachInterrupt(digitalPinToInterrupt(BUTTON_PIN), buttonISR, FALLING);
  
  Serial.println("Ready. Press the button connected to GPIO 4.");
}

void loop() {
  // Check if the ISR flagged a press
  if (buttonPressPending) {
    // Software debounce: ensure enough time has passed since the last valid trigger
    if ((millis() - lastDebounceTime) > DEBOUNCE_DELAY_MS) {
      
      // Read the current physical state to confirm it's actually LOW
      int currentState = digitalRead(BUTTON_PIN);
      
      if (currentState == LOW && lastButtonState == HIGH) {
        // Valid press confirmed!
        handleButtonPress();
        lastDebounceTime = millis(); // Reset debounce timer
      }
      
      lastButtonState = currentState;
    }
    
    // Clear the ISR flag regardless of debounce outcome
    buttonPressPending = false; 
  }
  
  // Your main IoT/WiFi code goes here. 
  // The loop is completely non-blocking.
}

void handleButtonPress() {
  Serial.printf("[%lu ms] Button Press Registered!\n", millis());
  // Add your relay toggle, MQTT publish, or LED logic here.
}

Debugging: When Your ESP32 Button Circuit Fails

When working with ESP32 buttons, hardware bounce and RTOS interrupt handling frequently collide, resulting in board crashes or missed inputs. If your circuit is misbehaving, run through this diagnostic path.

The First Three Things to Check

1. Verify the GPIO capabilities: Open the official Espressif GPIO documentation. Confirm your chosen pin supports both INPUT mode and internal pull-ups (avoiding 34-39 and strapping pins).
2. Check for the IRAM_ATTR macro: If your ISR function lacks this prefix, the ESP32 will crash the moment the interrupt fires, because the flash-cached function cannot be read fast enough during an interrupt context.
3. Measure switch continuity: Use a multimeter in continuity mode. Cheap 6x6mm tactile switches often have oxidized contacts out of the bag. Press the button; you should read < 1 ohm. If it reads > 10 ohms, replace the switch.

Exact Error Strings and Ranked Causes

If your ESP32 reboots randomly when you press the button, check your serial monitor for this exact panic string:

Guru Meditation Error: Core 1 panic'ed (Interrupt wdt timeout on CPU1)
Core 1 register dump:
PC: 0x4008xxxx PS: 0x00060x33 A0: 0x800xxxxx

Ranked Causes for the WDT Timeout:

For a deeper understanding of the physics behind switch bounce, review the oscilloscope traces in this All About Circuits primer on switch debouncing. Mechanical contacts physically chatter for 1 to 20 milliseconds before settling, which the ESP32's 240MHz CPU interprets as dozens of distinct presses.

Extending and Simplifying the Build

Once you have a single button working reliably, you will inevitably need to scale the design. Here is how to adapt the architecture based on your final product requirements.

How to Simplify (If You Hate ISR Logic)

If you are building a quick weekend project and don't want to manage volatile variables and RTOS timing, strip out the interrupt code entirely and use the ezButton library by ArduinoGetStarted.

The trade-off: You must call button.loop() at the very top of your main loop() function. If your main loop contains blocking code (like a 500ms delay() or a synchronous HTTP request), the library will miss the button press. For 90% of basic sensor-logging projects, this simplification is worth the trade-off.

How to Extend (When You Run Out of GPIOs)

The ESP32-WROOM-32 only has about 15 safely usable GPIOs once you account for flash SPI, strapping pins, and input-only pins. If your project requires a 12-button macro pad or a complex control panel, do not wire 12 individual buttons to the DevKit.

The concrete pick for extension: Use a 74HC165 Parallel-In/Serial-Out Shift Register.

By wiring eight buttons to a single 74HC165 chip, you can read all eight states using only three ESP32 GPIO pins (Data, Clock, Latch). You can daisy-chain multiple 74HC165 chips together to read 16, 24, or 32 buttons while still only consuming three ESP32 pins. This is the exact architecture used in commercial MIDI controllers and industrial HMI panels, and it completely eliminates the need to hunt for unused, non-strapping GPIOs on your ESP32.