1.. _module-pw_digital_io_linux: 2 3.. cpp:namespace-push:: pw::digital_io 4 5=================== 6pw_digital_io_linux 7=================== 8.. pigweed-module:: 9 :name: pw_digital_io_linux 10 11``pw_digital_io_linux`` implements the :ref:`module-pw_digital_io` interface 12using the `Linux userspace gpio-cdev interface 13<https://www.kernel.org/doc/Documentation/ABI/testing/gpio-cdev>`_. 14 15.. note:: 16 17 Currently only the v1 userspace ABI is supported (https://pwbug.dev/328268007). 18 19 20------------- 21API reference 22------------- 23The following classes make up the public API: 24 25``LinuxDigitalIoChip`` 26====================== 27Represents an open handle to a GPIO *chip* (e.g. ``/dev/gpiochip0``). 28 29This can be created using an existing file descriptor 30(``LinuxDigitalIoChip(fd)``) or by opening a given path 31(``LinuxDigitalIoChip::Open(path)``). 32 33``LinuxDigitalIn`` 34================== 35Represents a single input line and implements :cpp:class:`DigitalIn`. 36 37This is acquired by calling ``chip.GetInputLine()`` with an appropriate 38``LinuxInputConfig``. 39 40``LinuxDigitalInInterrupt`` 41=========================== 42Represents a single input line configured for interrupts and implements 43:cpp:class:`DigitalInInterrupt`. 44 45This is acquired by calling ``chip.GetInterruptLine()`` with an appropriate 46``LinuxInputConfig``. 47 48``LinuxDigitalOut`` 49=================== 50Represents a single input line and implements :cpp:class:`DigitalOut`. 51 52This is acquired by calling ``chip.GetOutputLine()`` with an appropriate 53``LinuxOutputConfig``. 54 55.. warning:: 56 57 The ``Disable()`` implementation only closes the GPIO handle file 58 descriptor, relying on the underlying GPIO driver / pinctrl to restore 59 the state of the line. This may or may not be implemented depending on 60 the GPIO driver. 61 62 63------ 64Guides 65------ 66Example code to use GPIO pins: 67 68Configure an input pin and get its state 69======================================== 70 71.. literalinclude:: examples/input.cc 72 :language: cpp 73 :linenos: 74 :lines: 15- 75 76 77Configure an output pin and set its state 78========================================= 79 80.. literalinclude:: examples/output.cc 81 :language: cpp 82 :linenos: 83 :lines: 15- 84 85 86Configure an interrupt pin and handle events 87============================================ 88 89.. literalinclude:: examples/interrupt.cc 90 :language: cpp 91 :linenos: 92 :lines: 15- 93 94.. _module-pw_digital_io_linux-cli: 95 96---------------------- 97Command-Line Interface 98---------------------- 99This module also provides a tool also named ``pw_digital_io_linux`` which 100provides a basic command-line interface to the library. It provides the 101following sub-commands: 102 103``get`` 104======= 105Configure a GPIO line as an input and get its value. 106 107Usage: 108 109.. code-block:: none 110 111 get [-i] CHIP LINE 112 113Options: 114 115* ``-i``: Invert; configure as active-low. 116 117Arguments: 118 119* ``CHIP``: gpiochip path (e.g. ``/dev/gpiochip0``) 120* ``LINE``: GPIO line number (e.g. ``1``) 121 122``set`` 123======= 124Configure a GPIO line as an output and set its value. 125 126.. warning:: 127 128 After this process exits, the GPIO line could immediately return to its 129 hardware-controlled default state (depending on the GPIO driver). 130 131Usage: 132 133.. code-block:: none 134 135 set [-i] CHIP LINE VALUE 136 137Options: 138 139* ``-i``: Invert; configure as active-low. 140 141Arguments: 142 143* ``CHIP``: gpiochip path (e.g. ``/dev/gpiochip0``) 144* ``LINE``: GPIO line number (e.g. ``1``) 145* ``VALUE``: the value to set (``0`` = inactive or ``1`` = active) 146 147.. _module-pw_digital_io_linux-cli-watch: 148 149``watch`` 150========= 151Configure a GPIO line as an input and watch for interrupt events. 152 153By default, both rising and falling edges will trigger an event. 154This can be changed via the ``-t`` option. 155 156Usage: 157 158.. code-block:: none 159 160 watch [-i] [{-ta,-tb,-td}] CHIP LINE 161 162Options: 163 164* ``-i``: Invert; configure as active-low. 165* ``-t``: Trigger for an interrupt: 166 167 * ``-ta`` - activating edge 168 * ``-tb`` - both edges (default) 169 * ``-td`` - deactivating edge 170 171Arguments: 172 173* ``CHIP``: gpiochip path (e.g. ``/dev/gpiochip0``) 174* ``LINE``: GPIO line number (e.g. ``1``) 175 176.. cpp:namespace-pop:: 177