nRF Connect SDK Fundamentals

Feedback
Feedback

If you are having issues with the exercises, please create a ticket on DevZone: devzone.nordicsemi.com
Click or drag files to this area to upload. You can upload up to 2 files.
Register

GPIO Generic API

v2.x.x

To interact with the General-Purpose Input/Output (GPIO) peripheral, we can use the generic API <zephyr/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 any driver in Zephyr, the first step is to initialize it by retrieving the device pointer. For a GPIO pin, the first necessary step after that 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 four steps will be covered in detail.

Initializing the API

Some of the generic APIs in Zephyr have API-specific structs that contain the previously mentioned device pointer, as well as some other information about the device. In the GPIO API, this is the structure gpio_dt_spec. This structure has the device pointer const struct device * port, as well as the pin number on the device, gpio_pin_t pin, and the device’s configuration flags, gpio_dt_flags_t dt_flags.

The port is the GPIO device controlling the pin. Pins are usually grouped and controlled by a single GPIO port. On most Nordic SoCs, there are either one or two GPIO controllers, named GPIO0 or GPIO1.

You can check this in the SoCs product specification. For example, see the nRF52833 Product Specification section GPIO — General purpose input/output.

To retrieve this structure, we need to use the API-specific function GPIO_DT_SPEC_GET(), which has the following signature:

Similar to DEVICE_DT_GET(), GPIO_DT_SPEC_GET() also takes the devicetree node identifier. It also takes the property name of the node. The function will return a variable of type gpio_dt_spec, containing the device pointer as well as the pin number and configuration flags.

The advantage of this API-specific structure is that it encapsulates all the information needed to use the device in a single variable, instead of having to extract it from the devicetree line by line.

Let’s take led_0 as an example, which has the devicetree implementation shown below:

From the image above, we can see that the property containing all this information is called gpios, and is the property name to pass to GPIO_DT_SPEC_GET():

static const struct gpio_dt_spec led = GPIO_DT_SPEC_GET(LED0_NODE, gpios);

This function will return a struct of type gpio_dt_spec with the device pointer for the GPIO controller, &gpio0, the pin number led.pin = 13 and the flag led.dt_flags = GPIO_ACTIVE_LOW.

Before using the device pointer contained in gpio_dt_spec led, we need to check if it’s ready using gpio_is_ready_dt(). 

	if (!gpio_is_ready_dt(&led)) {
		return 0;
	}

Configure a single pin

This is done by calling the function gpio_pin_configure_dt(), 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 second parameter flags as shown in the examples below.

The following line configures the pin associated with gpio_dt_spec led, which can be denoted as led.pin, as an output pin:

gpio_pin_configure_dt(&led, GPIO_OUTPUT);

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 parameter flags.

The following line configures the pin led.pin as an output that is active low.

gpio_pin_configure_dt(&led, GPIO_OUTPUT | 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_dt(), which has the following signature:

For example, the following line sets the pin associated with gpio_dt_spec led, which can be denoted as led.pin, to logic 1 “active state”:

gpio_pin_set_dt(&led, 1);

For instance, for the node led_0 on the nRF52833DK, this would set pin 13 to logic 1 “active state”.

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

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

gpio_pin_toggle_dt(&led);

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_dt(), which has the following signature:

For example, the following line reads the current status of led.pin saves it in a variable called val.

val = gpio_pin_get_dt(&led);

The drawback of the polling method is that you have to repeatedly call gpio_pin_get_dt() 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.

Note

You can only configure an interrupt on a GPIO pin configured as an input.

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_dt(), which has the signature shown below:

Through the second 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 dev.pin on the change to logical level 1.

gpio_pin_interrupt_configure_dt(&button,GPIO_INT_EDGE_TO_ACTIVE);

All interrupt flag options are documented here.

2. Define the callback function pin_isr().

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, gpio_port_pins_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_dt(&led);
}

3. 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).

4. Initialize the gpio callback variable pin_cb_data using gpio_init_callback().

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 dev.pin. 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(dev.pin));

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(button.port, &pin_cb_data);

The full API documentation for GPIO generic interface is available here

v1.6.0 – v1.9.1

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. 

Make sure to Log in or Register to save your progress

Back
Next
Register an account
Already have an account? Log in
(All fields are required unless specified optional)

  • 8 or more characters
  • Upper and lower case letters
  • At least one number or special character

Forgot your password?
Enter the email associated with your account, and we will send you a link to reset your password.