ESP32 - Button Module
A doorbell for your workshop, a "fire" key for a small game, a start/stop key for a data logger: many ESP32 projects need just one thing from the user, a press. This tutorial shows how to get that press into your ESP32 with the 3-pin button module, step by step, from reading the raw pin level, to catching clean press and release events with a short delay, and finally to the ezButton library, which does the debouncing for you without pausing your code.
This tutorial shows how to program the ESP32 using the Arduino language (C/C++) via the Arduino IDE. If you’d like to learn how to program the ESP32 with MicroPython, visit this ESP32 MicroPython - Button Module tutorial.
Hardware Used In This Tutorial
Or you can buy the following kits:
| 1 | × | DIYables ESP32 Starter Kit (ESP32 included) | |
| 1 | × | DIYables ESP32 S3 Starter Kit (ESP32 S3 included) | |
| 1 | × | DIYables Sensor Kit (18 sensors/displays) |
Introduction to the Button Module
In short, the button module is a push button with its resistor already on board. A small tactile switch with a colored cap sits on a tiny PCB, next to a pull-down resistor. While nobody touches the cap, that resistor holds the output at LOW. Press the cap and the output jumps to the supply voltage, so the ESP32 reads HIGH. Let go and it falls back to LOW. One pack holds five modules, one in each color: red, yellow, green, blue and white, so you can give every key in your project its own color.
| Button Module | |
|---|---|
| The switch type | momentary tactile push button |
| The operating voltage | 3.3V to 5V DC |
| The output when released | LOW |
| The output when pressed | HIGH (equal to VCC) |
| The pull resistor | pull-down, built into the module |
| The connector | 3-pin male header, 2.54mm pitch |
Button Module Pinout
The three pins are printed on the board in the order VCC, OUT, GND:
- VCC pin: connect this pin to 3V3 of the ESP32. Do not use the 5V or VIN pin (see the warning below).
- OUT pin: connect this pin to a GPIO of the ESP32. It gives LOW when the cap is up and HIGH when the cap is down.
- GND pin: connect this pin to GND (0V).
※ NOTE THAT:
When the cap is pressed, the OUT pin gives out the same voltage as the VCC pin. The ESP32 GPIO pins work at 3.3V and are not 5V tolerant. If VCC is wired to 5V or VIN, every press pushes 5V into GPIO21 and can damage the ESP32. Always power the module from the 3V3 pin.
There is one more thing every mechanical button does: its metal contacts bounce for a few milliseconds when they close or open. During that short time the pin flips between LOW and HIGH, so a single press can look like several presses to a fast chip like the ESP32. The second and third examples below fix this.
Why pick the module over a bare 4-pin push button? The bare button needs a pull-up or pull-down resistor (or INPUT_PULLUP in code), and its four legs are easy to wire the wrong way. The module has labeled pins and its own pull-down, and its logic is not inverted: pressed simply means HIGH. We highly recommend you using the button module if you are new to buttons. If you want to learn the bare button too, see the ESP32 - Button tutorial.
Wiring Diagram
The module needs three wires, and the same wiring is used for all three codes in this tutorial:
| Button Module | ESP32 |
|---|---|
| VCC | → 3V3 (not 5V, not VIN) |
| OUT | → GPIO21 |
| GND | → GND |
This image is created using Fritzing. Click to enlarge image
If you're unfamiliar with how to supply power to the ESP32 and other components, you can find guidance in the following tutorial: The best way to Power ESP32 and sensors/displays.
ESP32 Code - Read the Raw State
This first code is the simplest one. Five times per second, the ESP32 reads GPIO21 and prints the level, plus a short word that says if the key is down or up.
Quick Instructions
- If this is the first time you use ESP32, see how to setup environment for ESP32 on Arduino IDE.
- Wire the button module to the ESP32 as in one of the diagrams above. Check twice that VCC goes to 3V3.
- Connect the ESP32 to your PC with the USB Type-C cable.
- Open Arduino IDE and choose your ESP32 board (e.g. ESP32 Dev Module) and its COM port.
- Paste the code above into a new sketch.
- Click to the Upload button to build the code and send it to the ESP32.
- Open the Serial Monitor and set the baud rate to 9600.
- Do nothing for two or three seconds, press the button and hold it for about a second, then release it.
The value stays 0 while the cap is up. There is no random 0/1 noise, because the module's pull-down holds the pin firmly at LOW. If you see 1 all the time, check the OUT and VCC wires. They may be swapped.
ESP32 Code - Detect Press and Release Events (Debounce with delay)
Printing the level many times per second is not what a doorbell or a game key needs. Those projects want one message per press. This code remembers the last confirmed state. When a new reading is different, it waits 50 milliseconds for the contacts to stop bouncing, reads the pin again, and only then reports the change.
Quick Instructions
- Keep the same wiring.
- Paste this code into Arduino IDE and upload it to the ESP32.
- Press the button three times, at any speed you like.
- The Serial Monitor shows exactly one pair of lines for each press:
This works well, but delay() blocks the loop: during those 50 milliseconds the ESP32 can do nothing else. For a project that also blinks LEDs, reads sensors or serves a web page, the next example is a better choice.
Video Tutorial
Making video is a time-consuming work. If the video tutorial is necessary for your learning, please let us know by subscribing to our YouTube channel , If the demand for video is high, we will make the video tutorial.