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

Examples

Note

The following examples where creating using a Raspberry Pi 4B. The pins will be different on other board.

Detect the available gpiochips:

$ gpiodetect
gpiochip0 [pinctrl-bcm2711] (58 lines)
gpiochip1 [raspberrypi-exp-gpio] (8 lines)

Read the info for all the lines on a gpiochip:

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

$ ./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:

$ gpioget RXD1
"RXD1"=active

Read the value of a single GPIO line by chip and offset:

$ gpioget -c 0 15
"15"=active

Read the value of a single GPIO line as a numeric value:

$ gpioget --numeric RXD1
1

Read two values at the same time, set the active state of the lines to low and without quoted names:

$ gpioget --active-low --unquoted GPIO23 GPIO24
GPIO23=active GPIO24=active

Set the value of a line and hold the line until killed:

$ gpioset GPIO23=1

Set values of two lines, then daemonize and hold the lines:

$ gpioset --daemonize GPIO23=1 GPIO24=0

Set the value of a single line, hold it for 20ms, then exit:

$ gpioset --hold-period 20ms -t0 GPIO23=1

Blink an LED on GPIO22 at 1Hz:

$ gpioset -t500ms GPIO22=1

Blink an LED on GPIO22 at 1Hz with a 20% duty cycle:

$ gpioset -t200ms,800ms GPIO22=1

Set some lines interactively (requires --enable-gpioset-interactive):

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

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

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

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

$ gpiomon --num-events=1 --quiet GPIO22

Monitor multiple lines, exit after the first edge event:

$ gpiomon --quiet --num-events=1 GPIO5 GPIO6 GPIO12 GPIO17

Monitor a line for changes to info:

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

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

$ gpionotify --quiet --num-events=1 --event=requested GPIO5 GPIO6 GPIO12 GPIO17

Block until a line is released:

$ gpionotify --quiet --num-events=1 --event=released GPIO6