ESP-IDF: ESP32 GPIO Interrupts (Button with Debouncing)

In this guide, you’ll learn how to set ESP32 GPIO interrupts with ESP-IDF (Espressif IoT Development Framework). The ESP32 is a microcontroller that offers several General Purpose Input/Output (GPIO) pins that can be configured as GPIO interrupts. With the GPIOs set as interrupts, you can monitor the pin state for changes (rising edge, falling edge, etc.). This allows you to run a function immediately when a GPIO state changes with non-blocking code.

Prerequisites

Before following this guide, you need to install the ESP-IDF extension on VS Code IDE (Microsoft Visual Studio Code). Follow the next guide to install it, if you haven’t already:

Getting Started Guide: Programming ESP32 with ESP-IDF using VS Code

You will also need an ESP32 development board model of your choice.

Introducing Interrupts

Interrupts are useful for making things happen automatically in microcontroller programs and can help solve timing problems. Interrupts and event handling provide mechanisms to respond to external events, enabling the ESP32 to react quickly to changes without continuously polling (continuously checking the current value of a pin or variable).

What are Interrupts?

Interrupts are signals that pause the normal execution flow of a program to handle a specific event. When an interrupt happens, the processor stops the execution of the main program to execute a task and then gets back to the main program. That task is also referred to as an interrupt handling/service routine.

Using interrupts is especially useful to trigger an action whenever motion is detected or whenever a pushbutton is pressed without the need for constantly checking its state.

ESP32 GPIO Interrupts with ESP-IDF

To set an interrupt GPIO in ESP-IDF, you need to follow these next steps:

1. Create a queue: in app_main(), use xQueueCreate() function to make a queue for sending data from ISR to the main task.

button_queue = xQueueCreate(10, sizeof(uint32_t));

2. Configure GPIO: set up the pin as an input with pull-up resistor enabled and interrupt on rising edge using gpio_config().

#define BUTTON_GPIO GPIO_NUM_4 

gpio_config_t io_conf = {
    .intr_type = GPIO_INTR_POSEDGE, // Rising edge interrupt trigger
    .mode = GPIO_MODE_INPUT,
    .pin_bit_mask = (1ULL << BUTTON_GPIO),
    .pull_down_en = GPIO_PULLDOWN_DISABLE,
    .pull_up_en = GPIO_PULLUP_ENABLE
};
gpio_config(&io_conf);

3. Install ISR service and add handler: call gpio_install_isr_service(0) to set up the interrupt, then gpio_isr_handler_add() to attach your ISR function to the button pin.

gpio_install_isr_service(0);

gpio_isr_handler_add(BUTTON_GPIO, button_isr, NULL);

4. Define the ISR function: create a function with IRAM_ATTR; in that function, you can check the debounce time, increment counter, and send the new counter value to the queue using xQueueSendFromISR().

