.. _module-pw_digital_io_linux:

.. cpp:namespace-push:: pw::digital_io

===================
pw_digital_io_linux
===================
.. pigweed-module::
   :name: pw_digital_io_linux

``pw_digital_io_linux`` implements the :ref:`module-pw_digital_io` interface
using the `Linux userspace gpio-cdev interface
<https://www.kernel.org/doc/Documentation/ABI/testing/gpio-cdev>`_.

.. 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 :cpp:class:`DigitalIn`.

This is acquired by calling ``chip.GetInputLine()`` with an appropriate
``LinuxInputConfig``.

``LinuxDigitalOut``
===================
Represents a single input line and implements :cpp:class:`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
========================================

.. code-block:: cpp

   #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
=========================================

.. code-block:: cpp

   #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:

.. code-block:: none

   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:

.. code-block:: none

   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)

.. cpp:namespace-pop::