.. SPDX-License-Identifier: CC-BY-SA-4.0 SPDX-FileCopyrightText: 2025 Bartosz Golaszewski .. This file is part of libgpiod. GPIO tools documentation Command-line tools ================== Overview -------- The **libgpiod** project includes a suite of **command-line tools** to facilitate GPIO manipulation from console and shell scripts. There are currently six command-line tools available: * **gpiodetect**: list all gpiochips present on the system, their names, labels and number of GPIO lines * **gpioinfo**: list lines, their gpiochip, offset, name, and direction, and if in use then the consumer name and any other configured attributes, such as active state, bias, drive, edge detection and debounce period * **gpioget**: read values of specified GPIO lines * **gpioset**: set values of specified GPIO lines, holding the lines until the process is killed or otherwise exits * **gpiomon**: wait for edge events on GPIO lines, specify which edges to watch for, how many events to process before exiting, or if the events should be reported to the console * **gpionotify**: wait for changed to the info for GPIO lines, specify which changes to watch for, how many events to process before exiting, or if the events should be reported to the console Shared library -------------- A number of functions used to implement **gpio-tools** has been made available in a shared library separate from the low-level, core libgpiod API in the form of libgpiotools. .. note:: The libgpiotools library does not get nearly as much attention and care as the core libgpiod C library so your mileage may vary. .. toctree:: :maxdepth: 1 libgpiotools API documentation .. toctree:: :maxdepth: 1 :caption: Manual entries gpiodetect gpioinfo gpioget gpioset gpiomon gpionotify Examples -------- .. note:: The following examples where creating using a Raspberry Pi 4B. The pins will be different on other board. Detect the available gpiochips: .. code-block:: none $ gpiodetect gpiochip0 [pinctrl-bcm2711] (58 lines) gpiochip1 [raspberrypi-exp-gpio] (8 lines) Read the info for all the lines on a gpiochip: .. code-block:: none $ gpioinfo -c 1 gpiochip1 - 8 lines: line 0: "BT_ON" output line 1: "WL_ON" output line 2: "PWR_LED_OFF" output active-low consumer="led1" line 3: "GLOBAL_RESET" output line 4: "VDD_SD_IO_SEL" output consumer="vdd-sd-io" line 5: "CAM_GPIO" output consumer="cam1_regulator" line 6: "SD_PWR_ON" output consumer="sd_vcc_reg" line 7: "SD_OC_N" input Read the info for particular lines: .. code-block:: none $ ./gpioinfo PWR_LED_OFF STATUS_LED_G_CLK GLOBAL_RESET gpiochip0 42 "STATUS_LED_G_CLK" output consumer="led0" gpiochip1 2 "PWR_LED_OFF" output active-low consumer="led1" gpiochip1 3 "GLOBAL_RESET" output Read the value of a single GPIO line by name: .. code-block:: none $ gpioget RXD1 "RXD1"=active Read the value of a single GPIO line by chip and offset: .. code-block:: none $ gpioget -c 0 15 "15"=active Read the value of a single GPIO line as a numeric value: .. code-block:: none $ gpioget --numeric RXD1 1 Read two values at the same time, set the active state of the lines to low and without quoted names: .. code-block:: none $ gpioget --active-low --unquoted GPIO23 GPIO24 GPIO23=active GPIO24=active Set the value of a line and hold the line until killed: .. code-block:: none $ gpioset GPIO23=1 Set values of two lines, then daemonize and hold the lines: .. code-block:: none $ gpioset --daemonize GPIO23=1 GPIO24=0 Set the value of a single line, hold it for 20ms, then exit: .. code-block:: none $ gpioset --hold-period 20ms -t0 GPIO23=1 Blink an LED on GPIO22 at 1Hz: .. code-block:: none $ gpioset -t500ms GPIO22=1 Blink an LED on GPIO22 at 1Hz with a 20% duty cycle: .. code-block:: none $ gpioset -t200ms,800ms GPIO22=1 Set some lines interactively (requires ``--enable-gpioset-interactive``): .. code-block:: none $ gpioset --interactive --unquoted GPIO23=inactive GPIO24=active gpioset> get GPIO23=inactive GPIO24=active gpioset> toggle gpioset> get GPIO23=active GPIO24=inactive gpioset> set GPIO24=1 gpioset> get GPIO23=active GPIO24=active gpioset> toggle gpioset> get GPIO23=inactive GPIO24=inactive gpioset> toggle GPIO23 gpioset> get GPIO23=active GPIO24=inactive gpioset> exit Wait for three rising edge events on a single GPIO line, then exit: .. code-block:: none $ gpiomon --num-events=3 --edges=rising GPIO22 10002.907638045 rising "GPIO22" 10037.132562259 rising "GPIO22" 10047.179790748 rising "GPIO22" Wait for three edge events on a single GPIO line, with time in local time and with unquoted line name, then exit: .. code-block:: none $ gpiomon --num-events=3 --edges=both --localtime --unquoted GPIO22 2022-11-15T10:36:59.109615508 rising GPIO22 2022-11-15T10:36:59.129681898 falling GPIO22 2022-11-15T10:36:59.698971886 rising GPIO22 Wait for falling edge events with a custom output format: .. code-block:: none $ gpiomon --format="%e %c %o %l %S" --edges=falling -c gpiochip0 22 2 gpiochip0 22 GPIO22 10946.693481859 2 gpiochip0 22 GPIO22 10947.025347604 2 gpiochip0 22 GPIO22 10947.283716669 2 gpiochip0 22 GPIO22 10947.570109430 ... Block until an edge event occurs, don't print anything: .. code-block:: none $ gpiomon --num-events=1 --quiet GPIO22 Monitor multiple lines, exit after the first edge event: .. code-block:: none $ gpiomon --quiet --num-events=1 GPIO5 GPIO6 GPIO12 GPIO17 Monitor a line for changes to info: .. code-block:: none $ gpionotify GPIO23 11571.816473718 requested "GPIO23" 11571.816535124 released "GPIO23" 11572.722894029 requested "GPIO23" 11572.722932843 released "GPIO23" 11573.222998598 requested "GPIO23" ... Monitor a line for requests, reporting UTC time and unquoted line name: .. code-block:: none $ gpionotify --utc --unquoted GPIO23 2022-11-15T03:05:23.807090687Z requested GPIO23 2022-11-15T03:05:23.807151390Z released GPIO23 2022-11-15T03:05:24.784984280Z requested GPIO23 2022-11-15T03:05:24.785023873Z released GPIO23 ... Monitor multiple lines, exit after the first is requested: .. code-block:: none $ gpionotify --quiet --num-events=1 --event=requested GPIO5 GPIO6 GPIO12 GPIO17 Block until a line is released: .. code-block:: none $ gpionotify --quiet --num-events=1 --event=released GPIO6