SOC-ESP32S3部分：8-GPIO输出LED控制

飞书文档https://x509p6c8to.feishu.cn/wiki/OSQWwh95niobqUkKyDQcVgsbnFg

这节课，我们将会以ESP32S3外设GPIO的使用为例，带大家学习如何从零开始学会ESP32外设的使用。

例如，这节课我们的需求是，需要通过GPIO控制指示灯的亮灭，也就是需要使用GPIO的输出控制功能，那如何了解GPIO的输出功能呢？

分为四步

1. 看芯片手册了解下芯片的IO
2. 查看板卡原理图，确定使用的是哪个GPIO
3. 查看GPIO官方例程，了解GPIO如何配置
4. 查看GPIO官方API文档或源码，了解API参数和如何使用

1、看芯片手册了解下芯片的IO

datasheet: 参考飞书文档

api说明书：参考飞书文档

ESP32-S3 芯片具有 45 个物理 GPIO 管脚（GPIO0 ~ GPIO21 和 GPIO26 ~ GPIO48）。每个管脚都可用作一个通用 IO，或连接一个内部外设信号。

​
Strapping（配置）管脚：GPIO0、GPIO3、GPIO45 和 GPIO46 是 Strapping 管脚。芯片启动时会通过这些管脚进入对应的工作模式，更多信息请参考 ESP32-S3 技术规格书。
SPI0/1：GPIO26 ~ GPIO32 通常用于 SPI flash 和 PSRAM，不推荐用于其他用途。当使用八线 flash 或八线 PSRAM 或同时使用两者时，GPIO33 ~ GPIO37 会连接到 SPIIO4 ~ SPIIO7 和 SPIDQS。因此，对于内嵌 ESP32-S3R8 或 ESP32-S3R8V 芯片的开发板，GPIO33 ~ GPIO37 也不推荐用于其他用途。
USB-JTAG：GPIO19 和 GPIO20 默认用于 USB-JTAG。如果将它们配置为普通 GPIO，驱动程序将禁用 USB-JTAG 功能​

2、查看板卡原理图，确定使用的是哪个GPIO

购买核心板后，板卡原理图可在-》专属答疑交流群-》群公告-》链接中获取：

我们可以打开板卡原理图，找到需要点亮的LED模块，然后确定需要控制的GPIO，从下方原理图可以看到，LED对应的GPIO为GPIO9

3、查看GPIO官方例程，了解GPIO如何配置

IDF的所有官方例程都位于esp-idf/examples在，GPIO属于外设模块，所以位于peripherals下的gpio/generic_gpio中，完整路径是esp-idf/examples/peripherals/gpio/generic_gpio

例程如何看？首先看README文件，这个文件非常非常重要，它是对应例程使用的说明书，请务必看懂每一句话，如果英文不好，可以配合翻译软件查看

esp-idf/examples/peripherals/gpio/generic_gpio/README.md

