# GPIOD使用说明

***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.***

---

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

# 适用说明

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

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

- 确认系统已识别的GPIO控制器；

- 检查某条GPIO是否可用于普通输入输出；

- 在调试阶段读取输入状态或驱动输出电平；

- 监听线路变化事件；

- 为上层应用程序提供统一的GPIO访问方式。

# 使用原则

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

- 以控制器和线路编号作为访问对象，而不是使用旧式导出接口；

- 在操作前先确认目标线路未被系统功能占用；

- 将命令行工具用于调试验证，将开发库用于正式程序接入；

- 对涉及外设连接的场景，先确认硬件电平与接口复用关系。

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

# 环境准备

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

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

```bash
sudo apt update
sudo apt install -y gpiod
```

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

```bash
sudo apt install -y libgpiod-dev
```

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

```bash
sudo apt install -y python3-libgpiod
```

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

```bash
apt list --installed | grep gpiod
gpiodetect
```

# 控制器识别

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

```bash
gpiodetect
```

示例输出：

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

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

# 线路状态确认

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

```bash
gpioinfo
```

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

```bash
gpioinfo | grep -A 180 "gpiochip4"
```

典型信息包括：

- 当前方向为输入或输出；

- 是否为低有效；

- 是否存在 *consumer* 标记；

- 是否已配置线路名称。

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

# 输入读取

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

```bash
gpioget -c gpiochip4 77
```

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

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

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

```bash
gpioget -c gpiochip4 --numeric 77
```

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

# 输出控制

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

```bash
gpioset -c gpiochip4 77=1
```

设置为低电平：

```bash
gpioset -c gpiochip4 77=0
```

也可使用显式状态写法：

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

同时控制多条线路：

```bash
gpioset -c gpiochip4 16=1 17=0
```

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

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

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

```bash
gpioset -c gpiochip4 -z 77=1
```

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

# 事件监听

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

```bash
gpiomon -c gpiochip4 77
```

可按需要限制监听类型：

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

其他常用用法示例：

```bash
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电压兼容性；

- 若命令参数与本文档描述存在差异，请以设备当前安装版本的帮助信息为准。