简体中文

English

简体中文

English

外观

​

前置条件 ​

条件说明
系统Debian12 或 Ubuntu24
Python 绑定sudo apt install python3-libgpiod
演示引脚Pin 31（GPIO2_B0 = gpiochip2 line 8）

快速验证 ​

bash
python3 -c "import gpiod; print(gpiod.__version__)"

正常输出版本号即可。如果报 ModuleNotFoundError：

bash
sudo apt install python3-libgpiod

不要用 pip 安装

pip install gpiod 安装的是 v2 版本，与系统的 libgpiod v1 不兼容。请使用 apt 安装 python3-libgpiod。

API 概览 ​

text
gpiod.Chip('gpiochipN')       →  打开控制器
    ↓
chip.get_line(offset)         →  获取单条线
chip.get_lines([...])         →  获取多条线
    ↓
line.request(...)             →  申请使用（指定方向/事件类型）
    ↓
line.get_value()              →  读取
line.set_value(val)           →  写入
line.event_wait() / event_read()  →  事件监听
    ↓
line.release()                →  释放线
chip.close()                  →  关闭控制器

request 参数速查

type 参数说明
gpiod.LINE_REQ_DIR_IN输入
gpiod.LINE_REQ_DIR_OUT输出
gpiod.LINE_REQ_EV_RISING_EDGE监听上升沿
gpiod.LINE_REQ_EV_FALLING_EDGE监听下降沿
gpiod.LINE_REQ_EV_BOTH_EDGES监听双边沿
flags 参数说明
gpiod.LINE_REQ_FLAG_BIAS_PULL_UP内部上拉
gpiod.LINE_REQ_FLAG_BIAS_PULL_DOWN内部下拉
gpiod.LINE_REQ_FLAG_OPEN_DRAIN开漏输出

输出控制（点灯） ​

创建文件 gpio_output.py：

python
#!/usr/bin/env python3
import gpiod
import time

chip = gpiod.Chip("gpiochip2")
line = chip.get_line(8)  # GPIO2_B0 = Pin 31

# 申请为输出，初始电平为 0
line.request(consumer="gpio-output-demo", type=gpiod.LINE_REQ_DIR_OUT, default_val=0)

print("开始闪烁 Pin 31 (GPIO2_B0)...")
try:
    for i in range(5):
        line.set_value(1)
        print("  HIGH")
        time.sleep(0.5)

        line.set_value(0)
        print("  LOW")
        time.sleep(0.5)
finally:
    line.release()
    chip.close()

print("完成")

运行：

bash
sudo python3 gpio_output.py
运行输出
text
开始闪烁 Pin 31 (GPIO2_B0)...
  HIGH
  LOW
  HIGH
  LOW
  HIGH
  LOW
  HIGH
  LOW
  HIGH
  LOW
完成

如果 Pin 31 外接了 LED（串联 330Ω 限流电阻到 GND），可以看到 LED 闪烁。

输入读取 ​

创建文件 gpio_input.py：

python
#!/usr/bin/env python3
import gpiod
import time

chip = gpiod.Chip("gpiochip2")
line = chip.get_line(8)  # GPIO2_B0 = Pin 31

# 申请为输入，启用内部上拉
line.request(
    consumer="gpio-input-demo",
    type=gpiod.LINE_REQ_DIR_IN,
    flags=gpiod.LINE_REQ_FLAG_BIAS_PULL_UP,
)

print("读取 Pin 31 (GPIO2_B0) 电平，共 10 次...")
try:
    for i in range(10):
        val = line.get_value()
        level = "HIGH" if val else "LOW"
        print(f"  [{i+1}] 电平: {level}")
        time.sleep(1)
finally:
    line.release()
    chip.close()

运行：

bash
sudo python3 gpio_input.py

配置了内部上拉，引脚悬空时读到 HIGH，接 GND 后读到 LOW。

边沿事件检测（中断） ​

创建文件 gpio_event.py：

python
#!/usr/bin/env python3
import gpiod

chip = gpiod.Chip("gpiochip2")
line = chip.get_line(8)  # GPIO2_B0 = Pin 31

# 申请双边沿事件监听，启用内部上拉
line.request(
    consumer="gpio-event-demo",
    type=gpiod.LINE_REQ_EV_BOTH_EDGES,
    flags=gpiod.LINE_REQ_FLAG_BIAS_PULL_UP,
)

print("等待 Pin 31 (GPIO2_B0) 边沿事件，按 Ctrl+C 退出...")
try:
    while True:
        # 等待事件，超时 5 秒
        if line.event_wait(sec=5):
            event = line.event_read()
            edge = "RISING " if event.type == gpiod.LineEvent.RISING_EDGE else "FALLING"
            print(f"  {edge} @ {event.sec}.{event.nsec:09d}")
        else:
            print("  超时，继续等待...")
except KeyboardInterrupt:
    print("\n退出")
finally:
    line.release()
    chip.close()

运行：

bash
sudo python3 gpio_event.py

将 Pin 31 接 GND 再松开，终端会打印边沿事件和时间戳。

同时操作多条线 ​

创建文件 gpio_multi.py：

python
#!/usr/bin/env python3
import gpiod
import time

chip = gpiod.Chip("gpiochip2")

# 批量获取：Pin 31 (line 8) 和 Pin 29 (line 16)
lines = chip.get_lines([8, 16])

# 批量申请为输出
lines.request(consumer="gpio-multi-demo", type=gpiod.LINE_REQ_DIR_OUT, default_vals=[0, 0])

print("交替闪烁 Pin 31 和 Pin 29...")
try:
    for i in range(10):
        if i % 2 == 0:
            lines.set_values([1, 0])
        else:
            lines.set_values([0, 1])
        time.sleep(0.3)
finally:
    lines.release()
    chip.close()

print("完成")

运行：

bash
sudo python3 gpio_multi.py

常见问题 ​

Permission denied

GPIO 操作需要 root 权限：

bash
sudo python3 your_script.py

或者将用户加入 gpio 组（需重新登录）：

bash
sudo usermod -aG gpio $USER

ModuleNotFoundError: No module named 'gpiod'

bash
sudo apt install python3-libgpiod

注意包名是 python3-libgpiod，不是 python3-gpiod。

Device or resource busy

引脚被其他程序或内核驱动占用。排查：

bash
gpioinfo gpiochip2 | grep "line   8"

如果显示 [used]，需要先停止占用该引脚的程序，或在设备树中禁用对应外设。

event_wait 一直超时？

确认硬件接线正确。可以先用命令行工具验证：

bash
sudo gpiomon gpiochip2 8

如果命令行工具也收不到事件，说明是硬件问题（接线松动、引脚被占用等）。

参考资料 ​

本页面更新于: