MicroPython: Interrupts with ESP32 and ESP8266

Learn how to configure and handle interrupts using MicroPython firmware with ESP32 and ESP8266 boards. You’ll also build a project example with a PIR Motion Sensor.

Prerequisites

To follow this tutorial you need MicroPython firmware flashed in your ESP32 or ESP8266. You also need an IDE to write and upload the code to your board. We suggest using Thonny IDE or uPyCraft IDE:

• Thonny IDE:
  • Installing and getting started with Thonny IDE
  • Flashing MicroPython Firmware with esptool.py
• uPyCraft IDE:
  • Install uPyCraft IDE (Windows, Mac OS X, Linux)
  • Flash/Upload MicroPython Firmware to ESP32 and ESP8266

Introducing Interrupts

Interrupts are useful for making things happen automatically in microcontroller programs and can help solve timing problems. With interrupts you don’t need to constantly check the current pin value. When a change is detected, an event is triggered (a function is called).

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 as shown in the figure below.

This 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 interrupt pins: you can use all GPIOs as interrupts, except GPIO 6 to GPIO 11.

ESP8266 interrupt pins: you can use all GPIOs, except GPIO 16.

Set Up an Interrupt in MicroPython

To setup an interrupt in MicroPython, you need to follow the next steps:

1. Define an interrupt handling function. The interrupt handling function should be as simple as possible, so the processor gets back to the execution of the main program quickly. The best approach is to signal the main code that the interrupt has happened by using a global variable, for example. The interrupt handling function should accept a parameter of type Pin. This parameter is returned to the callback function and it refers to the GPIO that caused the interrupt.

def handle_interrupt(pin):

2. Setup the GPIO that will act as an interrupt pin as an input. For example:

pir = Pin(14, Pin.IN)

3. Attach an interrupt to that pin by calling the irq() method:

pir.irq(trigger=Pin.IRQ_RISING, handler=handle_interrupt)

The irq() method accepts the following arguments:

• trigger: this defines the trigger mode. There are 3 different conditions:
  • Pin.IRQ_FALLING: to trigger the interrupt whenever the pin goes from HIGH to LOW;
  • Pin.IRQ_RISING: to trigger the interrupt whenever the pin goes from LOW to HIGH.
  • 3: to trigger the interrupt in both edges (this means, when any change is detected)
• handler: this is a function that will be called when an interrupt is detected, in this case the handle_interrupt() function.

Project Example with PIR Motion Sensor

To demonstrate how to handle interrupts, we’ll build a simple project with a PIR motion sensor. Whenever motion is detected we’ll light up an LED for 20 seconds.

Parts required

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

• ESP32 (read Best ESP32 development boards) or ESP8266 (read Best ESP8266 development boards)
• 5mm LED
• 330 Ohm resistor
• Mini PIR motion sensor (AM312) or PIR motion sensor (HC-SR501)
• Breadboard
• Jumper wires

Schematic – ESP32

Follow the next schematic diagram if you’re using an ESP32 board:

Schematic – ESP8266

Follow the next schematic diagram if you’re using an ESP8266 board:

Important: the Mini AM312 PIR Motion Sensor we’re using in this project operates at 3.3V. However, if you’re using another PIR motion sensor like the HC-SR501, it operates at 5V. You can either modify it to operate at 3.3V or simply power it using the Vin pin.

In the figure below, we provide the pinout for the Mini AM312 PIR motion sensor. If you’re using another motion sensor, please check its pinout before assembling the circuit.

Code

Here’s the script that detects motion and lights up an LED whenever motion is detected. This code is compatible with both the ESP32 and ESP8266.

from machine import Pin
from time import sleep

motion = False

def handle_interrupt(pin):
  global motion
  motion = True
  global interrupt_pin
  interrupt_pin = pin 

led = Pin(12, Pin.OUT)
pir = Pin(14, Pin.IN)

pir.irq(trigger=Pin.IRQ_RISING, handler=handle_interrupt)

while True:
  if motion:
    print('Motion detected! Interrupt caused by:', interrupt_pin)
    led.value(1)
    sleep(20)
    led.value(0)
    print('Motion stopped!')
    motion = False

How the code Works

To use interrupts, import the Pin class from the machine module. We also import the sleep method from the time module to add a delay in our script.

from machine import Pin
from time import sleep

Create a variable called motion that can be either True of False. This variable will indicate whether motion was detected or not (this is the global variable that will be changed on the interrupt handling function).

motion = False

Then, create a function called handle_interrupt.

def handle_interrupt(pin):
  global motion
  motion = True
  global interrupt_pin
  interrupt_pin = pin 

This function will be called every time motion is detected. The handle_interrupt function has an input parameter (pin) in which an object of class Pin will be passed when the interrupt happens (it indicates which pin caused the interrupt).

Here we’re saving the pin that caused the interrupt in the interrupt_pin variable. In this case, it is not very useful because we only have one interrupt pin. However, this can be useful if we have several interrupts that trigger the same interrupt handling function and we want to know which GPIO caused the interrupt.

In our example, the handle_interrupt function simply changes the motion variable to True and saves the interrupt pin. You should keep your handling interrupt functions as short as possible and avoid using the print() function inside. Then, the main code should have all the things we want to happen when the interrupt happens.

Note: as you want motionto be usable both inside the function and throughout the code, it needs to be declared as global. Otherwise, when motion is detected nothing would happen, because the motion variable would be changing inside the function and not in the main body of the code.

Proceeding with the code, we need to create two Pin objects. One for the LED on GPIO 12, and another for the PIR motion sensor on GPIO 14.

led = Pin(12, Pin.OUT)
pir = Pin(14, Pin.IN)

Then, set an interrupt on the pir by calling the irq() method.

pir.irq(trigger=Pin.IRQ_RISING, handler=handle_interrupt)

In the loop(), when the motionvariable is True, we turn the LED on for 20 seconds and print a message that indicates that motion was detected and which pin caused the interrupt.

if motion:
  print('Motion detected! Interrupt caused by:', interrupt_pin)
  led.value(1)
  sleep(20)

After 20 seconds, turn the LED off, and print a message to indicate that motion stopped.

led.value(0)
print('Motion stopped!')

Finally, set the motion variable to False:

motion = False

The motion variable can only become True again, if motion is detected and the handle_interrupt function is called.

For simplicity, in this example we use a delay to keep the LED on for 20 seconds. Ideally, you should use timers.

Demonstration

Upload the code to your ESP32/ESP8266 board. The LED should turn on for 20 seconds when motion is detected, and a message should be printed in the Shell.

After 20 seconds the LED turns off.

Note: the AM312 PIR motion sensor has a default delay time of 8 seconds. This means that it won’t be triggered before 8 seconds have passed since the last trigger.

Wrapping Up

We hope you’ve found this article interesting. We’ve learned how to:

• setup a pin as an interrupt
• handle that interrupt in your code
• detect which GPIO pin caused the interrupt

In our example, we’ve used a PIR motion sensor to trigger the interrupt. But the example presented can also be used to detect a button press, for example.

If you like programming the ESP32 and ESP8266 boards with MicroPython, and you want to learn more, please take a look at the following resources:

• MicroPython: WS2812B Addressable RGB LEDs with ESP32 and ESP8266
• Low Power Weather Station Datalogger using ESP8266 and BME280 with MicroPython
• MicroPython – Getting Started with MQTT on ESP32/ESP8266