ESP32 S3 - Button Module

Hardware Preparation

Or you can buy the following kits:

Overview of Button Module

In short, this is a push button with its resistor already on board. A momentary tactile switch with a colored cap is soldered to a small PCB, together with a pull-down resistor that holds the OUT pin at LOW while nobody touches the key. Press it, and the switch links OUT to VCC, so the pin goes HIGH; let go, and it falls back to LOW. Like every mechanical switch, the metal contacts bounce for a few milliseconds when they meet or part, so one press can look like several quick presses to a fast chip like the ESP32 S3. Two of the sketches below deal with that.

Key Specifications

The module runs from 3.3V to 5V DC and its output is active HIGH: HIGH while held, LOW while free. DIYables ships it as a pack of five, one cap each in red, yellow, green, blue and white, which makes it easy to tell several keys apart on one panel.

Button Module Pinout

The edge of the board carries a 3-pin header with 2.54mm spacing. The labels read, from one end to the other:

1. VCC — supply for the switch; on the ESP32 S3 this must be 3.3V (the 3V3 pin)
2. OUT — the signal line; HIGH when pressed, LOW when released (GPIO21 in this guide)
3. GND — ground (0V), shared with the ESP32 S3

Why choose this over a bare 4-leg push button? The bare switch has four legs joined in hidden pairs, which confuses many beginners, and it floats unless you add a resistor or turn on INPUT_PULLUP, which then flips the logic so that pressed reads LOW. The module removes both problems: the pins are named, the pull-down is built in, and pressed simply means HIGH. If you would like to compare, our ESP32 S3 - Button guide covers the bare version.

Wiring Diagram

Only three jumper wires are needed, and no resistor goes on the breadboard because the module brings its own. Connect VCC to the 3V3 pin, OUT to GPIO21, and GND to any GND pin of the ESP32 S3.

This image is created using Fritzing. Click to enlarge image

Safety Notes

Do not take power for this module from the 5V pin. When you press the key, OUT carries the same voltage as VCC, so a 5V supply would push 5V straight into GPIO21, and the ESP32 S3 pins are made for 3.3V only. Keep VCC on 3V3 and the signal stays in the safe range. Also make your wiring changes with the USB cable unplugged, so a loose wire cannot short 3V3 to GND by accident.

How To Program For Button Module

The ESP32 S3 reads the module like any digital input. In setup(), pinMode() sets GPIO21 as a plain INPUT; do not pick INPUT_PULLUP, because the internal pull-up would fight against the module's pull-down. In loop(), digitalRead() returns HIGH while the key is held and LOW otherwise. The three sketches build on this one call: the first prints it, the second checks it twice with a pause in between, and the third hands the job to the ezButton library.

ESP32 S3 Code - Read the Button Module State

This sketch is the simplest possible check of your wiring. Five times per second it reads GPIO21 and prints the level as 1 or 0, with a short note next to it, so you can see the pin follow your finger.

Detailed Instructions

1. New to ESP32 S3? Complete our Getting Started with ESP32 S3 guide first.
2. Set the ESP32 S3 and the button module on the breadboard and run the three wires from the table: VCC to 3V3, OUT to GPIO21, GND to GND.
3. Connect the board to your computer with the Type-C cable.
4. In the Arduino IDE, choose the ESP32 S3 board in Tools > Board and the matching port in Tools > Port.
5. Paste the sketch into a new window and press Upload.
6. Open the Serial Monitor at 9600 baud.
7. Hold the key down for a second, then let it go, and watch the numbers change.
8. Pro Tip: If the monitor shows 1 all the time, check that the OUT wire is really on GPIO21 and not on the 3V3 pin next to the other wires.

ESP32 S3 Code - Press and Release Events with Delay Debounce

Printing the level over and over is fine for a test, but most projects only care about the moment the key goes down or comes up. This sketch keeps the last confirmed level. When a new reading is different, it waits 50 milliseconds for the contacts to settle, reads again, and only then prints one message. Note that delay() stops the whole loop during those 50 milliseconds, so nothing else can run while it waits.

Detailed Instructions

1. Leave the wiring exactly as it is.
2. Open the debounce sketch in place of the first one and click Upload.
3. With the Serial Monitor still at 9600 baud, give the key a few short taps and one long hold.
4. Pro Tip: If one tap still prints two presses, raise SETTLE_TIME to 80; if fast double-taps get missed, lower it to 30.

ESP32 S3 Code - Button Module with the ezButton Library

The delay method works, but a blocked loop is a problem once your ESP32 S3 also has to refresh a display, read a sensor, or keep WiFi alive. The ezButton library by ArduinoGetStarted.com debounces with timestamps instead, so its loop() call returns at once. Because the module pulls OUT down, the button object is created with EXTERNAL_PULLDOWN (available from ezButton 1.0.6); this tells the library that HIGH means pressed. After that, setDebounceTime() sets the filter, getState() gives the steady level, and isPressed() and isReleased() each report an event once.

Detailed Instructions

1. Click the Libraries icon on the left bar of the Arduino IDE.
2. Type ezButton in the search box and find the library by ArduinoGetStarted.com.
3. Click Install. If an older copy is already there, update it to version 1.0.6 or newer.

• Search for ezButton created by ArduinoGetStarted.com and click the Install button.

1. Paste the ezButton sketch, keep the same wiring, and click Upload.
2. Open the Serial Monitor at 9600 baud, then press and release the key a couple of times.
3. Pro Tip: Add more keys by making one ezButton object per module, and call loop() on each of them at the top of loop().

Application and Project Ideas

One labeled key with a clean HIGH signal is enough to start many ESP32 S3 builds.

1. WiFi doorbell: Send a phone notification through a web service each time the visitor presses the module.
2. Mode selector: Step through display pages or LED effects with every press of a single colored key.
3. Start/stop timer: Use a green module to start a stopwatch and a red one to stop it.
4. Quiz buzzer box: Give each player a different cap color and show who pressed first.
5. Mini game pad: Put four modules in a cross shape as direction keys for a small game on an OLED screen.

Challenge Yourself

1. Beginner: Count the presses and print the total each time the key is released.
2. Intermediate: Use the ezButton sketch to toggle an LED on GPIO7 with each press, as in our ESP32 S3 - Button LED tutorial.
3. Advanced: Measure how long the key is held and treat a hold of more than one second as a different command from a quick tap; the ESP32 S3 - Button - Debounce guide is a good place to look at timing ideas.

Video Tutorial

The video for this ESP32 S3 button module lesson will appear here.

Language References

• pinMode()
• digitalRead()
• delay()
• ezButton library

Learn More

• ESP32 S3 - Button
• ESP32 S3 - Button - Debounce
• ESP32 S3 - Button - Long Press Short Press
• ESP32 S3 - Multiple Button
• ESP32 S3 - Switch
• ESP32 S3 - Limit Switch
• ESP32 S3 - DIP Switch
• ESP32 S3 - Button LED