ESP32-IDF GPIO 专题

---

一、基本介绍

API 参考路径 esp-idf/components/esp_driver_gpio/include/driver/gpio.h。

ESP-IDF 由多个组件组成，组件中包含专门为 ESP 芯片编写的代码或第三方库（即第三方组件）。对于某些第三方库，ESP-IDF 提供专用的包装器和接口，以简化对第三方库的使用，或提高其与 ESP-IDF 其他功能的兼容性。某些情况下，第三方组件将直接呈现底层库的原始 API。

1、配置结构体

为确保应用程序与未来 ESP-IDF 版本的兼容性，请正确初始化配置结构体。

多数 ESP-IDF 中的初始化、配置和安装函数（通常以 ..._init()、 ..._config() 和 ..._install() 命名）都需要一个指向配置结构体的指针作为参数。例如：

const esp_timer_create_args_t my_timer_args = {
   
   
    .callback = &my_timer_callback,
    .arg = callback_arg,
    .name = "my_timer"
};
esp_timer_handle_t my_timer;
esp_err_t err = esp_timer_create(&my_timer_args, &my_timer);

初始化函数不会存储指向配置结构体的指针，因此在栈上分配结构体是安全的。

下面介绍 GPIO 的配置结构体：

typedef struct {
   
   
    uint64_t pin_bit_mask;          /*!< GPIO pin: set with bit mask, each bit maps to a GPIO */
    gpio_mode_t mode;               /*!< GPIO mode: set input/output mode                     */
    gpio_pullup_t pull_up_en;       /*!< GPIO pull-up                                         */
    gpio_pulldown_t pull_down_en;   /*!< GPIO pull-down                                       */
    gpio_int_type_t intr_type;      /*!< GPIO interrupt type                                  */
#if SOC_GPIO_SUPPORT_PIN_HYS_FILTER
    gpio_hys_ctrl_mode_t hys_ctrl_mode;       /*!< GPIO hysteresis: hysteresis filter on slope input    */
#endif
} gpio_config_t;

• pin_bit_mask：GPIO 引脚号。
  • 比如 GPIO_NUM_2，则配置为 .pin_bit_mask = (1 << GPIO_NUM_2)，
• mode：选择输入/输出模式
• pull_up_en：引脚上拉设置
• pull_down_en：引脚下拉设置
• intr_type：中断模式

有关这几个类型的定义在本文第三小节可以找到

2、常用 API

在使用 GPIO 相关的 API 时，要加上头文件：

#include "driver/gpio.h"

2.1 gpio_config

esp_err_t gpio_config(const gpio_config_t *pGPIOConfig);

• 参数
  • pGPIOConfig：GPIO 配置结构体，见第一小节
• 作用：
  • 该函数用于初始化 GPIO 的 Mode、pull-up、PullDown、IntrType，
• 返回值
  • ESP_OK 成功
  • ESP_ERR_INVALID_ARG 参数错误

2.2 gpio_reset_pin

esp_err_t gpio_reset_pin(gpio_num_t gpio_num)

• 参数：
  • gpio_num：引脚号
• 作用
  • 重置 GPIO 到默认状态（选择 GPIO 功能，启用上拉，禁用输入和输出）。
• 返回值
  • 总是返回 ESP_OK

2.3 gpio_set_intr_type

esp_err_t gpio_set_intr_type(gpio_num_t gpio_num, gpio_int_type_t intr_type)

• 参数
  • gpio_num：引脚号
  • intr_type：中断类型，见第三小节
• 作用
  • 设置 GPIO 中断类型
• 返回值
  • ESP_OK 成功
  • ESP_ERR_INVALID_ARG 参数错误

2.4 gpio_intr_enable

esp_err_t gpio_intr_enable(gpio_num_t gpio_num)

• 参数
  • gpio_num：引脚号
• 作用
  • 使能 GPIO 中断
• 返回值
  • ESP_OK 成功
  • ESP_ERR_INVALID_ARG 参数错误

2.5 gpio_intr_disable

esp_err_t gpio_intr_disable(gpio_num_t gpio_num)

• 参数
  • gpio_num：引脚号
• 作用
  • 禁用 GPIO 中断
• 返回值
  • ESP_OK 成功
  • ESP_ERR_INVALID_ARG 参数错误

2.6 gpio_set_level

esp_err_t gpio_set_level(gpio_num_t gpio_num, uint32_t level)

• 参数
  • gpio_num：引脚号
  • level：0: 低；1: 高
• 作用
  • 设置 GPIO 输出电平
• 返回值
  • ESP_OK 成功
  • ESP_ERR_INVALID_ARG 参数错误

通过启用 CONFIG_GPIO_CTRL_FUNC_IN_IRAM，此函数允许在 ISR 上下文中禁用缓存的情况下执行。

2.7 gpio_get_level

int gpio_get_level(gpio_num_t gpio_num)

• 参数
  • gpio_num：引脚号
• 作用
  • 获取 GPIO 输入电平
• 返回值
  • 0：低电平；1：高电平

如果引脚未配置为输入（或输入和输出），返回的值始终为 0。

2.8 gpio_set_direction

esp_err_t gpio_set_direction(gpio_num_t gpio_num, gpio_mode_t mode)

• 参数
  • gpio_num：引脚号
  • mode：要设置的模式，见第三小节
• 作用
  • 配置 GPIO 方向，例如仅输出，仅输入，输出和输入
• 返回值
  • ESP_OK 成功
  • ESP_ERR_INVALID_ARG 参数错误

2.9 gpio_set_pull_mode

esp_err_t gpio_set_pull_mode(gpio_num_t gpio_num, gpio_pull_mode_t pull_mode)

• 参数
  • gpio_num：引脚号
  • pull_mode：GPIO 拉高/拉低模式，见第三小节
• 作用
  • 配置 GPIO 上拉/下拉电阻
• 返回值
  • ESP_OK 成功
  • ESP_ERR_INVALID_ARG 参数错误

2.10 gpio_isr_register