Skip to main content
Version: 6

How to Use GPIO on TorizonCore

Introduction​

The Kernel Linux GPIO user space SysFS is deprecated and has been discontinued. On the other hand, the kernel config CONFIG_GPIO_SYSFS is still enabled on our BSP as many customers still use it on their legacy applications - you can check it with zcat /proc/config.gz | grep CONFIG_GPIO_SYSFS. Its use is discouraged and might be removed from mainline Linux after 2020 as can be seen on sysfs-gpio documentation. For GPIO access from userspace, the new char device API, also known as libgpiod, must be used.

The new user space API uses the /dev/gpiochip devices through ioctl calls to manage GPIOs:

# ls /dev/gpiochip*
/dev/gpiochip0  /dev/gpiochip2  /dev/gpiochip4  /dev/gpiochip6
/dev/gpiochip1  /dev/gpiochip3  /dev/gpiochip5  /dev/gpiochip7

Each entry on the /dev/gpiochip corresponds to a GPIO bank that the operating system has access to.

Even though Torizon is preferred for using libgpiod, it is also supported and can be used on Toradex BSP Layers and Reference Images for Yocto Project from the release 3.0b3 onwards. The userspace tools and libraries are included in our evaluation image. If you are looking for more general information on how to use the command-line tools and the C API as well, refer to GPIO (Linux).

info

Non-generic features such as GPIO power management keys, GPIO power off, GPIO LED, U-boot and others explained in GPIO (Linux) also work in TorizonCore.

This article complies with the Typographic Conventions for Toradex Documentation.

libgpiod​

The libgpiod library encapsulates the ioctl calls and data structures for GPIO in a straightforward API. Additionally, the libgpiod project contains a set of command-line tools allowing GPIO access and control from the command-line. These command-line tools can also be used to replace scripts that used the deprecated sysfs API directly.

Prerequisites​

Software Requirements​

Hardware Requirements​

If you want to see things happening, hook up a LED (or a multimeter) and switch (and of course other components to interface with the TTL level from your SoM) to the GPIO pins:

  • Apalis MXM3 pin 3 (Apalis GPIO2): Switch
  • Apalis MXM3 pin 5 (Apalis GPIO3): LED (or a multimeter)

For Colibri and Verdin, we leave it up to you to choose the pins.

danger

The TTL level for Colibri and Apalis I/O is 3.3V and for Verdin is 1.8V. Do not apply 3.3V signals to Verdin I/O.

Command-line Tools​

To get started with the libgpiod command-line tools let's exemplify some commands. We will use TorizonCore for testing with a pre-built container. We also provide optional instructions for you to re-build the container if you want.

Bring up the Container​

Choose your SoM's architecture from the tabs below:

The Dockerfile below is built into the image torizonextras/arm64v8-gpiod:

  • Dockerfile Run the following command on the board terminal to download the image and mount the container for testing:
# docker run --rm -it --device /dev/gpiochip0 torizonextras/arm64v8-gpiod

Note that in the docker run command, the argument --device pass the char device from the GPIO bank that will be shared and accessed inside the container. You may specify that argument multiple times if access to different GPIO banks is required, as shown bellow:

# docker run --rm -it --device /dev/gpiochip0 --device /dev/gpiochip1 torizonextras/arm64v8-gpiod

TorizonCore comes with udev rules which allow access for users part of the gpio group. Adding the torizon user to the group allows to also access GPIOs as a user from within the container. Use USER torizon in your Dockerfile if you prefer running the container as non-root user, as exemplified in the sample Dockerfile.

Command-line Tools Usage​

After launching the container, you should be able to run, inside the container, any command explained in the section Command Line Tools on GPIO (Linux).

Sample Applications​

To use GPIO and libgpiod functionalities, choose the programming language you want to use and follow the steps described in the related section.

C Language Examples​

Some examples are provided in this chapter, illustrating how to use the C API from libgpiod. Pre-built containers are not provided, therefore you are encouraged to build your own, in which case you will need the optional dependencies.

First, clone the torizon-samples repository to the host computer:

$ git clone https://github.com/toradex/torizon-samples.git
$ cd torizon-samples/gpio

Then, you will be able to build and deploy the container, as well as run the samples, as explained in the next sections.

Build the Docker Image With the C Samples​

In this section, you will compile all the C examples and build a Container image to be easily deployed to the board. Choose your SoM from the tabs below:

info

For the examples below we will use the multi-stage Docker build. It is a best practice and you are encouraged to understand how it is implemented.

The sample Dockerfile used is:

Assuming that you have cloned the torizon-samples repository as described in the Software Requirements, you can modify and re-build the image by yourself in your development PC.

First, build the container image.

$ docker build -f Dockerfile.arm64 -t <yourDockerHubUsername>/arm64v8-c-gpiod .

Upload the image generated in the command above to your Docker Hub:

$ docker login
$ docker push <yourDockerHubUsername>/arm64v8-c-gpiod

After that, on the board's terminal, run the following command to pull the image from Docker Hub:

# docker pull <yourDockerHubUsername>/arm64v8-c-gpiod

Now you are ready to understand and run the samples documented at How to toggle a GPIO and Read GPIO Using Interrupt Driven Events. The sections below help you to run the mentioned examples using the previously built containers.

How to Toggle a GPIO​

Run How to toggle a GPIO example using the previously built and deployed container. Choose your SoM from the tabs below:

This example uses the Apalis iMX8 GPIO3 - LSIO.GPIO0.IO12:

# docker run --rm -it --init --device /dev/gpiochip0 yourdockerhubuser/arm64v8-c-gpiod
## gpio-toggle 0 12

Read GPIO Using Events (Interrupt Driven)​

Run Read GPIO Using Interrupt Driven Events example using the previously built and deployed container. Choose your SoM from the tabs below:

This example uses the Apalis iMX8 GPIO3 - LSIO.GPIO0.IO12 as output and GPIO2 - LSIO.GPIO0.IO9 as input.

# docker run --rm -it --init --device /dev/gpiochip0 yourdockerhubuser/arm64v8-c-gpiod
## gpio-event 0 9 0 12

.NET Examples​

The article .NET Core Development and Debugging on Torizon Using Visual Studio Code explains how to use libgpiod with .NET.

Python Examples​

Our samples repository on GitHub provides an example: Python libgpiod example The following articles can help you with enough context for running and extending the sample:



Send Feedback!