libgpiod Usage

2026-04-28

This document describes the recommended method for accessing GPIO from Linux user space on Quectel Pi H1, together with considerations relevant to debugging and application development.

Scope

For user-space GPIO access on Quectel Pi H1, the recommended approach is based on the Linux GPIO character device interface. For application development, interface verification, and hardware bring-up, libgpiod provides the recommended toolset and programming interface.

This approach is suitable for the following tasks:

  • identifying GPIO controllers detected by the system;
  • checking whether a GPIO line is available for general-purpose input or output;
  • reading input states or driving output levels during debugging;
  • monitoring line events;
  • providing a consistent GPIO access method for upper-layer applications.

Usage principles

When using GPIO on Quectel Pi H1, the following practices are recommended:

  • use controller and line numbers as the basic access unit instead of legacy export-based interfaces;
  • confirm that the target line is not already occupied by another system function before operating it;
  • use command-line tools for verification and development libraries for application integration;
  • confirm IO voltage levels and pin multiplexing constraints before connecting external hardware.

If a line is already reserved by a kernel driver, peripheral function, or board-level configuration, it should not be reused as a generic GPIO.

Environment setup

Install the required components according to the intended usage.

If only command-line inspection or simple control is needed, install the command-line tools:

sudo apt update
sudo apt install -y gpiod

For C development, install the development package:

sudo apt install -y libgpiod-dev

For Python-based access, install the Python bindings:

sudo apt install -y python3-libgpiod

The following commands can be used to verify availability:

apt list --installed | grep gpiod
gpiodetect

Controller identification

Before starting GPIO debugging, first confirm which GPIO controllers are currently detected by the system:

gpiodetect

Example output:

gpiochip0 [gpio0] (32 lines)
gpiochip1 [gpio1] (32 lines)
gpiochip2 [gpio2] (32 lines)
gpiochip3 [gpio3] (32 lines)
gpiochip4 [gpio4] (128 lines)

The controller numbering and line count may vary depending on the image version, kernel configuration, or hardware revision. Always use the actual output from the target device as the reference.

Line status check

Before controlling a GPIO line, it is recommended to inspect its current status to avoid conflicts with existing functions.

gpioinfo

To focus on a specific controller, filtering may be used:

gpioinfo | grep -A 180 "gpiochip4"

Typical information includes:

  • whether the current direction is input or output;
  • whether the line is active-low;
  • whether a consumer is already assigned;
  • whether a line name has been configured.

If consumer=... is shown in the output, the line is already in use by another function and should not be directly added to a new GPIO control flow.

Input reading

For input verification, use gpioget to read the current state of a line:

gpioget -c gpiochip4 77

Controller number or device path can also be used:

gpioget -c 4 77
gpioget -c /dev/gpiochip4 77

If numeric output is preferred:

gpioget -c gpiochip4 --numeric 77

The result is typically reported as active or inactive. The mapping to electrical high or low level should be interpreted together with the line properties.

Output control

For output verification or basic control, use gpioset to drive a line to the required state:

gpioset -c gpiochip4 77=1

Set the line low:

gpioset -c gpiochip4 77=0

Explicit state keywords are also supported:

gpioset -c gpiochip4 77=active
gpioset -c gpiochip4 77=inactive

To control multiple lines at the same time:

gpioset -c gpiochip4 16=1 17=0

For temporary output control, a hold period may be specified:

gpioset -c gpiochip4 -p 5s 77=1
gpioset -c gpiochip4 -p 100ms 77=1

To keep the process in the background:

gpioset -c gpiochip4 -z 77=1

The hold behavior of gpioset may differ across libgpiod versions. For applications that require stable output retention, validation should be performed against the actual software version and hardware behavior.

Event monitoring

For key detection, edge capture, or signal change observation, use gpiomon:

gpiomon -c gpiochip4 77

The monitored edge type may be limited as required:

gpiomon -c gpiochip4 -e rising 77
gpiomon -c gpiochip4 -e falling 77
gpiomon -c gpiochip4 -e both 77

Other common examples:

gpiomon -c gpiochip4 -n 10 77
gpiomon -c gpiochip4 --idle-timeout 5s 77
gpiomon -c gpiochip4 -p 10ms 77

This command is useful during hardware bring-up when checking for edge activity, bounce, or unexpected transitions.

Debugging recommendations

During GPIO bring-up on Quectel Pi H1, the following order is recommended:

  • identify the available gpiochip controllers;
  • confirm that the target line is not occupied by another function;
  • verify pin voltage levels, logic relationships, and peripheral wiring;
  • for input scenarios, confirm that the observed state matches expectations;
  • for output scenarios, use a multimeter, oscilloscope, or status indicator for confirmation;
  • for edge-driven scenarios, pay additional attention to bounce and debounce handling.

Notes

  • GPIO access should always follow the actual state reported by the running system;
  • lines already used by system functions should not be forcefully reused;
  • the same line should not be controlled by multiple processes at the same time;
  • IO voltage compatibility should be confirmed before connecting external signals;
  • if command options differ from this document, refer to the help output of the installed version on the target device.