这部分描述了这个例程支持哪些芯片:
| Supported Targets | ESP32 | ESP32-C2 | ESP32-C3 | ESP32-C5 | ESP32-C6 | ESP32-C61 | ESP32-H2 | ESP32-P4 | ESP32-S2 | ESP32-S3 |
| ----------------- | ----- | -------- | -------- | -------- | -------- | --------- | -------- | -------- | -------- | -------- |# Example: GPIO
这部分描述了如果需要了解更多关于examples文件夹的例程信息，可以查看esp-idf/examples/README.md文件
(See the README.md file in the upper level 'examples' directory for more information about examples.)
这部分描述了例程的功能：
This test code shows how to configure GPIO and how to use it with interruption.## GPIO functions:
这部分描述了例程中，每个GPIO的功能配置，这里两个IO作为输出，两个IO作为输入
| GPIO                         | Direction | Configuration                                          |
| ---------------------------- | --------- | ------------------------------------------------------ |
| CONFIG_GPIO_OUTPUT_0         | output    |                                                        |
| CONFIG_GPIO_OUTPUT_1         | output    |                                                        |
| CONFIG_GPIO_INPUT_0          | input     | pulled up, interrupt from rising edge and falling edge |
| CONFIG_GPIO_INPUT_1          | input     | pulled up, interrupt from rising edge                  |## Test:
这部分描述了测试IO功能时，如何进行器件连线，例如把输出的IO连接到输入的IO上1. Connect CONFIG_GPIO_OUTPUT_0 with CONFIG_GPIO_INPUT_02. Connect CONFIG_GPIO_OUTPUT_1 with CONFIG_GPIO_INPUT_13. Generate pulses on CONFIG_GPIO_OUTPUT_0/1, that triggers interrupt on CONFIG_GPIO_INPUT_0/1**Note:** The following pin assignments are used by default, you can change them by `idf.py menuconfig` > `Example Configuration`.
这部分描述了不同芯片默认的IO选择，这里默认的是乐鑫官方的开发板的，我们可以通过menuconfig配置为自己板卡
|                        | CONFIG_GPIO_OUTPUT_0 | CONFIG_GPIO_OUTPUT_1 | CONFIG_GPIO_INPUT_0 | CONFIG_GPIO_INPUT_1 |
| ---------------------- | -------------------- | -------------------- | ------------------- | ------------------- |
| ESP32C2/ESP32H2        | 8                    | 9                    | 4                   | 5                   |
| All other chips        | 18                   | 19                   | 4                   | 5                   |## How to use example
这部分描述如何使用这个例程
Before project configuration and build, be sure to set the correct chip target using `idf.py set-target <chip_name>`.### Hardware Required
这部分描述使用这个例程时，需要的硬件，一块板卡，一根USB线，用于连接IO的杜邦线
* A development board with any Espressif SoC (e.g., ESP32-DevKitC, ESP-WROVER-KIT, etc.)
* A USB cable for Power supply and programming
* Some jumper wires to connect GPIOs.### Configure the project
这部分描述了如何配置、编译工程
### Build and FlashBuild the project and flash it to the board, then run the monitor tool to view the serial output:Run `idf.py -p PORT flash monitor` to build, flash and monitor the project.(To exit the serial monitor, type ``Ctrl-]``.)See the [Getting Started Guide](https://docs.espressif.com/projects/esp-idf/en/latest/get-started/index.html) for full steps to configure and use ESP-IDF to build projects.## Example Output
这部分描述了工程运行后，调试时日志输出内容
As you run the example, you will see the following log:```
I (317) gpio: GPIO[18]| InputEn: 0| OutputEn: 1| OpenDrain: 0| Pullup: 0| Pulldown: 0| Intr:0
I (327) gpio: GPIO[19]| InputEn: 0| OutputEn: 1| OpenDrain: 0| Pullup: 0| Pulldown: 0| Intr:0
I (337) gpio: GPIO[4]| InputEn: 1| OutputEn: 0| OpenDrain: 0| Pullup: 1| Pulldown: 0| Intr:1
I (347) gpio: GPIO[5]| InputEn: 1| OutputEn: 0| OpenDrain: 0| Pullup: 1| Pulldown: 0| Intr:1
Minimum free heap size: 289892 bytes
cnt: 0
cnt: 1
GPIO[4] intr, val: 1
GPIO[5] intr, val: 1
cnt: 2
GPIO[4] intr, val: 0
cnt: 3
GPIO[4] intr, val: 1
GPIO[5] intr, val: 1
cnt: 4
GPIO[4] intr, val: 0
cnt: 5
GPIO[4] intr, val: 1
GPIO[5] intr, val: 1
cnt: 6
GPIO[4] intr, val: 0
cnt: 7
GPIO[4] intr, val: 1
GPIO[5] intr, val: 1
cnt: 8
GPIO[4] intr, val: 0
cnt: 9
GPIO[4] intr, val: 1
GPIO[5] intr, val: 1
cnt: 10
...
```## Troubleshooting
这部分描述了如果遇到问题时，你可以到论坛上发帖求助
For any technical queries, please open an [issue](https://github.com/espressif/esp-idf/issues) on GitHub. We will get back to you soon.

如果你看不懂，直接把文档拷贝给AI工具，让它总结下，最终你会得到类似如下的内容：

这是一个关于 ESP-IDF 框架下 GPIO 示例的文档，介绍了该示例代码的功能、使用方法、硬件要求、配置步骤、运行输出及故障处理等内容，总结如下：

支持的芯片

支持 ESP32、ESP32 - C2、ESP32 - C3 等多种 Espressif 芯片。

示例功能

此测试代码展示了如何配置 GPIO 以及如何使用 GPIO 中断，具体 GPIO 配置如下：

测试步骤

1. 连接 CONFIG_GPIO_OUTPUT_0 与 CONFIG_GPIO_INPUT_0。
2. 连接 CONFIG_GPIO_OUTPUT_1 与 CONFIG_GPIO_INPUT_1。
3. 在 CONFIG_GPIO_OUTPUT_0/1 上产生脉冲，触发 CONFIG_GPIO_INPUT_0/1 的中断。

默认引脚分配

使用方法

1. 设置芯片目标：在项目配置和构建前，使用 idf.py set - target <chip_name> 设置正确的芯片目标。
2. 硬件要求：需要开发板、USB 线和跳线。
3. 配置项目：可通过 idf.py menuconfig > Example Configuration 修改引脚配置。
4. 构建和烧录：运行 idf.py -p PORT flash monitor 构建、烧录项目并监控串口输出。

示例输出

运行示例时，会输出 GPIO 配置信息、最小空闲堆大小，以及中断触发信息和计数器值。

故障处理

若有技术问题，可在 GitHub 上提交 issue。

同理，对于前面说到的esp-idf/examples/README.md文件说明，我们也可以总结下

​
该文档主要介绍了 ESP-IDF 项目中的示例，涵盖示例布局、使用方法、测试脚本、复制示例、进一步开发以及贡献示例等方面，具体内容如下：示例布局：
示例按类别分组在子目录中，包括蓝牙（不同协议和主机栈）、构建系统、C++ 语言应用、以太网、入门示例等多个类别，此外 commmon_components 目录包含多个示例共享的代码。
bluetooth/bluedroid：使用默认 Bluedroid 主机栈的经典蓝牙（BT）、低功耗蓝牙（BLE）以及共存示例。
bluetooth/nimble：使用 NimBLE 主机栈的低功耗蓝牙示例。
bluetooth/esp_ble_mesh：ESP 低功耗蓝牙 Mesh 示例。
bluetooth/hci：HCI 传输（VHCI 和 HCI UART）示例。
build_system：构建系统特性的示例。
cxx：C++ 语言应用示例以及实验性组件。
ethernet：以太网网络示例。
get-started：功能极简的简单示例，是初学者的良好起点。
ieee802154：IEEE802.15.4 示例。
mesh：Wi-Fi Mesh 示例。
network：与一般网络环境、测试和分析相关的示例。
openthread：OpenThread 示例。
peripherals：展示 ESP32 板载各种外设驱动功能的示例。
protocols：展示网络协议交互的示例。
provisioning：Wi-Fi 配置示例。
security：关于安全特性的示例。
storage：展示使用 SPI 闪存、SD/MMC 接口等外部存储以及闪存分区进行数据存储方法的示例。
system：演示芯片内部一些特性，或调试与开发工具的示例。
wifi：高级 Wi-Fi 特性示例（网络协议示例请查看protocols目录）。
Zigbee：Zigbee 网络和设备示例。使用示例：
设置芯片目标：
确保目标芯片受 ESP-IDF 版本和示例支持，使用 idf.py --list-targets 查看支持的目标，在示例项目目录中通过 idf.py set-target <target> 设置目标芯片。配置项目：
通过 Project Configuration 了解 Kconfig 选项，使用 idf.py menuconfig 检查或修改 Kconfig 选项。构建和烧录：
使用 idf.py build flash monitor 或 idf.py flash monitor 构建项目、烧录到开发板并通过串口监视器查看输出，若失败可检查串口监视器日志，使用 Ctrl + ] 退出串口监视器。运行测试 Python 脚本（pytest）：
部分示例有 pytest_....py 脚本，使用 pytest 作为测试框架，详细信息参考 ESP-IDF tests in Pytest documentation 中 “Run the Tests Locally” 部分，推荐使用 pytest 编写新测试。复制示例：
每个示例是独立项目，不一定要在 esp-idf 目录内，可复制到任意位置，IDF_PATH 环境变量将示例与 ESP-IDF 其他部分连接，若需更基础项目可尝试 esp-idf-template。进一步开发：
项目管理：
参考 IDF Frontend 文档、ESP-IDF 入门视频、示例项目 Overview 以及 Build System 文档。编写代码：
按照 API references 编写代码。贡献示例：
若有新示例可通过提交拉取请求发送给官方，在 ESP-IDF 文档中 “Creating Examples” page 介绍了创建高质量示例的步骤。​

