ESP32 S3 UNO - Button Module

Hardware Preparation

Or you can buy the following kits:

Overview of Button Module

In short, the button module is a push button that brings its own resistor. A momentary tactile switch with a colored cap is soldered to a small PCB, next to a pull-down resistor. The switch only closes while your finger holds the cap. When you let go, it springs back and the circuit opens again. A pack holds five modules in five cap colors: red, yellow, green, blue and white. That makes it easy to build a panel where every color means a different action.

Like every mechanical switch, it is not perfectly clean. The metal contacts bounce for a few milliseconds when they touch or let go, so one press can look like several quick presses to a fast board. Examples 2 and 3 below deal with that.

A 3-pin header with 2.54mm spacing sits on one edge. The labels on the board read VCC, OUT and GND, in that order:

• VCC: supply input, 3.3V to 5V DC. On the ESP32 S3 Uno, wire it to the 3.3V pin only.
• OUT: the signal pin. The on-board pull-down holds it LOW while the key is up. Pressing the key links OUT to VCC, so it goes HIGH. Wire it to a digital input, here D7 (GPIO14).
• GND: ground. Wire it to any GND pin of the ESP32 S3 Uno.

ESP32 S3 Uno Pinout

The image below shows the pinout of the ESP32 S3 Uno form board. Look for three spots before you wire: the 3.3V pin, a GND pin and the D7 header, which is GPIO14 inside the chip.

Wiring Diagram

No breadboard and no extra resistor go into this circuit. Three jumper wires join the module header directly to the ESP32 S3 Uno.

This image is created using Fritzing. Click to enlarge image

D7 is a good home for a button on this board. It is a normal input pin, not a boot strapping pin, so holding the key down while the board resets causes no trouble.

How To Program For Button Module

The module already sets the idle level with its pull-down, so the code only needs to read one pin. No special library is needed for the first two examples.

1. Store the GPIO number of D7 in a name. Arduino code uses GPIO numbers on this board, so D7 becomes 14:

1. In setup(), set the pin as a plain input. Skip INPUT_PULLUP: an internal pull-up would work against the module's pull-down.

1. Read the pin when you need it. The logic is not inverted, so HIGH means the key is down:

ESP32 S3 Uno Code - Read the Button Module Level

The first sketch is a simple probe. About three times a second it reads OUT and prints the number it sees, plus a short "key down" or "key up" label. It is the fastest way to prove that the wires and the pin number are right.

Detailed Instructions

1. First time with this board? Set up Arduino IDE with ESP32 S3 Uno - Getting Started.
2. Make the three connections: VCC to 3.3V, OUT to D7, GND to GND. Check VCC twice before you plug in the USB cable.
3. Plug in the board with a USB Type-C cable.
4. In Arduino IDE, pick the ESP32S3 Dev Module board and the right COM port.
5. Paste the sketch above into a new Arduino IDE window.
6. Click Upload and wait until the IDE says it is done.

1. Open the Serial Monitor at 9600 baud.
2. Hold the cap down for about a second, then let go. The lines change while you hold it:

1. Check: with nobody touching the module, the value should stay at 0 all the time. That steady 0 is the pull-down at work. If it jumps around, a wire is loose.

ESP32 S3 Uno Code - Press and Release Events with delay()

A level printout repeats the same line again and again. Most projects only care about the moment something changes: the key went down, or the key came up. This sketch remembers the last confirmed state. When a new reading differs, it waits 50 ms with delay(), reads OUT a second time, and only reports the change if it is still there. Bounces are over by then, so you get one clean message per action.

Detailed Instructions

1. Leave the wiring as it is. It is the same for all three sketches.
2. Paste this sketch into Arduino IDE and click Upload.
3. Open the Serial Monitor at 9600 baud.
4. Tap the cap three times, quickly and lightly:

1. Keep in mind: while delay(50) runs, the ESP32 S3 Uno is stuck and cannot do anything else. For one button in a small test that is fine, but a busy sketch should not stop like this.

ESP32 S3 Uno Code - Button Module with the ezButton Library

The ezButton library by ArduinoGetStarted.com keeps its own timer for each button. Its loop() function returns at once every time, so your sketch can still blink lights, read sensors or talk over WiFi while the debounce happens in the background. Create the button with EXTERNAL_PULLDOWN so the library knows that HIGH means pressed on this module. This sketch also counts the presses.

