To interact with the General-Purpose Input/Output (GPIO) peripheral, we can use the generic API <drivers/gpio.h>, which provides user-friendly functions to interact with GPIO peripherals. The GPIO peripheral can be used to interact with a variety of external components such as switches, buttons, and LEDs.
When using a GPIO pin, the first necessary step is to configure the pin to be either an input or an output pin. Then you can write to an output pin or read from an input pin. In the following paragraphs, these three main steps will be covered in detail.
With this function, you can configure a pin to be an input GPIO_INPUT or an output GPIO_OUTPUT through the third parameter flags as shown in the examples below.
The following line configures pin 13 as an output pin:
gpio_pin_configure(dev, 13, GPIO_OUTPUT);
While the following line configures pin 11 as an input pin:
gpio_pin_configure(dev, 11, GPIO_INPUT);
You can also specify other hardware characteristics to a pin like the drive strength, pull up/pull down resistors, active high or active low. Different hardware characteristics can be combined through the | operator. Again, this is done using the third parameter flags.
The following line configures pin 13 as an output that is active low.
For example, the following line will toggle pin 13, whenever this API is called.
Read from an input pin
Reading a pin configured as an input is not as straightforward as writing to a pin configured as an output. There are two possible methods to read the status of an input pin:
Polling means continuously reading the status of the pin to check if it has changed. To read the current status of a pin, all you need to do is to call the function gpio_pin_get(), which has the following signature:
For example, the following line reads the current status of pin 11 and saves it in a variable called val.
val = gpio_pin_get(dev, 11);
The drawback of the polling method is that you have to repeatedly call gpio_pin_get() to keep track of the status of a pin. This is usually not optimal from performance and power perspectives as it requires the CPU’s constant attention. It’s a simple method, yet not power-efficient.
We will use this method in Exercise 1 of this lesson for demonstration purposes.
In this method, the hardware will notify the CPU once there is a change in the status of the pin. This is the recommended way to read an input pin as it frees the CPU from the burden of repeatedly polling the status of the pin. You can put the CPU to sleep and only wake it up when there is a change.
We will use this method in Exercise 2 of this lesson.
The following are the general steps needed to set up an interrupt on a GPIO pin.
2. Define a variable of type static struct gpio_callback as shown in the code line below.
static struct gpio_callback pin_cb_data;
The pin_cb_data gpio callback variable will hold information such as the pin number and the function to be called when an interrupt occurs (callback function).
3. Define the callback function.
The callback function is called when an interrupt is triggered.
Callback function: Also known as an interrupt handler or an Interrupt Service Routine (ISR). It runs asynchronously in response to a hardware or software interrupt. In general, ISRs have higher priority than all threads (covered in Lesson 7). It preempts the execution of the current thread, allowing an action to take place immediately. Thread execution resumes only once all ISR work has been completed.
The signature (prototype) of the callback function is shown below:
What you put inside the body of an ISR is highly application-dependent. For instance, the following ISR toggles a LED every time the interrupt is triggered.
void pin_isr(const struct device *dev, struct gpio_callback *cb, uint32_t pins)
gpio_pin_toggle(dev,LED_PIN); //LED_PIN is an output pin connected to a LED
4. Initialize the static struct gpio_callback variable defined in step 2.
This gpio_callback struct variable stores the address of the callback function and the bitmask relevant to the pin. Use the function gpio_init_callback() to do this initialization.
For example, the following line will initialize the pin_cb_data variable with the callback function pin_isr and the bit mask of pin 11. Note the use of the macro BIT(n), which simply gets an unsigned integer with bit position n set.