pw_digital_io_linux#
Digital I/O interface for Linux userspace
Unstable C++17
pw_digital_io_linux
implements the pw_digital_io interface
using the Linux userspace gpio-cdev interface.
Note
Currently only the v1 userspace ABI is supported (https://pwbug.dev/328268007).
API reference#
The following classes make up the public API:
LinuxDigitalIoChip
#
Represents an open handle to a GPIO chip (e.g. /dev/gpiochip0
).
This can be created using an existing file descriptor
(LinuxDigitalIoChip(fd)
) or by opening a given path
(LinuxDigitalIoChip::Open(path)
).
LinuxDigitalIn
#
Represents a single input line and implements DigitalIn
.
This is acquired by calling chip.GetInputLine()
with an appropriate
LinuxInputConfig
.
LinuxDigitalOut
#
Represents a single input line and implements DigitalOut
.
This is acquired by calling chip.GetOutputLine()
with an appropriate
LinuxOutputConfig
.
Warning
The Disable()
implementation only closes the GPIO handle file
descriptor, relying on the underlying GPIO driver / pinctrl to restore
the state of the line. This may or may not be implemented depending on
the GPIO driver.
Guides#
Example code to use GPIO pins:
Configure an input pin and get its state#
#include "pw_digital_io_linux/digital_io.h"
#include "pw_status/try.h"
using pw::digital_io::LinuxDigitalIoChip;
pw::Status InputExample() {
// Open handle to chip.
PW_TRY_ASSIGN(auto chip, LinuxDigitalIoChip::Open("/dev/gpiochip0"));
// Configure input line.
LinuxInputConfig config(
/* index= */ 5,
/* polarity= */ Polarity::kActiveHigh);
PW_TRY_ASSIGN(auto input, chip.GetInputLine(config));
PW_TRY(input.Enable());
// Get the input pin state.
PW_TRY_ASSIGN(auto pin_state, input.GetState());
return pw::OkStatus();
}
Configure an output pin and set its state#
#include "pw_digital_io/polarity.h"
#include "pw_digital_io_linux/digital_io.h"
#include "pw_status/try.h"
using pw::digital_io::LinuxDigitalIoChip;
using pw::digital_io::LinuxOutputConfig;
using pw::digital_io::Polarity;
using pw::digital_io::State;
pw::Status OutputExample() {
// Open handle to chip.
PW_TRY_ASSIGN(auto chip, LinuxDigitalIoChip::Open("/dev/gpiochip0"));
// Configure output line.
// Set the polarity to active-low and default state to active.
LinuxOutputConfig config(
/* index= */ 4,
/* polarity= */ Polarity::kActiveLow,
/* default_state= */ State::kActive);
PW_TRY_ASSIGN(auto output, chip->GetOutputLine(config));
// Enable the output pin. This pulls the pin to ground since the
// polarity is kActiveLow and the default_state is kActive.
PW_TRY(output.Enable());
// Set the output pin to inactive.
// This pulls pin to Vdd since the polarity is kActiveLow.
PW_TRY(out.SetState(State::kInactive));
return pw::OkStatus();
}
Command-Line Interface#
This module also provides a tool also named pw_digital_io_linux
which
provides a basic command-line interface to the library. It provides the
following sub-commands:
get
#
Configure a GPIO line as an input and get its value.
Usage:
get [-i] CHIP LINE
Options:
-i
: Invert; configure as active-low.
Arguments:
CHIP
: gpiochip path (e.g./dev/gpiochip0
)LINE
: GPIO line number (e.g.1
)
set
#
Configure a GPIO line as an output and set its value.
Warning
After this process exits, the GPIO line could immediately return to its hardware-controlled default state (depending on the GPIO driver).
Usage:
set [-i] CHIP LINE VALUE
Options:
-i
: Invert; configure as active-low.
Arguments:
CHIP
: gpiochip path (e.g./dev/gpiochip0
)LINE
: GPIO line number (e.g.1
)VALUE
: the value to set (0
= inactive or1
= active)