![\"ESP-IDF](\"https:\/\/i0.wp.com\/randomnerdtutorials.com\/wp-content\/uploads\/2026\/01\/ESP32-ESP-IDF-GPIO-Interrupts-Button-Debouncing.jpg?resize=1200%2C675&quality=100&strip=all&ssl=1\")
<\/figure><\/div>\n\n\nPrerequisites<\/h2>\n\n\n\n
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:<\/p>\n\n\n\n
- \n
- Getting Started Guide:<\/strong> Programming ESP32 with ESP-IDF using VS Code<\/a><\/li>\n<\/ul>\n\n\n\n
You will also need an ESP32 development board<\/a> model of your choice.<\/p>\n\n\n\n
Introducing Interrupts<\/h2>\n\n\n\n
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).<\/p>\n\n\n\n
What are Interrupts?<\/h3>\n\n\n\n
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<\/em>.<\/p>\n\n\n
\n![\"How](\"https:\/\/i0.wp.com\/randomnerdtutorials.com\/wp-content\/uploads\/2019\/03\/interrupt.png?resize=992%2C291&quality=100&strip=all&ssl=1\")
<\/figure><\/div>\n\n\nUsing 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.<\/p>\n\n\n\n
ESP32 GPIO Interrupts with ESP-IDF<\/h2>\n\n\n\n
To set an interrupt GPIO in ESP-IDF, you need to follow these next steps:<\/p>\n\n\n\n
1. Create a queue:<\/strong> in app_main()<\/span>, use xQueueCreate()<\/span> function to make a queue for sending data from ISR to the main task.<\/p>\n\n\n\n
button_queue = xQueueCreate(10, sizeof(uint32_t));<\/code><\/pre>\n\n\n\n2. Configure GPIO:<\/strong> set up the pin as an input with pull-up resistor enabled and interrupt on rising edge using gpio_config()<\/span>.<\/p>\n\n\n\n
#define BUTTON_GPIO GPIO_NUM_4 \n\ngpio_config_t io_conf = {\n .intr_type = GPIO_INTR_POSEDGE, \/\/ Rising edge interrupt trigger\n .mode = GPIO_MODE_INPUT,\n .pin_bit_mask = (1ULL << BUTTON_GPIO),\n .pull_down_en = GPIO_PULLDOWN_DISABLE,\n .pull_up_en = GPIO_PULLUP_ENABLE\n};\ngpio_config(&io_conf);<\/code><\/pre>\n\n\n\n3. Install ISR service and add handler:<\/strong> call gpio_install_isr_service(0)<\/span> to set up the interrupt, then gpio_isr_handler_add()<\/span> to attach your ISR function to the button pin.<\/p>\n\n\n\n
gpio_install_isr_service(0);<\/code><\/pre>\n\n\n\ngpio_isr_handler_add(BUTTON_GPIO, button_isr, NULL);<\/code><\/pre>\n\n\n\n4. Define the ISR function:<\/strong> create a function with IRAM_ATTR<\/span>; in that function, you can check the debounce time, increment counter, and send the new counter value to the queue using xQueueSendFromISR()<\/span>.<\/p>\n\n\n\n
static void IRAM_ATTR button_isr(void *arg) {<\/code><\/pre>\n\n\n\n5. Handle data in main loop:<\/strong> in app_main()<\/span>, use an infinite loop with xQueueReceive()<\/span> to wait for queue items and process them.<\/p>\n\n\n\n
if (xQueueReceive(button_queue, &button_counter, portMAX_DELAY)) {<\/code><\/pre>\n\n\n\ngpio_config_t<\/em> structure<\/h3>\n\n\n\n
Public Member<\/strong><\/td> Value<\/strong><\/td><\/tr> uint64_t pin_bit_mask<\/td> GPIO pin set with bit mask, for example: (1ULL << 2)<\/td><\/tr> gpio_mode_t mode<\/td> GPIO_MODE_DISABLE, GPIO_MODE_INPUT, GPIO_MODE_OUTPUT, GPIO_MODE_OUTPUT_OD, GPIO_MODE_INPUT_OUTPUT_OD, GPIO_MODE_INPUT_OUTPUT<\/td><\/tr> gpio_pullup_t pull_up_en<\/td> GPIO_PULLUP_DISABLE, GPIO_PULLUP_ENABLE<\/td><\/tr> gpio_pulldown_t pull_down_en<\/td> GPIO_PULLDOWN_DISABLE, GPIO_PULLDOWN_ENABLE<\/td><\/tr> gpio_int_type_t intr_type<\/td> GPIO_INTR_DISABLE, GPIO_INTR_POSEDGE, GPIO_INTR_NEGEDGE, GPIO_INTR_ANYEDGE, GPIO_INTR_LOW_LEVEL, GPIO_INTR_HIGH_LEVEL, GPIO_INTR_MAX<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n ESP32 Interrupt GPIOs<\/h3>\n\n\n\n
All GPIOs can be configured as interrupts.<\/p>\n\n\n
\n![\"ESP32](\"https:\/\/i0.wp.com\/randomnerdtutorials.com\/wp-content\/uploads\/2018\/08\/ESP32-DOIT-DEVKIT-V1-Board-Pinout-36-GPIOs-updated.jpg?resize=750%2C538&quality=100&strip=all&ssl=1\")
<\/figure><\/div>\n\n\nLearn more about the ESP32 GPIOs: ESP32 Pinout Reference<\/a>.<\/p>\n\n\n
![\"ESP32-S3](\"https:\/\/i0.wp.com\/randomnerdtutorials.com\/wp-content\/uploads\/2024\/09\/ESP32-S3-pinout.jpg?resize=1200%2C818&quality=100&strip=all&ssl=1\")
<\/figure><\/div>\n\n\n![\"Interrupt](\"https:\/\/i0.wp.com\/randomnerdtutorials.com\/wp-content\/uploads\/2025\/05\/interrupt-modes.png?resize=750%2C438&quality=100&strip=all&ssl=1\")
<\/figure><\/div>\n\n\n![\"ESP-IDF](\"https:\/\/i0.wp.com\/randomnerdtutorials.com\/wp-content\/uploads\/2025\/05\/ESP-IDF-ESP32-Create-Open-New-Project-Wizard-Menu.png?resize=937%2C742&quality=100&strip=all&ssl=1\")
<\/figure><\/div>\n\n\n![\"ESP-IDF](\"https:\/\/i0.wp.com\/randomnerdtutorials.com\/wp-content\/uploads\/2025\/05\/ESP-IDF-ESP32-Create-Open-New-Project-Wizard-Menu-Select-Directory-Board-Template.png?resize=983%2C856&quality=100&strip=all&ssl=1\")
<\/figure><\/div>\n\n\n![\"ESP-IDF](\"https:\/\/i0.wp.com\/randomnerdtutorials.com\/wp-content\/uploads\/2026\/01\/ESP-IDF-ESP32-Create-New-Sample-Project-using-IDF-Template.png?resize=1178%2C744&quality=100&strip=all&ssl=1\")
<\/figure><\/div>\n\n\n![\"ESP-IDF](\"https:\/\/i0.wp.com\/randomnerdtutorials.com\/wp-content\/uploads\/2026\/01\/ESP-IDF-ESP32-Open-New-Project-Sample.png?resize=1024%2C503&quality=100&strip=all&ssl=1\")
<\/figure><\/div>\n\n\n![\"ESP-IDF](\"https:\/\/i0.wp.com\/randomnerdtutorials.com\/wp-content\/uploads\/2025\/05\/ESP-IDF-ESP32-Open-Project-Folder-VS-Code-File-Menu.png?resize=396%2C315&quality=100&strip=all&ssl=1\")
<\/figure><\/div>\n\n\n![\"ESP-IDF](\"https:\/\/i0.wp.com\/randomnerdtutorials.com\/wp-content\/uploads\/2025\/05\/ESP-IDF-ESP32-Open-Project-VS-Code-Select-Folder.png?resize=667%2C366&quality=100&strip=all&ssl=1\")
<\/figure><\/div>\n\n\n![\"ESP-IDF](\"https:\/\/i0.wp.com\/randomnerdtutorials.com\/wp-content\/uploads\/2025\/05\/ESP-IDF-ESP32-Open-Project-in-a-VS-Code-Browse-to-Main-C-File.png?resize=907%2C571&quality=100&strip=all&ssl=1\")
<\/figure><\/div>\n\n\n![\"VS](\"https:\/\/i0.wp.com\/randomnerdtutorials.com\/wp-content\/uploads\/2025\/05\/VS-Code-Check-All-the-Configured-Settings-UART-COM-Port-Target-Board.png?resize=498%2C28&quality=100&strip=all&ssl=1\")
<\/figure><\/div>\n\n\n![\"VS](\"https:\/\/i0.wp.com\/randomnerdtutorials.com\/wp-content\/uploads\/2025\/05\/VS-Code-Select-Flash-UART-Option-to-Program-Flash-ESP32-1024x584.png?resize=1024%2C584&quality=100&strip=all&ssl=1\")
<\/figure><\/div>\n\n\n![\"VS](\"https:\/\/i0.wp.com\/randomnerdtutorials.com\/wp-content\/uploads\/2025\/05\/VS-Code-Programming-ESP32-Board-Select-Correct-COM-Port-Number.png?resize=1024%2C582&quality=100&strip=all&ssl=1\")
<\/figure><\/div>\n\n\n![\"VS](\"https:\/\/i0.wp.com\/randomnerdtutorials.com\/wp-content\/uploads\/2025\/05\/VS-Code-Select-the-ESP32-S3-or-Correct-Target-Device.png?resize=1024%2C579&quality=100&strip=all&ssl=1\")
<\/figure><\/div>\n\n\n![\"VS](\"https:\/\/i0.wp.com\/randomnerdtutorials.com\/wp-content\/uploads\/2025\/05\/VS-Code-Select-the-ESP32-S3-chip-via-built-in-USB-JTAG-Target-Device.png?resize=757%2C579&quality=100&strip=all&ssl=1\")
<\/figure><\/div>\n\n\n![\"VS](\"https:\/\/i0.wp.com\/randomnerdtutorials.com\/wp-content\/uploads\/2025\/06\/VS-Code-Build-Project-Example-Code-ESP32-ESP-IDF.png?resize=581%2C359&quality=100&strip=all&ssl=1\")
<\/figure><\/div>\n\n\n