You are currently not logged in and your progress will not be saved. Register or Log in

GPIO Generic API

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.

Configure a single pin

This is done by calling the function gpio_pin_configure(), which has the following signature:

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.

gpio_pin_configure(dev, 13, GPIO_OUTPUT | GPIO_ACTIVE_LOW);

You can also specify the initial state of a certain pin by using the flag options GPIO_OUTPUT_INACTIVE or GPIO_OUTPUT_ACTIVE.

The following line configures pin 13 as an output (active low) and initializes it to a logic 1.

gpio_pin_configure(dev, 13, GPIO_OUTPUT_ACTIVE| GPIO_ACTIVE_LOW);

All GPIO flags are documented here.

Write to an output pin

Writing to an output pin is straightforward by using the function gpio_pin_set(), which has the following signature:

For example, the following line sets pin 13 to logic 1 “active state”:

gpio_pin_set(dev, 13, 1); //Set pin 13 to 1

While this line sets pin 13 to logic 0 “inactive state”:

gpio_pin_set(dev, 13, 0); //Set pin 13 to 0

You can also use the gpio_pin_toggle() function to toggle an output pin.

For example, the following line will toggle pin 13, whenever this API is called.

gpio_pin_toggle(dev,13);

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 method

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.

bool 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.

Interrupt method

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.

1. Configure the interrupt on a pin.

This is done by calling the function gpio_pin_interrupt_configure(), which has the signature shown below:

Through the third parameter flags, you can configure whether you want to trigger the interrupt on rising edge, falling edge, or both. Or change to logical level 1, logical level 0, or both.

The following line will configure an interrupt on pin 11 on the change to logical level 1.

gpio_pin_interrupt_configure(dev,11,GPIO_INT_EDGE_TO_ACTIVE);

All interrupt flag options are documented here.

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.

Definition

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:

void pin_isr(const struct device *dev, struct gpio_callback *cb, uint32_t pins);

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.

gpio_init_callback(&pin_cb_data, pin_isr, BIT(11));

5. The final step is to add the callback function through the function gpio_add_callback().

For example, the following line adds the callback function that we set up in the previous steps.

gpio_add_callback(dev, &pin_cb_data);

The full API documentation for GPIO generic interface is available here