libgpiod Edge Events: How to Catch Them with gpiomon
gpiomon is the libgpiod CLI that waits for GPIO line edge events and prints them to standard output. This article assumes you already know libgpiod basics and covers only edge options, chip/offset mistakes, and how that differs from polling.
Grounded in the libgpiod v2 gpiomon man page and gpio tools examples. No board pin-map claims, prices, or reviews.
What are the gpiomon options?
One-line answer: Choose rising / falling / both with --edges (default both), then add --num-events, --debounce-period, --active-low, or --quiet as needed.
gpiomon waits for events on GPIO lines and prints them. Lines are specified by name, or by offset when --chip is provided.
| Option | Meaning |
|---|---|
-e, --edges | falling / rising / both (default both) |
-n, --num-events | Exit after N events |
-p, --debounce-period | Debounce period (ms by default; units like 10us allowed) |
-l, --active-low | Treat the line as active-low (flips rising/falling sense) |
-q, --quiet | No output (useful in scripts) |
-c, --chip | Restrict to a chip (required for offsets) |
-b, --bias | pull-up / pull-down / disabled |
-F, --format | Custom format (%E, %o, %c, …) |
--idle-timeout | Exit if no events for the period |
Official examples:
gpiomon --num-events=3 --edges=rising GPIO22
gpiomon --num-events=1 --quiet GPIO22
gpiomon --format="%e %c %o %l %S" --edges=falling -c gpiochip0 22For noisy buttons, start with --debounce-period. If the line is wired active-low, combine -l with the edge you actually care about.
How do you avoid chip/offset mistakes?
One-line answer: Prefer line names; when using offsets, always pair them with -c/--chip, and verify with gpiodetect / gpioinfo.
The man page: specify lines by name, or by offset only if the chip option is set. A chip may be identified by number, name, or path (0, gpiochip0, /dev/gpiochip0).
Practical checklist:
- List chips with
gpiodetect. - Inspect names, offsets, and consumers with
gpioinfo. - Prefer line names in
gpiomon. If a name looks numeric, consider--by-name. - For offsets, write both sides:
-c gpiochip0 22. - Use
--strictwhen duplicate names should abort.
Silkscreen “GPIO22” is not guaranteed to equal offset 22 on gpiochip0. Do not carry sysfs-era global numbering habits into the character-device model without checking the SoC and device tree.
How does that differ from polling?
One-line answer: gpiomon waits on kernel edge events; polling repeatedly samples the level with tools like gpioget.
In the tools overview, gpiomon exists to wait for edge events. With --quiet --num-events=1 it can block until one event arrives—handy for shell automation.
Edge wait (gpiomon) | Polling (gpioget loops) | |
|---|---|---|
| Trigger | Kernel line events | Periodic samples |
| CPU | Mostly sleeps while waiting | Wakes on the poll interval |
| Short pulses | Captured per edge/debounce settings | Easy to miss between samples |
| Code | One process and flags | Loop, sleep, compare |
Polling still makes sense for periodic level logging or environments where edge wait is unavailable. For “wait for rising/falling without busy-spinning,” the documented CLI path is gpiomon.
Wrap-up
Minimum edge workflow: ① confirm name/chip with gpioinfo → ② set --edges and optional --debounce-period → ③ always pass --chip with offsets. The same character-device v2 model applies when you move from CLI to the C API.