Need help with libgpiod?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

brgl
169 Stars 63 Forks GNU Lesser General Public License v2.1 889 Commits 6 Opened issues

Description

NOTE - this project is now hosted at kernel.org and the development happens on the linux-gpio mailing list.

Services available

!
?

Need anything else?

Contributors list

libgpiod

libgpiod - C library and tools for interacting with the linux GPIO character device (gpiod stands for GPIO device)

Since linux 4.8 the GPIO sysfs interface is deprecated. User space should use the character device instead. This library encapsulates the ioctl calls and data structures behind a straightforward API.

RATIONALE

The new character device interface guarantees all allocated resources are freed after closing the device file descriptor and adds several new features that are not present in the obsolete sysfs interface (like event polling, setting/reading multiple values at once or open-source and open-drain GPIOs).

Unfortunately interacting with the linux device file can no longer be done using only standard command-line tools. This is the reason for creating a library encapsulating the cumbersome, ioctl-based kernel-userspace interaction in a set of convenient functions and opaque data structures.

Additionally this project contains a set of command-line tools that should allow an easy conversion of user scripts to using the character device.

BUILDING

This is a pretty standard autotools project. It does not depend on any libraries other than the standard C library with GNU extensions.

The autoconf version needed to compile the project is 2.61.

Recent kernel headers are also required for the GPIO user API definitions. For the exact version of kernel headers required, please refer to the configure.ac contents.

To build the project (including command-line utilities) run:

./autogen.sh --enable-tools=yes --prefix=
make
make install

The autogen script will execute ./configure and pass all the command-line arguments to it.

If building from release tarballs, the configure script is already provided and there's no need to invoke autogen.sh.

TOOLS

There are currently six command-line tools available:

  • gpiodetect - list all gpiochips present on the system, their names, labels and number of GPIO lines

  • gpioinfo - list all lines of specified gpiochips, their names, consumers, direction, active state and additional flags

  • gpioget - read values of specified GPIO lines

  • gpioset - set values of specified GPIO lines, potentially keep the lines exported and wait until timeout, user input or signal

  • gpiofind - find the gpiochip name and line offset given the line name

  • gpiomon - wait for events on GPIO lines, specify which events to watch, how many events to process before exiting or if the events should be reported to the console

Examples:

# Read the value of a single GPIO line.
$ gpioget gpiochip1 23
0

Read two values at the same time. Set the active state of the lines

to low.

$ gpioget --active-low gpiochip1 23 24 1 1

Set values of two lines, then daemonize and wait for a signal (SIGINT or

SIGTERM) before releasing them.

$ gpioset --mode=signal --background gpiochip1 23=1 24=0

Set the value of a single line, then exit immediately. This is useful

for floating pins.

$ gpioset gpiochip1 23=1

Find a GPIO line by name.

$ gpiofind "USR-LED-2" gpiochip1 23

Toggle a GPIO by name, then wait for the user to press ENTER.

$ gpioset --mode=wait gpiofind "USR-LED-2"=1

Wait for three rising edge events on a single GPIO line, then exit.

$ gpiomon --num-events=3 --rising-edge gpiochip2 3 event: RISING EDGE offset: 3 timestamp: [ 1151.814356387] event: RISING EDGE offset: 3 timestamp: [ 1151.815449803] event: RISING EDGE offset: 3 timestamp: [ 1152.091556803]

Wait for a single falling edge event. Specify a custom output format.

$ gpiomon --format="%e %o %s %n" --falling-edge gpiochip1 4 0 4 1156 615459801

Pause execution until a single event of any type occurs. Don't print

anything. Find the line by name.

$ gpiomon --num-events=1 --silent gpiofind "USR-IN"

Monitor multiple lines, exit after the first event.

$ gpiomon --silent --num-events=1 gpiochip0 2 3 5

BINDINGS

High-level, object-oriented bindings for C++ and python3 are provided. They can be enabled by passing --enable-bindings-cxx and --enable-bindings-python arguments respectively to configure.

C++ bindings require C++11 support and autoconf-archive collection if building from git.

Python bindings require python3 support and libpython development files. Care must be taken when cross-compiling python bindings: users usually must specify the PYTHONCPPFLAGS and PYTHONLIBS variables in order to point the build system to the correct locations. During native builds, the configure script can auto-detect the location of the development files.

TESTING

A comprehensive testing framework is included with the library and can be used to test both the core library code as well as the kernel-to-user-space interface.

The minimum kernel version required to run the tests can be checked in the tests/gpiod-test.c source file (it's subject to change if new features are added to the kernel). The tests work together with the gpio-mockup kernel module which must be enabled. NOTE: the module must not be built-in. A helper library - libgpiomockup - is included to enable straightforward interaction with the module.

To build the testing executable add the '--enable-tests' option when running the configure script. If enabled, the tests will be installed next to gpio-tools.

As opposed to standard autotools projects, libgpiod doesn't execute any tests when invoking 'make check'. Instead the user must run them manually with superuser privileges.

The testing framework uses the GLib unit testing library so development package for GLib must be installed.

The gpio-tools programs can be tested separately using the gpio-tools-test.bats script. It requires bats[1] to run and assumes that the tested executables are in the same directory as the script.

Both C++ and Python bindings also include their own test-suites. Both reuse the libgpiomockup library to avoid code duplication when interacting with gpio-mockup.

Python test-suite uses the standard unittest package. C++ tests use an external testing framework - Catch2 - which must be installed in the system.

DOCUMENTATION

All API symbols exposed by the core C API and C++ bindings are documented with doxygen markup blocks. Doxygen documentation can be generated by executing 'make doc' given that the doxygen executable is available in the system.

Python bindings contain help strings that can be accessed with the help builtin.

Man pages for command-line programs are generated automatically if gpio-tools were selected and help2man is available in the system.

CONTRIBUTING

Contributions are welcome - please send patches and bug reports to [email protected] (add the [libgpiod] prefix to the e-mail subject line) and stick to the linux kernel coding style when submitting new code.

[1] https://github.com/bats-core/bats-core

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.