You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Bartosz Golaszewski 689dd6e687 tests: iter: free non-mockup GPIO chips 5 days ago
bindings bindings: python: fix GCC8 warnings due to function pointer casting 5 days ago
include treewide: order includes alphabetically 4 months ago
lib treewide: rearrange source directories 4 months ago
man man: fix out of source build 3 months ago
tests tests: iter: free non-mockup GPIO chips 5 days ago
tools treewide: rearrange source directories 4 months ago
.gitignore gitignore: add .swp to the list of ignored extensions 3 months ago
COPYING libgpiod: relicense under LGPLv2.1 2 years ago
Doxyfile build: user SPDX license identifier 1 year ago
Makefile.am treewide: rearrange source directories 4 months ago
NEWS NEWS: updates for v1.4 1 month ago
README README: fix the kernel version required to run tests 4 months ago
TODO TODO: remove the task for factoring out of common testing code 1 month ago
autogen.sh build: user SPDX license identifier 1 year ago
configure.ac libgpiod: start v1.5 development cycle 1 month ago
libgpiod.pc.in build: add pkg-config support 1 year ago

README

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.