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 95---------------------- 96Command-Line Interface 97---------------------- 98This module also provides a tool also named ``pw_digital_io_linux`` which 99provides a basic command-line interface to the library. It provides the 100following sub-commands: 101 102``get`` 103======= 104Configure a GPIO line as an input and get its value. 105 106Usage: 107 108.. code-block:: none 109 110 get [-i] CHIP LINE 111 112Options: 113 114* ``-i``: Invert; configure as active-low. 115 116Arguments: 117 118* ``CHIP``: gpiochip path (e.g. ``/dev/gpiochip0``) 119* ``LINE``: GPIO line number (e.g. ``1``) 120 121``set`` 122======= 123Configure a GPIO line as an output and set its value. 124 125.. warning:: 126 127 After this process exits, the GPIO line could immediately return to its 128 hardware-controlled default state (depending on the GPIO driver). 129 130Usage: 131 132.. code-block:: none 133 134 set [-i] CHIP LINE VALUE 135 136Options: 137 138* ``-i``: Invert; configure as active-low. 139 140Arguments: 141 142* ``CHIP``: gpiochip path (e.g. ``/dev/gpiochip0``) 143* ``LINE``: GPIO line number (e.g. ``1``) 144* ``VALUE``: the value to set (``0`` = inactive or ``1`` = active) 145 146``watch`` 147========= 148Configure a GPIO line as an input and watch for interrupt evnts. 149 150By default, both rising and falling edges will trigger an event. 151This can be changed via the ``-t`` option. 152 153Usage: 154 155.. code-block:: none 156 157 watch [-i] [{-ta,-tb,-td}] CHIP LINE 158 159Options: 160 161* ``-i``: Invert; configure as active-low. 162* ``-t``: Trigger for an interrupt: 163 164 * ``-ta`` - activating edge 165 * ``-tb`` - both edges (default) 166 * ``-td`` - deactivating edge 167 168Arguments: 169 170* ``CHIP``: gpiochip path (e.g. ``/dev/gpiochip0``) 171* ``LINE``: GPIO line number (e.g. ``1``) 172 173.. cpp:namespace-pop:: 174