For anyone diving into the world of microcontrollers, the "Hello, World!" equivalent is blinking an LED. The next logical step is adding user interaction. This tutorial will guide you through the fundamental project of controlling an LED with a pushbutton using an ESP32.

We won't just turn the LED on while the button is held down. We will implement a more practical toggle switch: press the button once to turn the LED on, and press it again to turn it off. To ensure our project is reliable, we will also implement a crucial software technique called debouncing to prevent false triggers from the noisy electrical signals of a physical button.

By the end of this guide, you will have a solid understanding of:

  • Reading digital inputs (a button press).
  • Controlling digital outputs (an LED).
  • Using internal pull-up resistors to simplify wiring.
  • Implementing software debouncing to ensure accurate input reading.
  • Managing state to create a toggle function.

Required Components

You will need a few basic electronic components to get started:

  • An ESP32 Development Board (e.g., ESP32-WROOM-32 DevKitC)
  • A standard 5mm LED
  • A 220Ω to 330Ω resistor
  • A standard tactile pushbutton switch
  • A solderless breadboard
  • Jumper wires

Step 1: The Wiring Diagram

Before we touch the code, let's wire up our circuit. The connections are straightforward. The resistor is essential to limit the current flowing to the LED, protecting it from damage. We will use the ESP32's internal pull-up resistor for the button, which simplifies our circuit by eliminating the need for an external one.

  1. LED Connection:
    • Connect the anode (the longer leg of the LED) to GPIO 23 on the ESP32.
    • Connect the cathode (the shorter leg of the LED) to one end of the 220Ω resistor.
    • Connect the other end of the resistor to a GND (Ground) pin on the ESP32.
  2. Button Connection:
    • Connect one leg of the pushbutton to GPIO 22 on the ESP32.
    • Connect the leg directly opposite the first one to a GND pin on the ESP32.

Here is a simple schematic representation of the wiring:

          ESP32
           |
(GPIO 23) ---[ LED Anode ]---[ LED Cathode ]---[ 220Ω Resistor ]---(GND)
           |
(GPIO 22) ---[ Button Leg 1 ]---[ Button Leg 2 ]-------------------(GND)

Step 2: Setting Up the Arduino IDE

We will be using the Arduino IDE to program our ESP32. If you haven't already, you need to add ESP32 board support to it.

  1. Install Arduino IDE: Download and install the latest version from the official Arduino website.

  2. Add ESP32 Board Manager: Go to File > Preferences. In the "Additional Boards Manager URLs" field, paste the following URL:

    https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json
  3. Install ESP32 Boards: Go to Tools > Board > Boards Manager.... Search for "esp32" and install the package by Espressif Systems.
  4. Select Your Board: Once installed, go to Tools > Board and select your specific ESP32 board model (e.g., "ESP32 Dev Module"). Also, ensure you select the correct COM Port under the Tools menu.

Step 3: The Complete Code

This code includes the toggle functionality and software debouncing. Copy and paste it into your Arduino IDE.

C++

 

// Define the GPIO pins for the LED and the button
const int ledPin = 23;
const int buttonPin = 22;

// Variables to manage the toggle and debounce logic
int ledState = LOW;             // The current state of the LED (initially off)
int lastButtonState = HIGH;   // The previous reading from the button input
int currentButtonState;         // The current reading from the button input

// Debounce timer variables
unsigned long lastDebounceTime = 0; // The last time the button's state changed
unsigned long debounceDelay = 50;   // The debounce time in milliseconds; 50ms is a good starting point

void setup() {
  // Start serial communication for debugging purposes
  Serial.begin(115200); 
  
  // Configure the hardware pins
  pinMode(ledPin, OUTPUT);
  pinMode(buttonPin, INPUT_PULLUP); // Use the internal pull-up resistor

  // Set the initial state of the LED
  digitalWrite(ledPin, ledState);
  Serial.println("ESP32 Toggle Switch Ready.");
  Serial.println("Press the button to change the LED status.");
}

