| 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 (as in >= v4.8) kernel headers are also required for the GPIO user |
| API definitions. |
| |
| 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 |
| |
| TESTING |
| ------- |
| |
| A comprehensive testing framework is included with the library and can be |
| used to test both the library code and the linux kernel user-space interface. |
| |
| The minimum kernel version required to run the tests is 4.16. The tests work |
| together with the gpio-mockup kernel module which must be enabled. NOTE: the |
| module must not be built-in. |
| |
| To build the testing executable run: |
| |
| ./configure --enable-tests |
| make check |
| |
| 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: |
| |
| sudo ./tests/gpiod-test |
| |
| 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. |
| |
| 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. |