Wiring guide

How to wire a push button to an ESP32

To wire a push button to an ESP32, connect 1a to GPIO 4 (D4) and 2a to GND. The button goes between the pin and GND and uses the board’s internal pull-up, so there is no resistor and no supply wire, and the pin never sees more than 3.3 V. The sketch below uses no library beyond what the board includes. It waits for the button, debounces it for 20 ms and prints a running count of presses.

  • 3.3 V logic
  • Library: none
  • 2 wires
ESP32 · push buttonlive0.000 s 0.00x
Hold the button
The circuit itself, running on the simulator with the sketch below. Press what can be pressed; click anything else to open it in the editor.
Pin to pin

Push button to ESP32 wiring table

Every wire in the circuit above, with the part’s pin names and the board’s own labels. The wire colors are the ones the circuit uses; on a real bench any colors work.

Push button pinESP32 pinWire colorWhy
One side (1a)GPIO 4 (D4)amberWith INPUT_PULLUP the ESP32 (Xtensa LX6)’s own resistor holds the pin high.
The other side (2a)GNDbluePressing connects the pin to ground, so it reads LOW.
Voltage

Power and logic levels for push button and ESP32

Logic level

The ESP32’s GPIO pins are 3.3 V logic and are not 5 V tolerant. Nothing wired to a pin may go above 3.3 V.

This pair

No resistor and no supply wire: the ESP32’s internal pull-up, about 45 k on this chip, ties the pin to 3.3 V. Never wire a button between a pin and VIN (5 V from USB): the press would put 5 V on a 3.3 V pin.

Pins to leave alone

GPIO 34, 35, 36 (VP) and 39 (VN) are input only: they cannot drive a pin or take an internal pull-up. GPIO 0, 2, 5, 12 and 15 are strapping pins, read at power-on, and GPIO 6 to 11 are the flash chip.

The sketch

The working code for the ESP32

Library: none, the sketch reads the pin with digitalRead() and its internal pull-up. This is the sketch the circuit above runs.

Debounced button on ESP32 GPIO 4 (D4)
const int BUTTON_PIN = 4;   // GPIO 4 (D4) to the button, the button to GND
const unsigned long DEBOUNCE_MS = 20;

int lastReading = HIGH;
int state = HIGH;
unsigned long changedAt = 0;
unsigned int presses = 0;

void setup() {
  Serial.begin(115200);
  pinMode(BUTTON_PIN, INPUT_PULLUP);   // HIGH when up, LOW when pressed
  Serial.println("Press the button");
}

void loop() {
  int reading = digitalRead(BUTTON_PIN);
  if (reading != lastReading) changedAt = millis();
  lastReading = reading;
  if (millis() - changedAt > DEBOUNCE_MS && reading != state) {
    state = reading;
    if (state == LOW) {
      presses++;
      Serial.print("Pressed, count ");
      Serial.println(presses);
    }
  }
}
Output

What you should see

Open the serial monitor at 115200 baud. The sketch prints Press the button once. Each press then adds a line, Pressed, with a count that goes up by one; holding the button down counts once, because the sketch reacts to the press and not to the level.

A button that reads pressed all the time is wired to the wrong pin pair or the pull-up is off; one that counts twice per press is bouncing and needs the debounce time raised.

The serial monitor prints this, recorded from the circuit above with the button pressed once after 300 ms:

Press the button
Pressed, count 1
Pitfalls

Common mistakes wiring a push button to an ESP32

A floating input

With plain INPUT and no resistor, the pin reads whatever noise is nearby and the sketch sees presses nobody made. Use INPUT_PULLUP, or a 10 k resistor to the supply.

Counting the bounce

Without a debounce, one press can count as three or four. The simulated button bounces for a few milliseconds the way real contacts do, so the fix here is the fix on a desk.

Putting the button on an input-only pin

GPIO 34, 35, 36 and 39 on the ESP32 have no output driver at all. pinMode() to OUTPUT on one of them does nothing and the line never moves, which looks exactly like a dead part. GPIO 4 (D4) is a safe choice; so are GPIO 13, 14, 16 to 19, 23, 25 to 27 and 32 to 33.

Build your own push button project

Open this circuit in the editor, change the wiring or the code, and keep your version in a free account.