Attention: the Quickstart Guide for BSP 2.8, based on the Ångström distribution, is not being updated anymore. Depending on your SoM, you have different options:
Vybrid and Tegra: the information is provided as-is and still accurate, since newer Toradex BSPs are not ported to those SoMs. Just keep in mind that the Guides are not being maintained anymore, even if we find bugs or outdated instructions.
Apalis TK1 (all variants), Colibri iMX6ULL (all variants), Colibri iMX7S 256MB and Colibri iMX7D 512MB: these computer on modules are still regularly maintained in our BSPs and, to get started, you must check the software page Toradex BSP Layers and Reference Images for Yocto Project. Since Torizon is not supported, at the moment a Quickstart Guide is not available.
All other i.MX-based SoMs: you have two options to get started with embedded Linux: the first is to follow the Quickstart Guide for Torizon, which provides the greatest out-of-the-box experience, or if you choose to use Yocto, check the software page Toradex BSP Layers and Reference Images for Yocto Project.
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:
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.
The Colibri Evaluation Board already has buttons and LEDs available for debugging purposes, therefore only jumper wires are required.
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 Colibri Evaluation Board and the Colibri iMX6ULL datasheets from the respective products pages of the developer website:
Colibri Evaluation Board datasheet
For this introduction guide, some pins configured as GPIO by default 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 Colibri Evaluation Board V3.2. Consult the Colibri Evaluation 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.
Colibri Evaluation Board (connector.pin) | SODIMM pins |
---|---|
X22.9 | 79 |
Warning: The pinout of the Camera Interface connector (X22) has been updated from Colibri Evaluation Board V3.1 to V3.2. Please consult the datasheet if you are using the older version.
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:
PORTx[y]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 Colibri Evaluation Board pins and SODIMM pins can be extended to have the iMX6ULL pin name (ALT5), formed by GPIO controller, as example GPI07, plus pin at SoC level, as example IO09, and the Linux numeric representation. Fill the table below based in the example provided:
Colibri Evaluation Board (connector.pin) | SODIMM pins | iMX6ULL name (ALT5) | Linux GPIO number |
---|---|---|---|
X22.18 | 65 | GPIO2_IO28 | 124 |
X22.21 | 69 | ||
X22.3 | 75 | ||
X22.17 | 85 | ||
X22.4 | 96 | ||
X22.8 | 98 | ||
X3.A32 | 133 |
Choose two of the GPIO pins from the list above to toggle an LED and read the value of a switch. This lesson will use the following pins (Linux GPIO number):
Use jumper wires to connect GPIO 110 to the slide switch SW4 on the connector X21.7, and GPIO 124 to the LED1 on the connector X21.2.
Note: For more informations about pins schematic, please access the Colibri Evaluation Board schematics here.
Note: You may use any other of the LEDs/switches available. Please refer to the section 3.9.2.3 LED / Switches (X21) of the Colibri Evaluation Board datasheet.
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:
Locate the pins 110 and 124 in the table. Right click the direction of each of them and configure pin 110 as INPUT and pin 124 as OUTPUT. See the changes reflected in the application.
Toggle the switch SW4 and see the Logic checkbox of the pin 110 change its state. Click the Logic checkbox of pin 124 and see the LED switch on/off.
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 110 and 124:
echo 110 > /sys/class/gpio/exportecho 124 > /sys/class/gpio/export
Configure the pins as input and output, respectively:
echo "in" > /sys/class/gpio/gpio110/directionecho "out" > /sys/class/gpio/gpio124/direction
Read the switch value as you toggle it:
cat /sys/class/gpio/gpio110/value
Toggle the LED GPIO:
echo 1 > /sys/class/gpio/gpio124/valueecho 0 > /sys/class/gpio/gpio124/value
There is a debug interface provided by the kernel debugfs for GPIO, which holds information about GPIO pins already reserved for drivers, as well as pin configuration and state. See the example below for the Colibri iMX6ULL, and try it yourself:
root@colibri-imx6:~# cat /sys/kernel/debug/gpiogpiochip0: GPIOs 0-31, parent: platform/209c000.gpio, 209c000.gpio:gpiochip1: GPIOs 32-63, parent: platform/20a0000.gpio, 20a0000.gpio:gpio-37 ( |cd ) in higpio-54 ( |Wake-Up ) in logpiochip2: GPIOs 64-95, parent: platform/20a4000.gpio, 20a4000.gpio:gpio-90 ( |enable ) out higpio-95 ( |usb_host_vbus ) out logpiochip3: GPIOs 96-127, parent: platform/20a8000.gpio, 20a8000.gpio:gpio-108 ( |scl ) in higpio-109 ( |sda ) in higpio-110 ( |sysfs ) in higpio-124 ( |sysfs ) out logpiochip4: GPIOs 128-159, parent: platform/20ac000.gpio, 20ac000.gpio:gpio-130 ( |spi_imx ) out higpiochip5: GPIOs 160-191, parent: platform/20b0000.gpio, 20b0000.gpio:gpiochip6: GPIOs 192-223, parent: platform/20b4000.gpio, 20b4000.gpio:gpio-204 ( |id ) in lo
See that the pins 110 and 124, configured as input and output in the previous steps, are the only ones taken by sysfs and are correctly configured as in and out respectively.
Export, unexport, configure and toggle the GPIO pins as you read the debugfs information to see the changes.
Note: If you want additional pin configuration debug, explore the /sys/kernel/debug/pinctrl/ directory.
Write a small C application that toggles the LED GPIO. A small source-code is given below for reference and you may copy-paste it to your previously configured Eclipse environment.
Warning: The source-codes provided in this guide are distributed under the 3-clause BSD license terms. See below:
Write a small C application that reads the switch GPIO. A small source-code is given below for reference and you may copy-paste it to your previously configured Eclipse environment.
The GPIO sysfs interface enables the use of interrupts from user space, as long as it is supported by the underlying hardware. Read the sysfs GPIO documentation, have a look at the poll system call and try to implement an application that handles the interrupt. Have a look at the source code below for reference:
To prevent the main loop from blocking, run the GPIO IRQ handling in a separate thread. Try to implement it.
Improve the code from the previous steps to handle errors and add other functionality you want. The code below implements a frequency meter by measuring the elapsed time between GPIO interruptions:
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.