我们了解的例程的功能后，就可以结合API手册看例程的源码了。

4、查看GPIO官方API文档，了解API参数和如何使用

GPIO例程的源码文件在esp-idf/examples/peripherals/gpio/generic_gpio/main/gpio_example_main.c中，IO口的选择通过Kconfig进行配置esp-idf/examples/peripherals/gpio/generic_gpio/main/Kconfig.projbuild

这里的例程源码包括了GPIO的输出和输入、中断部分的配置，我们可以只关注输出部分即可，我们忽略无关内容，得到以下代码。

#include <stdio.h>
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "driver/gpio.h"#define LED_GPIO_IO    9
#define LED_GPIO_PIN_SEL    (1ULL<<LED_GPIO_IO)void app_main(void)
{gpio_config_t io_conf = {};io_conf.pin_bit_mask = LED_GPIO_PIN_SEL;io_conf.mode = GPIO_MODE_OUTPUT;io_conf.pull_down_en = GPIO_PULLUP_DISABLE;io_conf.pull_up_en = GPIO_PULLUP_DISABLE;io_conf.intr_type = GPIO_INTR_DISABLE;gpio_config(&io_conf);int cnt = 0;while (1) {printf("cnt: %d\n", cnt++);gpio_set_level(LED_GPIO_IO, 1);vTaskDelay(1000 / portTICK_PERIOD_MS);gpio_set_level(LED_GPIO_IO, 0);vTaskDelay(1000 / portTICK_PERIOD_MS);}
}

