GPIO 与执行器

开始之前

你需要准备什么

四节各自打透什么

本章术语：先说清，再往下

下面这些词会在本章反复出现。先扫一遍，知道「它是什么、为什么需要它」；读到再见到就不慌，也可以随时翻回这一页。它们不是堆砌——每引入一个词，都是因为我们到了必须说清那一步的关口。

外设与 I/O

I/O：物理世界怎么进程序

外设是 CPU 之外、用来感知或驱动外部世界的硬件模块——传感器、LED、风扇驱动等都算。I/O（Input/Output）是程序与这些硬件打交道的总称：输入把外界变成程序里的数，输出把程序里的决定变成外界动作。

同一条 GPIO 脚，配置成输出就能驱动执行器（如继电器信号端）；配置成输入就能读按键。对用户态程序来说，最终仍是「经内核接口写出一个命令」。下一节把这根脚在 Linux 里的名字（chip / line）和本板的 1.8 V 电平讲清楚——否则「写了 1 却不见动」会很难排查。

寄存器、MMIO 与用户态边界

寄存器是芯片内部一组可读写的控制位，用来配置外设、读状态、写输出。MMIO（Memory-Mapped I/O，内存映射 I/O）把这些寄存器映射到 CPU 可见的地址空间：驱动对某个地址的读写，实际落到外设控制逻辑，而不是普通 RAM。

GPIO：认识与控制

这一节把「外设」落到一根具体的脚上。读完应能回答：GPIO 是什么、Linux 怎么给脚编号、高低电平在本板上意味着什么、为什么要先申请再改电平，以及 set_value 之后如何用只读手段看见寄存器位翻转。

一根脚能做什么

GPIO（General-Purpose Input/Output，通用输入输出）是芯片上可以由软件配置方向的引脚。配置成输出时，程序决定它是高还是低，引脚电平驱动外部模块（继电器吸合、风扇转）。配置成输入时，程序读外部此刻是高还是低（按键有没有按下）。同一根物理脚，同一时刻通常只做一件事：要么输出，要么输入。

风扇、传感器模块内部可能很复杂；对 GPIO 这一层，常常仍然是「某一根脚输出高/低」或「某一根脚被拉高/拉低」。你的程序首先要管好自己的那根脚。

Linux 怎么称呼一根脚：chip 与 line

一块板子上往往有多组 GPIO 控制器。Linux 把每一组暴露成一个字符设备，名字像 /dev/gpiochip0、/dev/gpiochip1……每一个叫一个 gpiochip（芯片控制器节点，不一定等于「整颗 SoC」）。

在某一个 chip 里面，脚按编号排列，这个编号叫 line（线号 / offset）。本课默认控继电器信号脚用的是：

#define GPIO_CHIP_PATH  "/dev/gpiochip5"
#define FAN_LINE        5    /* 对应排针丝印 IO1_5；换脚只改数字 */

chip 指出哪一组控制器，line 指出这一组里的第几根。只说「GPIO3」而不说 chip，在多控制器的板上会说不清到底是哪一根。

「高」「低」在本板上是什么意思

程序里写 1 / 0（或 active / inactive），最终变成引脚上的电压：

• 高（high）：接近该脚所在电源域的电压。
• 低（low）：接近地（GND）。

许多教材默认「GPIO = 3.3 V」。荔枝派 4A 的 SoC 原生 IO 为 1.8 V。排针上的 3.3 V / 5 V 电源脚是给外设供电的；信号脚仍是 1.8 V 域。

本课继电器能直连，因为输入侧是光耦隔离：1.8 V 足以触发光耦；模块 5 V 线圈与输入信号在电气上不相通。第四章 DHT22 的数据线要 3.3 V 电平，那时再接电平转换。

经内核改电平：gpiod / libgpiod

在 Linux 用户态，日常业务经内核改芯片寄存器。你向内核请求：「使用 gpiochip5 的 line 5，配成输出，初始为低。」内核同意后，再请求设为高或低。这套用户态库和命令行工具统称 gpiod（库名常见 libgpiod，链接 -lgpiod）。

同一根脚可能被别的进程、某个内核驱动、或上次没退干净的命令占用。内核统一仲裁，才不会两个人各写各的。日常控继电器信号端走 gpiod；下面用 devmem 只读核对寄存器位，是旁路观察。

板端常见命令（本课板子多为 libgpiod 2.x）：

• gpioinfo：看某个 chip 上每根 line 的方向、占用者。
• gpioset：申请并保持某根脚为指定电平（进程活着时通常一直占着）。
• gpioget：读电平——若该脚正被别人以输出方式占用，往往会失败。

许多板上没有名叫 gpio 的万能命令。需要权限时用 sudo，或把用户加入 gpio 组（以课程环境为准）。

/* libgpiod v2 调用轮廓 */
chip = gpiod_chip_open("/dev/gpiochip5");
/* 申请 line 为输出并给出初值 → 得到 line_request */
gpiod_line_request_set_value(req, line, 1);   /* 高：继电器吸合 */
gpiod_line_request_set_value(req, line, 0);   /* 低：继电器释放 */
gpiod_line_request_release(req);

/* relay-toggle.c — 完整演示 gpiod 生命周期
 * 打开 chip → 申请 line 5 为输出(初值 0) → 拉高 → 拉低 → 释放 */
#include <gpiod.h>
#include <stdio.h>
#include <unistd.h>

int main(void) {
    /* 1. 打开 chip：IO1_5 所在控制器 */
    struct gpiod_chip *chip = gpiod_chip_open("/dev/gpiochip5");

    /* 2. 配置 line 5：输出，初值低。
     *    初值=低 很关键：不驱动 = 悬空 = 电平不定，继电器可能乱吸合 */
    struct gpiod_line_settings *st = gpiod_line_settings_new();
    gpiod_line_settings_set_direction(st, GPIOD_LINE_DIRECTION_OUTPUT);
    gpiod_line_settings_set_output_value(st, GPIOD_LINE_VALUE_INACTIVE);
    struct gpiod_line_config *cfg = gpiod_line_config_new();
    gpiod_line_config_add_line_settings(cfg, (unsigned int[]){5}, 1, st);

    /* 3. 申请（consumer="relay-toggle"，gpioinfo 里认得出） */
    struct gpiod_request_config *rcfg = gpiod_request_config_new();
    gpiod_request_config_set_consumer(rcfg, "relay-toggle");
    struct gpiod_line_request *req = gpiod_chip_request_lines(chip, rcfg, cfg);

    printf("已申请 line 5，初值低 → 风扇确定关\n");
    sleep(1);

    /* 4. 拉高：继电器吸合，风扇开 */
    gpiod_line_request_set_value(req, 5, GPIOD_LINE_VALUE_ACTIVE);
    printf("line 5 = 高 → 继电器吸合，风扇开\n");
    sleep(2);

    /* 5. 拉低 → 6. 释放（把 line 还给内核） */
    gpiod_line_request_set_value(req, 5, GPIOD_LINE_VALUE_INACTIVE);
    printf("line 5 = 低 → 继电器释放，风扇关\n");
    gpiod_line_request_release(req);
    printf("已释放 line 5\n");
    return 0;
}

$ sudo /tmp/relay-toggle
已申请 line 5，初值低 → 风扇确定关
line 5 = 高 → 继电器吸合，风扇开
line 5 = 低 → 继电器释放，风扇关
已释放 line 5

set_value 之后：只读核对寄存器位

调用 gpiod_line_request_set_value(..., 1) 之后，真正改硬件的是内核 GPIO 驱动：经系统调用接到请求，往某个 MMIO 地址写一笔，把对应引脚那一位从 0 翻成 1（或反过来）。引脚电平变了，继电器才吸合。

本课板子（RevyOS）排针 GPIO 在 gpiochip5，数据寄存器物理地址 0xffec006000；IO1_5 是 gpiochip5 的 line 5（内核全局号 gpio-651，基址 646 + 5）。寄存器地址和位是心智模型：改 0xffec006000 的第 5 位（值 0x20），就是改 IO1_5 引脚。

在荔枝派上实测（gpioset 控 IO1_5，看内核视角）：

$ sudo gpioset -c gpiochip5 5=1
$ sudo cat /sys/kernel/debug/gpio | grep gpio-651
 gpio-651 (GPIO13              |gpioset             ) out hi
#         ↑ 名字             ↑ 占用者           ↑ out hi = 引脚高

$ sudo pkill -x gpioset
$ sudo cat /sys/kernel/debug/gpio | grep gpio-651
 gpio-651 (GPIO13              )