static void IRAM_ATTR button_isr(void *arg) {

5. Handle data in main loop: in app_main(), use an infinite loop with xQueueReceive() to wait for queue items and process them.

if (xQueueReceive(button_queue, &button_counter, portMAX_DELAY)) {

gpio_config_t structure

Public Member	Value
uint64_t pin_bit_mask	GPIO pin set with bit mask, for example: (1ULL << 2)
gpio_mode_t mode	GPIO_MODE_DISABLE, GPIO_MODE_INPUT, GPIO_MODE_OUTPUT, GPIO_MODE_OUTPUT_OD, GPIO_MODE_INPUT_OUTPUT_OD, GPIO_MODE_INPUT_OUTPUT
gpio_pullup_t pull_up_en	GPIO_PULLUP_DISABLE, GPIO_PULLUP_ENABLE
gpio_pulldown_t pull_down_en	GPIO_PULLDOWN_DISABLE, GPIO_PULLDOWN_ENABLE
gpio_int_type_t intr_type	GPIO_INTR_DISABLE, GPIO_INTR_POSEDGE, GPIO_INTR_NEGEDGE, GPIO_INTR_ANYEDGE, GPIO_INTR_LOW_LEVEL, GPIO_INTR_HIGH_LEVEL, GPIO_INTR_MAX

ESP32 Interrupt GPIOs

All GPIOs can be configured as interrupts.

ESP32 DevKit V1 DOIT 36 GPIOS Pinout Diagram

Learn more about the ESP32 GPIOs: ESP32 Pinout Reference.

Learn more about the ESP32-S3 GPIOs: ESP32-S3 GPIO Reference Guide.

ESP32 GPIO Interrupt Modes

There are six different GPIO interrupt modes:

GPIO_INTR_DISABLE: Disable interrupts on the GPIO
GPIO_INTR_POSEDGE: Trigger on rising edge (LOW » HIGH)
GPIO_INTR_NEGEDGE: Trigger on falling edge (HIGH » LOW)
GPIO_INTR_ANYEDGE: Trigger on both rising and falling edges
GPIO_INTR_LOW_LEVEL: Trigger while input is low
GPIO_INTR_HIGH_LEVEL: Trigger while input is high

Creating an ESP-IDF Template App Project for the ESP32

The ESP-IDF extension provides an easy way to create a project from scratch with all the required files and configurations generated automatically.

To create a new ESP-IDF project on VS Code, follow these steps:

Open the ESP-IDF Espressif extension
Expand the “Advanced” menu
Click the “New Project Wizard” option
Choose the “Use ESP-IDF v5.4.1” to select the framework version

ESP-IDF ESP32 Create Open New Project Wizard Menu

A new window opens, you need to fill in these fields:

Project Name: type the desired project name;
Enter Project Directory: click the folder icon and select the target folder to save all your project files. You can use any directory. Note: do NOT use a Google Drive / One Drive / Dropbox folder, because it will write/create many files during the building process—if it’s on a cloud folder, this process might be extremely slow;
ESP-IDF Target: select the target device chip, I’m using an ESP32 with the esp32s3 chip;
ESP-IDF Board: for the esp32s3 chip, I also need to select the configuration: ESP32-S chip (via builtin USB-JTAG);
Serial Port: while having your ESP32 board connected to your computer, select the correct COM port number that refers to your ESP32;
Choose Template: click the blue button to create a new project using a template.

ESP-IDF ESP32 Create Open New Project Wizard Menu Select Directory Board Template

In the menu, select the “ESP-IDF Templates” sample project and press the “Create project using template sample project” button.

ESP-IDF ESP32 Create New Sample Project using IDF Template

Opening the ESP-IDF Project on VS Code

After a few seconds, a notification will appear on a new window on VS Code. You can click “Open Project” to open the newly created ESP-IDF sample project template.

IMPORTANT: if you didn’t see the notification that allows you to automatically open the ESP-IDF project on VS Code, you can easily do it by following these instructions:

Go to File > Open Folder…

ESP-IDF ESP32 Open Project Folder VS Code File Menu

Browse on your computer for the esp-idf-project folder (your project folder name that you’ve previously defined) and “Select Folder“.

ESP-IDF ESP32 Open Project VS Code Select Folder

That’s it! Your new ESP-IDF project template has been successfully created and opened.

ESP-IDF generates many files, folders, and subfolders for your project. For this guide, I recommend keeping all the default files unchanged; we will only modify the main.c file.

The example codes will be written in the main.c file. To open it, follow these instructions:

Open the project explorer by clicking the first icon on the left sidebar.
Select your project folder name, in my case it’s “ESP-IDF-PROJECT“.
Expand the “main” folder.
Click the “main.c” file.
The default main.c template file loads in the code window.

ESP-IDF ESP32 Open Project in a VS Code Browse to Main C File

Code: ESP32 GPIO Button Interrupt with Debouncing using ESP-IDF

Copy the following code to the main.c file. This code waits for a rising edge interrupt from a button connected to ESP32 GPIO 4 using a debounce timer.

/*  
  Rui Santos & Sara Santos - Random Nerd Tutorials
  https://RandomNerdTutorials.com/esp-idf-esp32-gpio-interrupts/
*/
#include <stdio.h>
#include <freertos/FreeRTOS.h>
#include <freertos/task.h>
#include <freertos/queue.h>
#include <driver/gpio.h>
#include <esp_timer.h>
#include "sdkconfig.h"

#define BUTTON_GPIO GPIO_NUM_4       // Pushbutton GPIO
#define DEBOUNCE_DELAY_US 200000ULL  // Debounce delay in microseconds (200 ms)

static volatile uint64_t last_isr_time = 0;
static volatile uint32_t counter = 0;
static QueueHandle_t button_queue;

// Interrupt Service Routine (ISR) for button press, placed in IRAM for low latency
static void IRAM_ATTR button_isr(void *arg) {
    uint64_t now = esp_timer_get_time(); // Get current time in microseconds
    // Check if debounce period has passed, then process the button press
    if (now - last_isr_time > DEBOUNCE_DELAY_US) {
        counter++;
        uint32_t cnt = counter;
        BaseType_t higher_priority_task_woken = pdFALSE;
        xQueueSendFromISR(button_queue, &cnt, &higher_priority_task_woken); // Send counter to queue from ISR
        last_isr_time = now;
        if (higher_priority_task_woken) {
            portYIELD_FROM_ISR();
        }
    }
}

void app_main(void) {
    printf("Press the button on GPIO %d.\n", BUTTON_GPIO);

    // Create a queue to hold up to 10 uint32_t items
    button_queue = xQueueCreate(10, sizeof(uint32_t));

    // Configure Button GPIO
    gpio_config_t io_conf = {
        .intr_type = GPIO_INTR_POSEDGE, // Rising edge interrupt trigger
        .mode = GPIO_MODE_INPUT,
        .pin_bit_mask = (1ULL << BUTTON_GPIO),
        .pull_down_en = GPIO_PULLDOWN_DISABLE,
        .pull_up_en = GPIO_PULLUP_ENABLE
    };
    gpio_config(&io_conf);

    // Install GPIO ISR service
    gpio_install_isr_service(0);

    // Add ISR handler for button
    gpio_isr_handler_add(BUTTON_GPIO, button_isr, NULL);

    // Variable to receive counter from queue
    uint32_t button_counter;

    // Keep program running
    while (1) {
        // Wait indefinitely for an item in the queue
        if (xQueueReceive(button_queue, &button_counter, portMAX_DELAY)) {
            printf("Button pressed %lu times.\n", button_counter);
        }
    }
}

View raw code

How the Code Works

In this section, we’ll take a look at the code to see how it works.

Libraries

We start by including the required libraries:

stdio.h – the standard C library will be used for the printf function that prints the debugging information in the serial monitor;
FreeRTOS.h – provides the core FreeRTOS types and functions;
task.h – allows to use of the non-blocking delay function vTaskDelay;
queue.h – queue for ISR function for task communication;
gpio.h – includes the functions required to configure and control GPIOs;
esp_timer.h – timer functions for button debounce;
sdkconfig.h – includes the project’s configuration file.

#include <stdio.h>
#include <freertos/FreeRTOS.h>
#include <freertos/task.h>
#include <freertos/queue.h>
#include <driver/gpio.h>
#include <esp_timer.h>
#include "sdkconfig.h"

Definitions

These lines define the BUTTON_GPIO and DEBOUNCE_DELAY_US.

#define BUTTON_GPIO GPIO_NUM_4       // Pushbutton GPIO
#define DEBOUNCE_DELAY_US 200000ULL  // Debounce delay in microseconds (200 ms)

It also defines auxiliary variables to store the last time the button was pressed, counter and queues.

static volatile uint64_t last_isr_time = 0;
static volatile uint32_t counter = 0;
static QueueHandle_t button_queue;

app_main(void)

When creating an ESP-IDF project, this function will always be called to run. This function is where you need to write your code for any ESP-IDF applications; it is the equivalent of the setup() in Arduino programming. When the ESP32 boots, the ESP-IDF framework calls app_main.

void app_main(void)
{
    // your code goes here
}

In the app_main(void) function, you start by printing a messag in the Serial monitor to let the user know the board is ready to receive button presses.

printf("Press the button on GPIO %d.\n", BUTTON_GPIO);

Then, create a queue that can hold up to 10 uint32_t items. This queue will send data from ISR to the main task.

button_queue = xQueueCreate(10, sizeof(uint32_t));

Create the GPIO config variable with the pushbutton GPIO, set to the interrupt mode rising edge, set it as an INPUT, and disable pull-down resistor. If you notice, the internal pull-up resistor is enabled, so you don’t need an external resistor connected to the pushbutton:

// Configure Button GPIO
gpio_config_t io_conf = {
    .intr_type = GPIO_INTR_POSEDGE, // Rising edge interrupt trigger
    .mode = GPIO_MODE_INPUT,
    .pin_bit_mask = (1ULL << BUTTON_GPIO),
    .pull_down_en = GPIO_PULLDOWN_DISABLE,
    .pull_up_en = GPIO_PULLUP_ENABLE
};
gpio_config(&io_conf);

Call gpio_install_isr_service(0) to set up the GPIO pin to trigger with interrupts. The 0 argument means that it’s using the default configs.

gpio_install_isr_service(0);

Finally, call gpio_isr_handler_add() to attach your ISR function to the button pin. The button_isr() function runs immediatly when the button detects a rising edge.

gpio_isr_handler_add(BUTTON_GPIO, button_isr, NULL);

IRAM_ATTR

The button_isr() function has the IRAM_ATTR attribute, so it forces the function to be executed immediately (in RAM) when an interrupt is triggered.

static void IRAM_ATTR button_isr(void *arg) {

Inside that function, it starts by checking the current time in microseconds.

uint64_t now = esp_timer_get_time();

Then, it has a software debouncing to check if the debounce period has passed. If the button press is valid, it increments the global counter variable and sends the counter value via queue to be processed by a task in the while (1).

if (now - last_isr_time > DEBOUNCE_DELAY_US) {
    counter++;
    uint32_t cnt = counter;
    BaseType_t higher_priority_task_woken = pdFALSE;
    xQueueSendFromISR(button_queue, &cnt, &higher_priority_task_woken);
    last_isr_time = now;
    if (higher_priority_task_woken) {
        portYIELD_FROM_ISR();
    }
}

while (1)

The while (1) runs an infinite loop with xQueueReceive() to wait for queue items and process them. It will print in the Serial monitor how many times the button was pressed.

while (1) {
    if (xQueueReceive(button_queue, &button_counter, portMAX_DELAY)) {
        printf("Button pressed %lu times.\n", button_counter);
    }
}

Build and Flash Code to the ESP32 Board

To build and flash ESP-IDF code to the ESP32, you always need to follow this procedure. You need to select the flash method (UART), the COM port number, the target device (ESP32), build the code, and finally, flash it to the board. All these commands are available in the bottom menu bar of VS Code.

Make sure all your options are correct (they may already be properly configured if you used the project wizard).

However, if your setup is not correct, follow the next instructions to ensure everything is set up correctly. First, click the “Star” icon and select the flash method as UART.

VS Code ESP-IDF Select Flash UART Option to Program Flash ESP32

While the ESP32 board is connected to your computer, click the COM Port (plug icon) and select the correct port number that refers to your ESP32.

VS Code ESP-IDF Programming ESP32 Board Select Correct COM Port Number

You also need to select the target device. Click on the chip icon at the bottom bar. In my case, I have an ESP32 with the esp32s3 chip.

VS Code Select the ESP32 S3 or Correct Target Device ESP-IDF

For this board, I also need to select the configuration: ESP32-S chip (via builtin USB-JTAG).

VS Code ESP-IDF Select the ESP32 S3 chip via built in USB JTAG Target Device

Finally, your command bar at the bottom of VS Code should have similar options selected.

Now, you can build the project by clicking the wrench icon (Build Project) as shown in the image below.

VS Code Build Project Example Code ESP32 ESP-IDF

The first time you build a project, it usually takes a bit more time. Once completed, it should print a similar message in the Terminal menu and show a “Build Successfully” message.

VS Code Build Example Project ESP32 ESP-IDF Success Message

This is the final step. You can now flash the ESP-IDF project to the ESP32 by clicking the “Flash Device” button (thunder icon).

VS Code Flash Hello World Code Project to ESP32 ESP-IDF

Depending on your board, you might need to hold down the on-board BOOT button on your ESP32 to put it into flashing mode. Once the process is completed, it will pop-up a info message saying “Flash Done“.

VS Code Flash Hello World Project to ESP32 ESP-IDF Done Success Message

Schematic Diagram

Here’s a list of the parts you need to build the circuit:

Connect a pushbutton to GPIO 4 as shown in the schematic diagram below for a board with ESP32-S3 chip.

ESP-IDF ESP32 Read Digital Input Circuit Wiring Diagram Pushbutton

Demonstration

If you followed all the steps, the example should be running successfully on your board. Open your Terminal window — click the “Monitor Device” tool that is illustrated with a screen icon.