GPIOD使用说明¶

本文档说明Quectel Pi H1在Linux用户空间中访问GPIO时的推荐方式，以及在调试和应用开发过程中需要关注的事项。

适用说明¶

Quectel Pi H1的GPIO用户态访问建议基于Linux GPIO character device接口完成。对于应用层开发、接口验证和硬件联调，推荐使用 libgpiod 提供的工具与编程接口。

该方式适用于以下工作内容：

确认系统已识别的GPIO控制器；
检查某条GPIO是否可用于普通输入输出；
在调试阶段读取输入状态或驱动输出电平；
监听线路变化事件；
为上层应用程序提供统一的GPIO访问方式。

使用原则¶

在Quectel Pi H1上使用GPIO时，建议遵循以下原则：

以控制器和线路编号作为访问对象，而不是使用旧式导出接口；
在操作前先确认目标线路未被系统功能占用；
将命令行工具用于调试验证，将开发库用于正式程序接入；
对涉及外设连接的场景，先确认硬件电平与接口复用关系。

对于已经被内核驱动、外设功能或板级配置占用的线路，不建议再作为通用GPIO进行直接控制。

环境准备¶

根据实际需求安装对应组件。

如仅需在终端中进行检查或简单控制，可安装命令行工具：

sudo apt update
sudo apt install -y gpiod

如需进行C语言开发，可安装开发包：

sudo apt install -y libgpiod-dev

如需在Python中调用GPIO接口，可安装Python绑定：

sudo apt install -y python3-libgpiod

可通过以下命令确认工具是否可用：

apt list --installed | grep gpiod
gpiodetect

控制器识别¶

在进行GPIO调试前，应先确认系统当前识别到的GPIO控制器。可执行以下命令：

gpiodetect

示例输出：

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

实际系统中控制器编号和线路数量可能随镜像版本、内核配置或硬件差异而变化，因此后续操作前应以当前设备输出结果为准。

线路状态确认¶

在控制某条GPIO之前，建议先检查该线路当前状态，避免与已有功能冲突。

gpioinfo

若需要重点查看某一控制器，可结合过滤命令使用：

gpioinfo | grep -A 180 "gpiochip4"

典型信息包括：

当前方向为输入或输出；
是否为低有效；
是否存在 consumer 标记；
是否已配置线路名称。

若输出信息中已显示 consumer=…，说明该线路已被其他模块占用。此类线路不应直接纳入新的GPIO控制逻辑。

输入读取¶

对于输入验证场景，可使用 gpioget 读取指定线路当前状态。

gpioget -c gpiochip4 77

也可使用控制器编号或设备节点路径：

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

如需输出数值形式，可使用：

gpioget -c gpiochip4 --numeric 77

读取结果通常以 active 或 inactive 表示逻辑状态，具体高低电平关系需结合线路属性判断。

输出控制¶

对于输出验证或简单控制场景，可使用 gpioset 设置指定线路的逻辑状态。

gpioset -c gpiochip4 77=1

设置为低电平：

gpioset -c gpiochip4 77=0

也可使用显式状态写法：

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

同时控制多条线路：

gpioset -c gpiochip4 16=1 17=0

在需要短时输出的场景中，可指定保持时间：

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

如需在后台保持控制状态，可使用：

gpioset -c gpiochip4 -z 77=1

gpioset 的保持行为与当前安装的 libgpiod 版本有关。对于需要稳定保持输出状态的应用，不建议仅依据单次命令结果进行判断，应结合实际硬件表现进行验证。

事件监听¶

对于按键检测、边沿捕获或输入状态变化观察，可使用 gpiomon：

gpiomon -c gpiochip4 77

可按需要限制监听类型：

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

其他常用用法示例：

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

该命令适合在硬件联调阶段确认是否存在边沿触发、抖动或异常翻转。

调试建议¶

在Quectel Pi H1上进行GPIO联调时，建议按照以下顺序开展：

先识别当前可见的 gpiochip 控制器；
再检查目标线路是否已被其他功能占用；
确认引脚电压、电平关系及外设连接方式；
输入场景优先验证读值是否符合预期；
输出场景建议结合示波器、万用表或状态指示进行确认；
涉及边沿触发时，应额外关注信号抖动和去抖处理。

注意事项¶

GPIO访问应以当前系统实际识别结果为准；
不建议抢占已由系统功能使用的线路；
同一条线路不应由多个进程同时控制；
外部信号接入前，应确认IO电压兼容性；
若命令参数与本文档描述存在差异，请以设备当前安装版本的帮助信息为准。