改电平前后，out hi 出现 / 消失——「程序 → 内核 → 引脚」这条链就验证过了。对照上表：占用者列出现 gpioset，就是它申请并占住了这根 line。

独占与「Device or resource busy」

GPIO line 通常独占申请：同一时刻一个成功的请求占住这根脚，别人再申请或用另一种方式去读，就可能得到 Device or resource busy。

课堂上常见情况：用 gpioset 试验后命令一直占着；随后跑程序或 gpioget 失败。先弄清谁占着，再结束那个进程或换另一根 line。同一根脚上保持一个占用者。

在荔枝派上实测——占着 line 5 时，gpioget 读它直接失败：

$ sudo gpioget -c gpiochip5 5
gpioget: unable to request lines: Device or resource busy

$ ps aux | grep gpioset
$ sudo pkill -x gpioset   # -x：按进程名精确匹配
$ sudo cat /sys/kernel/debug/gpio

继电器、接线与跟做

这一节把 GPIO 接到真实的继电器与风扇上：信号端怎么接、用 gpioset 跟做一次、以及继电器不动时怎么排查。动手前先弄清面包板怎么连通，以及本章首次可能用到的电烙铁安全要求；完整步骤与插图见本章实验。

面包板与电烙铁（首次）

面包板：用语与商品详情一致——电源轨（「+」「−」横向连通）、连接孔（同一列纵向连通）、隔离凹槽（上下互不通）。摘录与结构图见 chapters/ch03/manuals/面包板_MB102摘录.md。把排针 5V / GND 接到电源轨后，再从轨上分线到继电器，可减少在排针上反复插拔。完整步骤与插图见本章实验。

电烙铁：本章以杜邦线插接为主；需要补焊端子或固定焊环时才使用。通电后烙铁放在架子上，勿用手试温，结束后断电冷却再收纳。安全细则与外形图见实验「电烙铁与安全」。

继电器：信号端与负载端

继电器把小信号变成大电流通路的通断：GPIO 驱动信号端（丝印 IN / X1，高电平吸合）；风扇等大电流走触点（NO / COM）。程序只写高/低，电机电流不进 SoC 脚。

跟做前：信号端三线

跳线帽拨到 H。此时即可听吸合或看工作灯；风扇电源回路放到实验再接。

跟做：用 gpioset 控一次继电器

目的：证明「chip + line → 引脚电平 → 继电器信号端」。

1. 1
   确认脚
   本课默认：gpiochip5 line 5 = 丝印 IO1_5。若镜像不同，用 sudo cat /sys/kernel/debug/gpio 与 pinmux 现查。
2. 2
   清占用
   sudo pkill -x gpioset（若有残留）。
3. 3
   拉高 / 拉低
   sudo gpioset -c gpiochip5 5=1，观察继电器；再 5=0 释放。
4. 4
   只读核对（建议）
   改电平前后各跑一次 sudo devmem 0xffec006000 32，对照第 5 位。

$ sudo gpioset -c gpiochip5 5=1
$ sudo cat /sys/kernel/debug/gpio | head -n 80
# 找到 gpiochip5 / line 5：应为 out hi
$ sudo pkill -x gpioset
# 释放（gpioset 是持线命令，进程活着就一直占着；用 Ctrl+C 或 pkill 释放）

故障排查（信号链）

继电器未动时，按软件状态 → 编号是否对应排针 → 信号端接线取证。

$ sudo cat /sys/kernel/debug/pinctrl/*/pinmux-pins
$ sudo cat /sys/kernel/debug/gpio

决策 → 执行：模拟温度怎么驱动风扇

数据流：决策 → 执行

第三章的程序用程序内部自变的模拟温度（约 24°C → 30°C 再降回）演示「决策 → 执行」：模拟温度 → 阈值判断 → 继电器 → 风扇。真传感器（DHT22）到第四章再接。

执行侧是开/关：GPIO 高/低 → 继电器 → 风扇电源通断。两档阈值形成滞回（第二章已定义：中间区间保持上一状态），温度在临界附近时风扇保持上一状态。

/* 伪代码：方向示意 */
if (模拟温度 > T_HIGH) 风扇应开;
else if (模拟温度 < T_LOW)  风扇应关;
/* 中间区间：保持上一状态 */

两个阈值的作用：高开、低关，中间区间保持——真实温控普遍如此。默认 T_HIGH=29 / T_LOW=25（与实验学生版、图 3 一致）。