这里面和GPIO相关的就是两个函数gpio_config、gpio_set_level，我们结合官方API文档https://docs.espressif.com/projects/esp-idf/zh_CN/v5.4/esp32s3/api-reference/peripherals/gpio.html了解每个函数和参数的含义：

头文件
#include "driver/gpio.h"esp_err_t gpio_config(const gpio_config_t *pGPIOConfig)
功能: gpio_config 函数用于配置一个或多个 GPIO 引脚。通过传递一个 gpio_config_t 结构体，可以设置引脚的模式、上拉/下拉电阻、中断类型等属性。pGPIOConfig参数说明
typedef struct {uint64_t pin_bit_mask;  // 要配置的 GPIO 引脚的位掩码gpio_mode_t mode;       // GPIO 引脚的工作模式gpio_pullup_t pull_up_en; // 是否启用上拉电阻gpio_pulldown_t pull_down_en; // 是否启用下拉电阻gpio_int_type_t intr_type; // 中断触发类型
} gpio_config_t;pin_bit_mask:
一个64位的掩码，用于指定要配置的引脚。每个位对应一个 GPIO 引脚，例如，若要配置 GPIO 2 和 GPIO 3，则可以设置为 (1ULL << 2) | (1ULL << 3)。
/** Let's say, GPIO_INPUT_IO_0=2, GPIO_INPUT_IO_1=3* In binary representation,* 1ULL<<GPIO_INPUT_IO_0 is equal to 0000000000000000000000000000000000000100 and* 1ULL<<GPIO_INPUT_IO_1 is equal to 0000000000000000000000000000000000001000* GPIO_INPUT_PIN_SEL                0000000000000000000000000000000000001100* */mode: 引脚的工作模式，可以是以下值之一：
GPIO_MODE_DISABLE: 禁用引脚。
GPIO_MODE_INPUT: 输入模式。
GPIO_MODE_OUTPUT: 输出模式。
GPIO_MODE_OUTPUT_OD: 开漏输出模式。
GPIO_MODE_INPUT_OUTPUT_OD: 开漏输入输出模式。
GPIO_MODE_INPUT_OUTPUT: 输入输出模式。pull_up_en: 上拉电阻使能，可以是以下值之一：
GPIO_PULLUP_DISABLE: 禁用上拉电阻。
GPIO_PULLUP_ENABLE: 启用上拉电阻。pull_down_en: 下拉电阻使能，可以是以下值之一：
GPIO_PULLDOWN_DISABLE: 禁用下拉电阻。
GPIO_PULLDOWN_ENABLE: 启用下拉电阻。intr_type: 中断类型，可以是以下值之一：
GPIO_INTR_DISABLE: 禁用中断。
GPIO_INTR_POSEDGE: 上升沿触发中断。
GPIO_INTR_NEGEDGE: 下降沿触发中断。
GPIO_INTR_ANYEDGE: 任意边沿触发中断。
GPIO_INTR_LOW_LEVEL: 低电平触发中断。
GPIO_INTR_HIGH_LEVEL: 高电平触发中断。esp_err_t gpio_set_level(gpio_num_t gpio_num, uint32_t level);
功能: gpio_set_level 函数用于设置指定 GPIO 引脚的电平。该函数适用于配置为输出模式的 GPIO 引脚。
参数:
gpio_num: 要设置电平的 GPIO 引脚编号。
level: 要设置的电平值，可以是 0（低电平）或 1（高电平）

