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 or 1 = active)