| 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=<install path> |
| 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 PYTHON_CPPFLAGS and PYTHON_LIBS 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 |
| linux-gpio@vger.kernel.org (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 |