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:
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:
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.
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 T20 datasheets from the respective products pages of the developer website:
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 (connector.pin)||SODIMM pins|
Have a look at the table available in the "List Functions" chapter of the Colibri T20 datasheet. It provides a list of most of the Tegra pins available on the SODIMM connector.
The SODIMM pins we are interested at are connected to the Tegra SoC and have names defined by the Tegra Pin Name function. Each pin is multiplexed to have a specific function - among them GPIO, therefore the GPIO function is the column that we are interested at.
Having a look at the GPIO Alphanumeric to GPIO Numeric Assignment article, the correspondence between GPIO and the Linux numeric representation of the GPIO pins is provided as a table. To find it from the GPIO it is possible to use the formula below:
GPIO-(Character).DigitLinux numeric representation = 8 x (Character - 'A') + Digit
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 Tegra pin name (GPIO), formed by GPIO character and digit, as example GPIO-T.02, and the Linux numeric representation. Fill the table below based in the example provided:
|Iris Carrier Board (connector.pin)||SODIMM pins||Tegra pin name (GPIO)||Linux GPIO number|
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):
Use jumper wires to connect GPIO 201 to GPIO 196.
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 201 and 196 in the table. Right click the direction of each of them and configure pin 201 as INPUT and pin 196 as OUTPUT. See the changes reflected in the application.
Click the Logic checkbox of pin 196 and see the logic checkbox of pin 201 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 201 and 196:
echo 201 > /sys/class/gpio/exportecho 196 > /sys/class/gpio/export
Configure the pins as input and output, respectively:
echo "in" > /sys/class/gpio/gpio201/directionecho "out" > /sys/class/gpio/gpio196/direction
Read the INPUT value as you toggle OUTPUT value:
echo 1 > /sys/class/gpio/gpio196/valuecat /sys/class/gpio/gpio201/valueecho 0 > /sys/class/gpio/gpio196/valuecat /sys/class/gpio/gpio201/value
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:[COLLAPSE=Steps 10 to 17]
The steps below will use the following pins (Linux GPIO number) to toggle an LED and read the value of a switch:
Use jumper wires to connect GPIO 196 to 2k2Ω resistor, connect the resistor to transistor base pin, connect pin X16.12 (5V) from iris to 470Ω resistor, connect the resistor to one LED and connect to transistor collector pin, connect the transistor emitter pin to pin X16.2 (GND) on Iris Carrier Board. Use jumper wires to connect pin X16.33 (3,3V) to 2k2Ω resistor, connect the resistor to one switch and to GPIO 201, and connect the node to pin X16.21 (GND) on Iris Carrier Board.
Read the switch value as you toggle it:
Note: If the module was rebooted the GPIO must be configured again as explained in Step 8.
Toggle the LED GPIO:
echo 1 > /sys/class/gpio/gpio196/valueecho 0 > /sys/class/gpio/gpio196/value
Note: If the module was rebooted the GPIO must be configured again as explained in Step 8.
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 T20, and try it yourself:
root@colibri-t20:~# cat /sys/kernel/debug/gpioGPIOs 0-255, tegra-gpio:gpio-10 (SODIMM pin 154 ) in logpio-17 (SODIMM pin 81 ) in logpio-23 (sdhci_cd ) in logpio-26 (THERMD_ALERT ) in higpio-29 (sysfs ) out higpio-67 (SODIMM pin 130 ) in logpio-70 (SODIMM pin 132 ) in logpio-85 (USBC_DET ) in logpio-86 (KEY_MENU ) in higpio-90 (sysfs ) out logpio-91 (sysfs ) out higpio-94 (sysfs ) out higpio-110 (SODIMM pin 162 ) in logpio-111 (hdmi_hpd ) in logpio-144 (SODIMM pin 73 ) in logpio-153 (EN_MIC_GND ) out higpio-157 (KEY_BACK ) in higpio-158 (KEY_HOME ) in higpio-168 (TOUCH_PEN_INT ) in higpio-169 (KEY_POWER ) in logpio-170 (BL_ON ) out higpio-171 (SODI-85, Iris X16-18) out logpio-178 (usb_host_vbus ) out logpio-181 (SODIMM pin 75 ) in logpio-188 (SODIMM pin 134 ) in logpio-190 (102, I X13 ForceOFF#) in logpio-191 (104, I X14 ForceOFF#) in logpio-196 (sysfs ) out logpio-197 (sysfs ) out logpio-198 (sysfs ) out logpio-199 (sysfs ) out higpio-201 (sysfs ) out logpio-220 (SODIMM pin 166 ) in logpio-221 (SODIMM pin 168 ) in logpio-222 (SODIMM pin 170 ) in logpio-223 (SODIMM pin 172 ) in logpio-226 (KEY_FIND ) in logpio-230 (KEY_VOLUMEDOWN ) in higpio-231 (SODIMM pin 94 ) in logpio-232 (LAN_RESET ) out higpio-234 (LAN_V_BUS ) out higpio-237 (SODIMM pin 69 ) in higpio-238 (SODIMM pin 65 ) in higpio-239 (KEY_VOLUMEUP ) in hiGPIOs 256-264, i2c/4-002d, tps6591x, can sleep:gpio-262 (fixed_reg_en_hdmi ) out lo
See that the pins 201 and 196, 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/tegra_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.