void loop() {
  // Read the current state of the button
  int reading = digitalRead(buttonPin);

  // Check if the button state has changed from its last known stable state.
  // This is the first step in detecting a potential press.
  if (reading != lastButtonState) {
    // If it has changed, reset the debouncing timer.
    lastDebounceTime = millis();
  }

  // After waiting for the debounce delay, we check if the signal is stable.
  // The millis() function returns the number of milliseconds since the ESP32 started.
  if ((millis() - lastDebounceTime) > debounceDelay) {
    
    // If the signal has been stable for long enough, we can trust the reading.
    // We only proceed if this stable reading is different from the last state we acted on.
    if (reading != currentButtonState) {
      currentButtonState = reading;

      // We only want to toggle the LED on the button PRESS, not the release.
      // A press corresponds to the state changing from HIGH (pull-up) to LOW.
      if (currentButtonState == LOW) {
        Serial.println("Button Click Registered!");
        
        // This is the toggle magic: invert the LED's state.
        // If ledState is LOW, it becomes HIGH. If it's HIGH, it becomes LOW.
        ledState = !ledState;
      }
    }
  }

  // After all logic, update the physical LED to match its stored state.
  digitalWrite(ledPin, ledState);

  // Save the current reading. This becomes the "lastButtonState" for the next loop iteration.
  lastButtonState = reading;
}

Step 4: Understanding the Code

Global Variables

  • ledPin & buttonPin: Constants holding the GPIO pin numbers we are using.
  • ledState: Stores the current intended state of the LED (HIGH or LOW). This is our "memory."
  • lastButtonState, currentButtonState: Used to detect a change in the button's state.
  • lastDebounceTime & debounceDelay: These are the core of our debouncing timer.

void setup()

  • pinMode(ledPin, OUTPUT): Configures GPIO 23 to be an output pin, allowing us to send voltage to it.
  • pinMode(buttonPin, INPUT_PULLUP): This is a key command. It configures GPIO 22 as an input but also connects a built-in resistor between the pin and the ESP32's internal 3.3V supply. This means when the button is not pressed, the pin reads HIGH. When the button is pressed, it connects the pin to Ground, and it reads LOW. This is efficient and saves an external component.
  • digitalWrite(ledPin, ledState): We set the LED to its initial state, which is LOW (off).

void loop() - The Core Logic

The loop() function runs continuously and is where the real work happens.

  1. The Problem of "Bounce": When you press a mechanical button, the metal contacts inside don't connect cleanly. They "bounce" against each other for a few milliseconds, creating a rapid series of on-off signals. The ESP32 is fast enough to see these bounces as dozens of separate presses.
  2. The Debounce Solution: Our code uses the millis() timer to ignore these bounces.
    • It first detects any change in the button's state (reading != lastButtonState).
    • When a change is seen, it records the time (lastDebounceTime = millis()).
    • It then waits for debounceDelay (50 milliseconds) to pass without any further changes.
    • Only when the signal has been stable for this duration does it consider the reading valid.
  3. Detecting the "Click": We only want to act when the button is pressed down (a "falling edge" from HIGH to LOW). The line if (currentButtonState == LOW) ensures that our action only happens on a press, not on the release.
  4. The Toggle Magic: The line ledState = !ledState; is beautifully simple. The logical NOT operator (!) inverts the boolean value. If ledState was LOW (which evaluates to 0 or false), !ledState becomes HIGH (true). If it was HIGH, it becomes LOW. This single line is what flips the state of our LED in memory.
  5. Updating the Hardware: Finally, digitalWrite(ledPin, ledState) takes the state we have stored in our ledState variable and applies it to the physical LED.

Uploading and Final Result

With the circuit wired and the code in your Arduino IDE, click the "Upload" button (the right-pointing arrow). Once the code has been successfully uploaded, open the Serial Monitor (Tools > Serial Monitor) and set the baud rate to 115200.

You should see the "ESP32 Toggle Switch Ready" message. Now, press your button. The LED will turn on. Press it again, and the LED will turn off. Each valid click will also print a message to your Serial Monitor.

Congratulations! You have successfully built a debounced toggle switch, a foundational building block for countless more complex and interactive electronics projects.