Detailed Instructions

1. Open the Library Manager with the Libraries icon on the left side of Arduino IDE.
2. Search for "ezButton" and choose the library by ArduinoGetStarted.com.
3. Click Install. If an older copy is already installed, update it to 1.0.6 or newer, because older versions do not know EXTERNAL_PULLDOWN.

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

1. Paste the sketch above into Arduino IDE and click Upload.
2. Open the Serial Monitor at 9600 baud and press the key a few times:

1. Note: button.loop() must be the first line in loop(). Without it, the library never updates, and isPressed() and isReleased() never return true.

The library gives you three useful calls after button.loop():

• button.isPressed(): true once, right after a confirmed press.
• button.isReleased(): true once, right after a confirmed release.
• button.getState(): the debounced level at any time, 1 while held and 0 while free.

Want to use several modules at once? See the ESP32 S3 Uno - Button - Debounce tutorial for multiple ezButton objects. Just remember to add EXTERNAL_PULLDOWN for each module.

Video Tutorial

Watch the video below to see this ESP32 S3 Uno project step by step.

Additional Knowledge

Button module or a bare push button?

The ESP32 S3 Uno - Button tutorial uses a plain 4-leg push button. Both read the same way in the end, but the details differ:

The bare button is cheap and teaches you about floating pins. The module saves wiring time and reads the natural way: pressed is 1.

Project ideas with the button module

1. Doorbell: play a short tone on a buzzer each time the key goes down.
2. Quiz buzzer: give each player a different cap color and print who pressed first.
3. Mode key: step through LED modes, as in the ESP32 S3 Uno - Button - LED tutorial.
4. Start/stop timer: start counting seconds on one press and stop on the next.

Function References

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

FAQ

Why must the button module use 3.3V on the ESP32 S3 Uno?

When the key is pressed, OUT is joined to VCC. The voltage on VCC goes straight to GPIO14. The ESP32 S3 Uno pins accept 3.3V at most, so 5V on VCC could damage the pin. At 3.3V the module works just as well.

Why is the reading 0 when I do not touch the key?

The pull-down resistor on the module holds OUT at LOW. Only a press pulls it up to VCC. So 0 means released and 1 means pressed. This is the opposite of a bare button with INPUT_PULLUP.

Can I use INPUT_PULLUP with the button module?

No. The internal pull-up and the module's pull-down would pull OUT in two directions at once. The released level may sit halfway and read badly. Use pinMode(pin, INPUT), or EXTERNAL_PULLDOWN with ezButton.

My ezButton code shows "pressed" when I release the key. Why?

The button was created without EXTERNAL_PULLDOWN, so the library expects the inverted pull-up logic. Write ezButton button(14, EXTERNAL_PULLDOWN); and make sure ezButton is version 1.0.6 or newer.

Can I move OUT to another pin?

Yes. Any normal digital header works, for example D4 or D5. Change BUTTON_MODULE_PIN to the matching GPIO number. Avoid D0 and D1 (USB serial). Also avoid D6 (GPIO3) and D9 (GPIO46), the boot strapping pins: a held key during reset could stop the board from starting.

What if my project needs more pins than the Uno headers give?

The ESP32 S3 Uno has two extra rows of holes with more GPIOs: GPIO15 and GPIO16 (I/O, PWM, analog), GPIO45 and GPIO35 to GPIO42 (I/O, PWM), and GPIO47/GPIO48 (output only, PWM). Solder pin headers to use them and write the GPIO number in code. For more button modules, GPIO35 to GPIO42, GPIO15 and GPIO16 are good picks. Never use GPIO47 or GPIO48, because they cannot read inputs, and they may run at 1.8V instead of 3.3V on some modules (especially ones with "V" in the name, like R8V or R16V). Also keep away from GPIO0, GPIO3 (D6), GPIO45 and GPIO46 (D9), the boot strapping pins, because a wrong level there can stop the board from booting or uploading code.

Troubleshooting

Learn More

• ESP32 S3 UNO - Button
• ESP32 S3 UNO - Button - Debounce
• ESP32 S3 UNO multiple Button
• ESP32 S3 UNO - Switch
• ESP32 S3 UNO - Limit Switch
• ESP32 S3 UNO - DIP Switch
• ESP32 S3 UNO - Button - LED
• ESP32 S3 UNO - Button - Servo Motor