Search by Tags

Basic GPIO usage - Iris Carrier Board - Colibri iMX6ULL


Your progress



In this lesson, you will learn the basics of GPIO usage on Linux, being able to read or write to a GPIO pin from command-line, as well as by developing a minimal C application.

In this lesson you will:

  • Understand how to translate the hardware pin names to the correspondent Linux sysfs interface numbers.
  • Assemble the additional hardware - an LED and a switch.
  • Use the Toradex GPIO Tool to validate the hardware setup.
  • Configure and use GPIO pins through the Linux sysfs.
  • Debug GPIO configuration.
  • Write minimal sample applications in C.

The information provided in this guide is based in Toradex's knowledge base article GPIO (Linux), as well as other knowledge sources such as kernel documentation and the Linux man-pages project.

Materials (Optional)

Since Iris Carrier Board doesn't have buttons and LEDs available for debbuging purposes, we present two alternatives to test GPIOs: the first connects two GPIOs configured as input and output respectively; whereas the second alternative uses an external button and LED to achieve a better user experience, however, the following items are required:

  • 1x LED
  • 1x Button
  • 1x Transistor BC548
  • 2x 2k2Ω Resistor
  • 1x 470Ω Resistor
  • 1x Breadboard
  • Jumper wires

Note: On this getting started we are going to use 2x Resistor 2k2Ω, but you can use anyone between 1kΩ and 10kΩ. For Resistor 470Ω, you can use anyone between 100Ω and 1kΩ. For the transistor BC548, you can use any switch component you want, as MOSFET, just change the circuit according to the component.

Step 1

To find out which GPIO number to use in the Linux sysfs interface, you have to know the correspondence between available pins in the carrier board, number of the correspondent pins on the SODIMM connector of the Colibri computer on module and number of the pins on Linux.

Download or open in a web browser the Iris Carrier Board and the Colibri iMX6ULL datasheets from the respective products pages of the developer website:

Iris Carrier Board datasheet

Colibri iMX6ULL datasheet

Step 2

For this introduction guide, some pins configured by default as GPIO in the Toradex BSP were chosen. The choice of pins was made based on their availability on all the carrier boards covered by the getting-started guide. This module will not go through the configuration of other pins as GPIO, although it is possible.

First of all, you need to find the correspondence between the SODIMM and the connectors exposed for the developer on the Iris Carrier Board. Consult the Iris Carrier Board datasheet and fill the table below based in the example provided:

Note: The notation CONNECTOR.PIN will be employed in this lesson, e.g. X12.5 means pin 5 of the X12 connector.

Iris Carrier Board ( SODIMM pins
X16.19 79
Table 1 filled

Step 3

Have a look at the table available in the "List Functions" chapter of the Colibri iMX6ULL datasheet. It provides a list of most of the iMX6ULL pins available on the SODIMM connector.

The SODIMM pins we are interested at are connected to the iMX6ULL SoC and have names defined by the iMX6ULL Ball Name function. Each pin is multiplexed to have a specific function - among them GPIO, therefore the ALT5 function is the column that we are interested at.

Having a look at the GPIO Alphanumeric to GPIO Numeric Assignment article, the correspondence between ALT5 and the Linux numeric representation of the GPIO pins is provided as a table. To find it from the ALT5 it is possible to use the formula below:

Linux numeric representation = [(x-1)*32]+y

Either by consulting the table from the article pointed above or calculating it, the previous table with the correspondence between Iris Carrier Board pins and SODIMM pins can be extended to have the iMX6ULL pin name (ALT5), formed by GPIO controller, as example GPIO07, plus pin at SoC level, as example IO09, and the Linux numeric representation. Fill the table below based in the example provided:

Iris Carrier Board ( SODIMM pins iMX6ULL name (ALT5) Linux GPIO number
X16.19 79 GPIO4_IO23 119
X16.18 85
X16.17 97
X16.13 98
X16.16 101
X16.15 103
X16.14 133
Table 2 filled

Step 4

Choose two of the GPIO pins from the list above to make a loopback test. This lesson will use the following pins (Linux GPIO number):

  • 118 as Input
  • 120 as Output

Use jumper wires to connect GPIO 118 to GPIO 120.

Step 5

The Toradex Linux pre-built image comes with a tool named Toradex GPIO tool meant for debugging pins configuration. It can also be used to determine the correspondences found in the previous step. We will use it to test the hardware connections.

Note: You need a display and a mouse connected to the system in order to use the GPIO tool. Please go to the beginning of the getting-started guide for more information about assembling the peripherals.

Run the GPIO tool from the target Linux desktop:

  • Starting the GPIO tool

    Starting the GPIO tool

  • GPIO tool initial screen

    GPIO tool initial screen

Step 6

Locate the pins 118 and 120 in the table. Right click the direction of each of them and configure pin 118 as INPUT and pin 120 as OUTPUT. See the changes reflected in the application.

  • Configuring SODIMM pin

    Configuring SODIMM pin

Step 7

Click the Logic checkbox of pin 120 and see the logic checkbox of pin 118 switch on/off.

  • Logic checkbox toggled from GPIO tool

    Logic checkbox toggled from GPIO tool

Step 8

The Linux sysfs interface provides an abstraction to access the GPIO, as well as many other hardware features, from the Linux user-space.

The pin has to be exported first, which guarantees that it is not being used by other kernel drivers nor allow other drivers to use it. It also has to be configured as input or output.

From the Linux terminal, export the pins 118 and 120:

echo 118 > /sys/class/gpio/export
echo 120 > /sys/class/gpio/export

Configure the pins as input and output, respectively:

echo "in" > /sys/class/gpio/gpio118/direction
echo "out" > /sys/class/gpio/gpio120/direction

Step 9

Read the INPUT value as you toggle OUTPUT value:

echo 1 > /sys/class/gpio/gpio120/value
cat /sys/class/gpio/gpio118/value
echo 0 > /sys/class/gpio/gpio120/value
cat /sys/class/gpio/gpio118/value

Steps 10 to 17 (Optional)

The following steps are meant for readers that have the optional items listed in the beginning of this lesson. If you want to go through them, click the dropdown link below:

Steps 10 to 17


This lesson only covers the basics of GPIO usage on Linux. Since there are other important topics that were not discussed, this FAQ section is meant as an information complement.

What is the sysfs interface
Where can I find more information regarding GPIO in the Toradex documentation
Should I always use the sysfs interface when I need to use a GPIO
How can I use pins that are not configured as GPIO by default
How can I use more GPIOs than available for a specific module
I dont want to reconfigure pins as GPIO due to Toradex pin compatibility How can I work around this
Linux has a kernel driver for controlling LEDs How to use it
Can I control backlight brightness using GPIO
Is it possible to use a GPIO to shutdown the system
Is it possible to use a GPIO to suspend resume the system
Can I toggle a GPIO earlier than Linux boots
Can I bypass sysfs to have direct access to GPIO
What is the initial state of a GPIO pin
How to set the initial state of a GPIO pin
What happens when a GPIO pin is unexported