所以最终程序如下：

#include <stdio.h>
// 包含 FreeRTOS 操作系统的核心头文件，FreeRTOS 是一个开源的实时操作系统内核，用于任务管理、调度等
#include "freertos/FreeRTOS.h"
// 包含 FreeRTOS 任务相关的头文件，提供了任务创建、删除、延时等功能的接口
#include "freertos/task.h"
// 包含 ESP32 芯片 GPIO（通用输入输出）驱动的头文件，用于对 GPIO 引脚进行配置和操作
#include "driver/gpio.h"// 定义一个宏 LED_GPIO_IO，其值为 9，表示要使用的 GPIO 引脚编号为 9
#define LED_GPIO_IO    9
// 定义一个宏 LED_GPIO_PIN_SEL，通过位运算（将 1 左移 LED_GPIO_IO 位）生成一个用于选择特定 GPIO 引脚的掩码
#define LED_GPIO_PIN_SEL  (1ULL<<LED_GPIO_IO)// 主应用程序入口函数，程序从这里开始执行
void app_main(void)
{// 定义一个 gpio_config_t 类型的结构体变量 io_conf，用于配置 GPIO 引脚的相关参数// 初始化为空结构体，确保所有成员都被初始化为 0gpio_config_t io_conf = {};// 设置 GPIO 引脚的中断类型为禁用，即不使用该引脚的中断功能io_conf.intr_type = GPIO_INTR_DISABLE;// 将 GPIO 引脚的工作模式设置为输出模式，意味着该引脚可以输出高低电平io_conf.mode = GPIO_MODE_OUTPUT;// 使用之前定义的掩码 LED_GPIO_PIN_SEL 来指定要配置的 GPIO 引脚，这里就是 GPIO 9io_conf.pin_bit_mask = LED_GPIO_PIN_SEL;// 禁用 GPIO 引脚的下拉电阻，下拉电阻用于将引脚电平拉低io_conf.pull_down_en = GPIO_PULLUP_DISABLE;// 禁用 GPIO 引脚的上拉电阻，上拉电阻用于将引脚电平拉高io_conf.pull_up_en = GPIO_PULLUP_DISABLE;// 调用 gpio_config 函数，将上述配置应用到指定的 GPIO 引脚gpio_config(&io_conf);// 定义一个整型变量 cnt 并初始化为 0，用于计数int cnt = 0;while (1) {// 打印当前的计数值，并将 cnt 的值加 1printf("cnt: %d\n", cnt++);// 调用 gpio_set_level 函数，设置 GPIO 9 引脚的输出电平gpio_set_level(LED_GPIO_IO, 1);// 调用 FreeRTOS 的 vTaskDelay 函数，使当前任务延时 1000 个时钟节拍 portTICK_PERIOD_MS 表示每个时钟节拍对应的毫秒数，这里实现了 1 秒的延时vTaskDelay(1000 / portTICK_PERIOD_MS);gpio_set_level(LED_GPIO_IO, 0);vTaskDelay(1000 / portTICK_PERIOD_MS);}
}

然后我们需要把板卡接到底板上，因为LED是在底板上的。

//设置“目标”芯片。
idf.py set-target esp32s3 
//编译，首次编译一般需要几分钟
idf.py build
//烧录
idf.py -p COM19 flash monitor

烧录完成后，我们就可以看到LED亮1s，灭1s