# GPIO & RTC GPIO

[English]

## GPIO 汇总

ESP32-H2 芯片具有 28 个物理 GPIO 管脚（GPIO0 ~ GPIO27）。

每个管脚都可用作一个通用 IO，或连接一个内部的外设信号。通过 GPIO 交换矩阵和 IO MUX，可配置外设模块的输入信号来源于任何的 IO 管脚，并且外设模块的输出信号也可连接到任意 IO 管脚。这些模块共同组成了芯片的 IO 控制。更多详细信息，请参阅 ESP32-H2 技术参考手册 > IO MUX 和 GPIO 矩阵（GPIO、IO_MUX） [PDF]。

下表提供了各管脚的详细信息，部分 GPIO 具有特殊的使用限制，具体可参考表中的注释列。

GPIO | 模拟功能 | 注释
--- | --- | ---
GPIO0 |  |
GPIO1 | ADC1_CH0 |
GPIO2 | ADC1_CH1 | Strapping 管脚
GPIO3 | ADC1_CH2 | Strapping 管脚
GPIO4 | ADC1_CH3 |
GPIO5 | ADC1_CH4 |
GPIO6 |  |
GPIO7 |  | RTC
GPIO8 |  | Strapping 管脚，RTC
GPIO9 |  | Strapping 管脚，RTC
GPIO10 | ANA_CMPR_CH0 外部参考电压 | RTC
GPIO11 | ANA_CMPR_CH0 同相输入 | RTC
GPIO12 |  | RTC
GPIO13 |  | RTC
GPIO14 |  | RTC
GPIO15 |  | SPI0/1
GPIO16 |  | SPI0/1
GPIO17 |  | SPI0/1
GPIO18 |  | SPI0/1
GPIO19 |  | SPI0/1
GPIO20 |  | SPI0/1
GPIO21 |  | SPI0/1
GPIO22 |  |
GPIO23 |  |
GPIO24 |  |
GPIO25 |  | Strapping 管脚
GPIO26 |  | USB-JTAG
GPIO27 |  | USB-JTAG

备注

- Strapping 管脚： GPIO2、GPIO3、GPIO8、GPIO9 和 GPIO25 是 Strapping 管脚。更多信息请参考 ESP32-H2 技术规格书。

- SPI0/1: GPIO15-21 通常用于 SPI flash, 不推荐用于其他用途。

- USB-Serial-JTAG: GPIO26 和 GPIO27 默认用于 USB-Serial-JTAG。用做 GPIO 时驱动程序将禁用 USB-Serial-JTAG。

- 对于合封了 flash 的芯片型号， GPIO15–GPIO21 专门用于连接该 flash, 并未引出至芯片管脚。且 GPIO6–GPIO7 也未引出至芯片管脚，用户不可用。用户可配置使用其他剩余的 19 个 GPIO 管脚, 编号为: GPIO0–GPIO5、GPIO8–GPIO14、GPIO22–GPIO27。

- RTC：GPIO7–GPIO14 可用于将芯片从 Deep-sleep 模式中唤。请注意，虽然 GPIO7 是一个 RTC GPIO，但由于未引出，无法用于外部唤醒。其他 GPIO 仅能将芯片从 Light-sleep 模式中唤醒。更多信息请参考 唤醒源 章节。

## IO 管脚配置

IO 可以有两种使用方式：

- 作为简单的 GPIO 输入读取引脚上的电平，或作为简单的 GPIO 输出以输出所需的电平。

- 作为外设信号的输入/输出。

IDF 外设驱动内部会处理需要应用到引脚上的必要 IO 配置，以便它们可以用作外设信号的输入或输出。这意味着用户通常自己只需负责将 IO 配置为简单的输入或输出。`gpio_config()` 是一个一体化的 API，可用于配置 I/O 模式、内部上拉/下拉电阻等管脚设置。

在一些应用中，IO 管脚可以同时发挥双重作用。例如，输出 LEDC PWM 信号的 IO 也可以作为 GPIO 输入生成中断或 GPIO ETM 事件。这种双重用途的 IO 管脚在配置时需要特别注意。由于 `gpio_config()` 是一个会覆盖所有当前配置的 API ，因此必须先调用它将管脚模式设置为 `gpio_mode_t::GPIO_MODE_INPUT`，然后才能调用 LEDC 驱动 API 将输出信号连接到引脚上。作为替代方案，如果除了使管脚输入启用之外不需要其他额外配置，可以随时调用 `gpio_input_enable()` 以实现相同的目的。

## 获取 IO 管脚实时配置状态

GPIO 驱动提供了一个函数 `gpio_dump_io_configuration()` 用来输出指定管脚的实时配置状态，包括上下拉、输入输出使能、管脚映射等。例如，以下命令可用于输出 GPIO4，GPIO18 与 GPIO26 的配置状态：

    gpio_dump_io_configuration(stdout, (1ULL << 4) | (1ULL << 18) | (1ULL << 26));

其输出信息如下：

    ================IO DUMP Start================
    IO[4] -
      Pullup: 1, Pulldown: 0, DriveCap: 2
      InputEn: 1, OutputEn: 0, OpenDrain: 0
      FuncSel: 1 (GPIO)
      GPIO Matrix SigIn ID: (simple GPIO input)
      SleepSelEn: 1

    IO[18] -
      Pullup: 0, Pulldown: 0, DriveCap: 2
      InputEn: 0, OutputEn: 1, OpenDrain: 0
      FuncSel: 1 (GPIO)
      GPIO Matrix SigOut ID: 256 (simple GPIO output)
      SleepSelEn: 1

    IO[26] **RESERVED** -
      Pullup: 1, Pulldown: 0, DriveCap: 2
      InputEn: 1, OutputEn: 0, OpenDrain: 0
      FuncSel: 0 (IOMUX)
      SleepSelEn: 1

    =================IO DUMP End==================

如果你想要查看所有管脚的配置状态，可以使用命令

    gpio_dump_io_configuration(stdout, SOC_GPIO_VALID_GPIO_MASK);

如果 IO 管脚通过 GPIO 交换矩阵连接到内部外设信号，输出信息打印中的外设信号 ID 定义可以在 soc/esp32h2/include/soc/gpio_sig_map.h 头文件中查看。`**RESERVED**` 字样则表示此 IO 用于连接 SPI flash 或 PSRAM，强烈建议不要重新配置这些管脚用于其他功能。

请不要依赖技术参考手册中记录的 GPIO 默认配置状态，因为特殊用途的 GPIO 可能会在 app_main 之前被引导加载程序或应用程序启动阶段的代码更改。

## 配置 USB PHY 管脚 为普通 GPIO 管脚

要将 USB PHY 管脚配置为普通 GPIO 管脚，可使用函数 `gpio_config()`，请参考以下代码片段来进行配置。

    gpio_config_t usb_phy_conf = {
        .pin_bit_mask = (1ULL << USB_PHY_DP_PIN) | (1ULL << USB_PHY_DM_PIN),
        .mode = GPIO_MODE_INPUT_OUTPUT,
        .pull_up_en = 0,
        .pull_down_en = 0,
        .intr_type = GPIO_INTR_DISABLE,
    };
    gpio_config(&usb_phy_conf);

## GPIO 毛刺过滤器

ESP32-H2 内置硬件的过滤器可以过滤掉 GPIO 输入端口上的毛刺信号，在一定程度上避免错误触发中断或者是错把噪声当成有效的外设信号。

每个 GPIO 都可以使用独立的毛刺过滤器，该过滤器可以将那些脉冲宽度窄于 2 个采样时钟的信号剔除掉，该宽度无法配置。GPIO 对输入信号的采样时钟通常是 IO_MUX 的时钟源。在驱动中，此类过滤器称为 `管脚毛刺过滤器`。可以调用 `gpio_new_pin_glitch_filter()` 函数创建一个过滤器句柄。过滤器的相关配置保存在 `gpio_pin_glitch_filter_config_t` 结构体中。

- `gpio_pin_glitch_filter_config_t::gpio_num` 设置启用毛刺过滤器的 GPIO 编号。

ESP32-H2 提供了 8 个灵活的毛刺过滤器，被过滤信号的脉冲宽度可以由软件进行配置。此类过滤器则称为 `灵活毛刺过滤器`。每个过滤器都可以应用于任意 GPIO 输入，然而，将多个过滤器应用于同一 GPIO 上效果并不会叠加。可以调用 `gpio_new_flex_glitch_filter()` 函数来创建一个过滤器句柄。过滤器的相关配置保存在 `gpio_flex_glitch_filter_config_t` 结构体中。

- `gpio_flex_glitch_filter_config_t::gpio_num` 设置启用毛刺过滤器的 GPIO 编号。

- `gpio_flex_glitch_filter_config_t::window_width_ns` 和 `gpio_flex_glitch_filter_config_t::window_thres_ns` 是毛刺过滤器的关键参数。在:cpp:member:gpio_flex_glitch_filter_config_t::window_width_ns 时间内，任何脉冲信号，如果它的宽度小于 `gpio_flex_glitch_filter_config_t::window_thres_ns` ，那么该脉冲信号就会被滤除掉。`gpio_flex_glitch_filter_config_t::window_thres_ns` 的值不能大于 `gpio_flex_glitch_filter_config_t::window_width_ns`。

请注意，`管脚毛刺过滤器` 和 `灵活毛刺过滤器` 是各自独立的，支持为同一 GPIO 同时启用这两种过滤器。

毛刺过滤器默认关闭，可调用 `gpio_glitch_filter_enable()` 使能过滤器。如需回收这个过滤器，可以调用 `gpio_del_glitch_filter()` 函数。在回收句柄前，请确保过滤器处于关闭状态，否则需调用 `gpio_glitch_filter_disable()`。

## GPIO 迟滞过滤器

ESP32-H2 支持输入引脚的硬件迟滞，这可以减少由于输入电压在逻辑 0、1 临界值附近时采样不稳定造成的 GPIO 中断误触，尤其是当输入逻辑电平转换较慢，电平建立时间较长时。

每个引脚可以独立启用迟滞功能。默认情况下，它由 eFuse 控制，且处于关闭状态，但也可以由软件控制启用或禁用。你可以通过配置 `gpio_config_t::hys_ctrl_mode` 来选择迟滞控制模式。迟滞控制模式会和其余 GPIO 配置一起在 `gpio_config()` 中生效。

备注

当迟滞功能由 eFuse 控制时，仍然可以独立的控制每个引脚的该功能，你需要 烧断 eFuse ，以在特定 GPIO 上启用迟滞功能。

## 应用示例

- peripherals/gpio/generic_gpio 演示了如何配置 GPIO 以生成脉冲，触发中断。

## API 参考 - 普通 GPIO

### Header File

- components/esp_driver_gpio/include/driver/gpio.h

- This header file can be included with:

  >     #include "driver/gpio.h"

- This header file is a part of the API provided by the `esp_driver_gpio` component. To declare that your component depends on `esp_driver_gpio`, add the following to your CMakeLists.txt:

  >     REQUIRES esp_driver_gpio

  > or

  >     PRIV_REQUIRES esp_driver_gpio

### Functions

esp_err_t gpio_config(const gpio_config_t *pGPIOConfig)

  GPIO common configuration.

         Configure GPIO's Mode,pull-up,PullDown,IntrType

  备注

  This function always overwrite all the current IO configurations

  参数:

    pGPIOConfig -- Pointer to GPIO configure struct

  返回:

    - ESP_OK success

    - ESP_ERR_INVALID_ARG Parameter error

esp_err_t gpio_reset_pin(gpio_num_t gpio_num)

  Reset a GPIO to a certain state (select gpio function, enable pullup and disable input and output).

  参数:

    gpio_num -- GPIO number.

  返回:

    - ESP_OK Success

    - ESP_ERR_INVALID_ARG Parameter error

esp_err_t gpio_set_intr_type(gpio_num_t gpio_num, gpio_int_type_t intr_type)

  GPIO set interrupt trigger type.

  参数:

    - gpio_num -- GPIO number. If you want to set the trigger type of e.g. of GPIO16, gpio_num should be GPIO_NUM_16 (16);

    - intr_type -- Interrupt type, select from gpio_int_type_t

  返回:

    - ESP_OK Success

    - ESP_ERR_INVALID_ARG Parameter error

esp_err_t gpio_intr_enable(gpio_num_t gpio_num)

  Enable GPIO module interrupt signal.

  备注

  ESP32: Please do not use the interrupt of GPIO36 and GPIO39 when using ADC or Wi-Fi and Bluetooth with sleep mode enabled. Please refer to the comments of `adc1_get_raw`. Please refer to Section 3.11 of ESP32 ECO and Workarounds for Bugs for the description of this issue.

  参数:

    gpio_num -- GPIO number. If you want to enable an interrupt on e.g. GPIO16, gpio_num should be GPIO_NUM_16 (16);

  返回:

    - ESP_OK Success

    - ESP_ERR_INVALID_ARG Parameter error

esp_err_t gpio_intr_disable(gpio_num_t gpio_num)

  Disable GPIO module interrupt signal.

  备注

  This function is allowed to be executed when Cache is disabled within ISR context, by enabling `CONFIG_GPIO_CTRL_FUNC_IN_IRAM`

  参数:

    gpio_num -- GPIO number. If you want to disable the interrupt of e.g. GPIO16, gpio_num should be GPIO_NUM_16 (16);

  返回:

    - ESP_OK success

    - ESP_ERR_INVALID_ARG Parameter error

esp_err_t gpio_set_level(gpio_num_t gpio_num, uint32_t level)

  GPIO set output level.

  备注

  This function is allowed to be executed when Cache is disabled within ISR context, by enabling `CONFIG_GPIO_CTRL_FUNC_IN_IRAM`

  参数:

    - gpio_num -- GPIO number. If you want to set the output level of e.g. GPIO16, gpio_num should be GPIO_NUM_16 (16);

    - level -- Output level. 0: low ; 1: high

  返回:

    - ESP_OK Success

    - ESP_ERR_INVALID_ARG GPIO number error

int gpio_get_level(gpio_num_t gpio_num)

  GPIO get input level.

  警告

  If the pad is not configured for input (or input and output) the returned value is always 0.

  参数:

    gpio_num -- GPIO number. If you want to get the logic level of e.g. pin GPIO16, gpio_num should be GPIO_NUM_16 (16);

  返回:

    - 0 the GPIO input level is 0

    - 1 the GPIO input level is 1

esp_err_t gpio_set_direction(gpio_num_t gpio_num, gpio_mode_t mode)

  GPIO set direction.

  Configure GPIO mode,such as output_only,input_only,output_and_input

  备注

  This function always overwrite all the current modes that have applied on the IO pin

  参数:

    - gpio_num -- Configure GPIO pins number, it should be GPIO number. If you want to set direction of e.g. GPIO16, gpio_num should be GPIO_NUM_16 (16);

    - mode -- GPIO direction

  返回:

    - ESP_OK Success

    - ESP_ERR_INVALID_ARG GPIO error

esp_err_t gpio_input_enable(gpio_num_t gpio_num)

  Enable input for an IO.

  参数:

    gpio_num -- GPIO number

  返回:

    - ESP_OK Success

    - ESP_ERR_INVALID_ARG GPIO number error

esp_err_t gpio_set_pull_mode(gpio_num_t gpio_num, gpio_pull_mode_t pull)

  Configure GPIO internal pull-up/pull-down resistors.

  备注

  This function always overwrite the current pull-up/pull-down configurations

  备注

  ESP32: Only pins that support both input & output have integrated pull-up and pull-down resistors. Input-only GPIOs 34-39 do not.

  参数:

    - gpio_num -- GPIO number. If you want to set pull up or down mode for e.g. GPIO16, gpio_num should be GPIO_NUM_16 (16);

    - pull -- GPIO pull up/down mode.

  返回:

    - ESP_OK Success

    - ESP_ERR_INVALID_ARG : Parameter error

esp_err_t gpio_wakeup_enable(gpio_num_t gpio_num, gpio_int_type_t intr_type)

  Enable GPIO wake-up function.

  参数:

    - gpio_num -- GPIO number.

    - intr_type -- GPIO wake-up type. Only GPIO_INTR_LOW_LEVEL or GPIO_INTR_HIGH_LEVEL can be used.

  返回:

    - ESP_OK Success

    - ESP_ERR_INVALID_ARG Parameter error

esp_err_t gpio_wakeup_disable(gpio_num_t gpio_num)

  Disable GPIO wake-up function.

  参数:

    gpio_num -- GPIO number

  返回:

    - ESP_OK Success

    - ESP_ERR_INVALID_ARG Parameter error

esp_err_t gpio_isr_register(void (*fn)(void*), void *arg, int intr_alloc_flags, gpio_isr_handle_t *handle)

  Register GPIO interrupt handler, the handler is an ISR. The handler will be attached to the same CPU core that this function is running on.

  This ISR function is called whenever any GPIO interrupt occurs. See the alternative gpio_install_isr_service() and gpio_isr_handler_add() API in order to have the driver support per-GPIO ISRs.

  To disable or remove the ISR, pass the returned handle to the interrupt allocation functions.

  参数:

    - fn -- Interrupt handler function.

    - arg -- Parameter for handler function

    - intr_alloc_flags -- Flags used to allocate the interrupt. One or multiple (ORred) ESP_INTR_FLAG_* values. See esp_intr_alloc.h for more info.

    - handle -- Pointer to return handle. If non-NULL, a handle for the interrupt will be returned here.

  返回:

    - ESP_OK Success ;

    - ESP_ERR_INVALID_ARG GPIO error

    - ESP_ERR_NOT_FOUND No free interrupt found with the specified flags

esp_err_t gpio_pullup_en(gpio_num_t gpio_num)

  Enable pull-up on GPIO.

  参数:

    gpio_num -- GPIO number

  返回:

    - ESP_OK Success

    - ESP_ERR_INVALID_ARG Parameter error

esp_err_t gpio_pullup_dis(gpio_num_t gpio_num)

  Disable pull-up on GPIO.

  参数:

    gpio_num -- GPIO number

  返回:

    - ESP_OK Success

    - ESP_ERR_INVALID_ARG Parameter error

esp_err_t gpio_pulldown_en(gpio_num_t gpio_num)

  Enable pull-down on GPIO.

  参数:

    gpio_num -- GPIO number

  返回:

    - ESP_OK Success

    - ESP_ERR_INVALID_ARG Parameter error

esp_err_t gpio_pulldown_dis(gpio_num_t gpio_num)

  Disable pull-down on GPIO.

  参数:

    gpio_num -- GPIO number

  返回:

    - ESP_OK Success

    - ESP_ERR_INVALID_ARG Parameter error

esp_err_t gpio_install_isr_service(int intr_alloc_flags)

  Install the GPIO driver's ETS_GPIO_INTR_SOURCE ISR handler service, which allows per-pin GPIO interrupt handlers.

  This function is incompatible with gpio_isr_register() - if that function is used, a single global ISR is registered for all GPIO interrupts. If this function is used, the ISR service provides a global GPIO ISR and individual pin handlers are registered via the gpio_isr_handler_add() function.

  参数:

    intr_alloc_flags -- Flags used to allocate the interrupt. One or multiple (ORred) ESP_INTR_FLAG_* values. See esp_intr_alloc.h for more info.

  返回:

    - ESP_OK Success

    - ESP_ERR_NO_MEM No memory to install this service

    - ESP_ERR_INVALID_STATE ISR service already installed.

    - ESP_ERR_NOT_FOUND No free interrupt found with the specified flags

    - ESP_ERR_INVALID_ARG GPIO error

void gpio_uninstall_isr_service(void)

  Uninstall the driver's GPIO ISR service, freeing related resources.

esp_err_t gpio_isr_handler_add(gpio_num_t gpio_num, gpio_isr_t isr_handler, void *args)

  Add ISR handler for the corresponding GPIO pin.

  Call this function after using gpio_install_isr_service() to install the driver's GPIO ISR handler service.

  The pin ISR handlers no longer need to be declared with IRAM_ATTR, unless you pass the ESP_INTR_FLAG_IRAM flag when allocating the ISR in gpio_install_isr_service().

  This ISR handler will be called from an ISR. So there is a stack size limit (configurable as "ISR stack size" in menuconfig). This limit is smaller compared to a global GPIO interrupt handler due to the additional level of indirection.

  参数:

    - gpio_num -- GPIO number

    - isr_handler -- ISR handler function for the corresponding GPIO number.

    - args -- parameter for ISR handler.

  返回:

    - ESP_OK Success

    - ESP_ERR_INVALID_STATE Wrong state, the ISR service has not been initialized.

    - ESP_ERR_INVALID_ARG Parameter error

esp_err_t gpio_isr_handler_remove(gpio_num_t gpio_num)

  Remove ISR handler for the corresponding GPIO pin.

  参数:

    gpio_num -- GPIO number

  返回:

    - ESP_OK Success

    - ESP_ERR_INVALID_STATE Wrong state, the ISR service has not been initialized.

    - ESP_ERR_INVALID_ARG Parameter error

esp_err_t gpio_set_drive_capability(gpio_num_t gpio_num, gpio_drive_cap_t strength)

  Set GPIO pad drive capability.

  参数:

    - gpio_num -- GPIO number, only support output GPIOs

    - strength -- Drive capability of the pad

  返回:

    - ESP_OK Success

    - ESP_ERR_INVALID_ARG Parameter error

esp_err_t gpio_get_drive_capability(gpio_num_t gpio_num, gpio_drive_cap_t *strength)

  Get GPIO pad drive capability.

  参数:

    - gpio_num -- GPIO number, only support output GPIOs

    - strength -- Pointer to accept drive capability of the pad

  返回:

    - ESP_OK Success

    - ESP_ERR_INVALID_ARG Parameter error

esp_err_t gpio_hold_en(gpio_num_t gpio_num)

  Enable gpio pad hold function.

  When a GPIO is set to hold, its state is latched at that moment and will not change when the internal signal or the IO MUX/GPIO configuration is modified (including input enable, output enable, output value, function, and drive strength values). This function can be used to retain the state of GPIOs when the power domain of where GPIO/IOMUX belongs to becomes off. For example, chip or system is reset (e.g. watchdog time-out, Deep-sleep events are triggered), or peripheral power-down in Light-sleep.

  This function works in both input and output modes, and only applicable to output-capable GPIOs. If this function is enabled: in output mode: the output level of the GPIO will be locked and can not be changed. in input mode: the input read value can still reflect the changes of the input signal.

  Power down or call `gpio_hold_dis` will disable this function.

  Please be aware that,

  1. USB pads cannot hold at low level after waking up from Deep-sleep. The USB related registers are reset, so the USB pull-up is back.

  2. For ESP32-P4 rev < 3.0, the states of IOs can not be hold after waking up from Deep-sleep.

  3. For ESP32/S2/C3/S3/C2, this function cannot be used to hold the state of a digital GPIO during Deep-sleep. Even if this function is enabled, the digital GPIO will be reset to its default state when the chip wakes up from Deep-sleep. If you want to hold the state of a digital GPIO during Deep-sleep, please call `gpio_deep_sleep_hold_en`.

  参数:

    gpio_num -- GPIO number, only support output-capable GPIOs

  返回:

    - ESP_OK Success

    - ESP_ERR_NOT_SUPPORTED Not support pad hold function

esp_err_t gpio_hold_dis(gpio_num_t gpio_num)

  Disable gpio pad hold function.

  When the chip is woken up from peripheral power-down sleep, the gpio will be set to the default mode, so, the gpio will output the default level if this function is called. If you don't want the level changes, the gpio should be configured to a known state before this function is called. e.g. If you hold gpio18 high during Deep-sleep, after the chip is woken up and `gpio_hold_dis` is called, gpio18 will output low level(because gpio18 is input mode by default). If you don't want this behavior, you should configure gpio18 as output mode and set it to high level before calling `gpio_hold_dis`.

  参数:

    gpio_num -- GPIO number, only support output-capable GPIOs

  返回:

    - ESP_OK Success

    - ESP_ERR_NOT_SUPPORTED Not support pad hold function

void gpio_iomux_in(uint32_t gpio_num, uint32_t signal_idx)

  SOC_GPIO_SUPPORT_HOLD_SINGLE_IO_IN_DSLP.

  Set pad input to a peripheral signal through the IOMUX.

  参数:

    - gpio_num -- GPIO number of the pad.

    - signal_idx -- Peripheral signal id to input. One of the `*_IN_IDX` signals in `soc/gpio_sig_map.h`.

void gpio_iomux_out(uint8_t gpio_num, int func, bool out_en_inv)

  Set peripheral output to an GPIO pad through the IOMUX.

  参数:

    - gpio_num -- gpio_num GPIO number of the pad.

    - func -- The function number of the peripheral pin to output pin. One of the `FUNC_X_*` of specified pin (X) in `soc/io_mux_reg.h`.

    - out_en_inv -- True if the output enable needs to be inverted, otherwise False.

esp_err_t gpio_force_hold_all(void)

  Force hold all digital and rtc gpio pads.

  GPIO force hold, no matter the chip in active mode or sleep modes.

  This function will immediately cause all pads to latch the current values of input enable, output enable, output value, function, and drive strength values.

  警告

  1. This function will hold flash and UART pins as well. Therefore, this function, and all code run afterwards (till calling `gpio_force_unhold_all` to disable this feature), MUST be placed in internal RAM as holding the flash pins will halt SPI flash operation, and holding the UART pins will halt any UART logging.

  2. The hold state of all pads will be cancelled during ROM boot, so it is not recommended to use this API to hold the pads state during deepsleep and reset.

esp_err_t gpio_force_unhold_all(void)

  Unhold all digital and rtc gpio pads.

  备注

  The global hold signal and the hold signal of each IO act on the PAD through 'or' logic, so if a pad has already been configured to hold by `gpio_hold_en`, this API can't release its hold state.

esp_err_t gpio_sleep_sel_en(gpio_num_t gpio_num)

  Enable SLP_SEL to change GPIO status automantically in lightsleep.

  参数:

    gpio_num -- GPIO number of the pad.

  返回:

    - ESP_OK Success

esp_err_t gpio_sleep_sel_dis(gpio_num_t gpio_num)

  Disable SLP_SEL to change GPIO status automantically in lightsleep.

  参数:

    gpio_num -- GPIO number of the pad.

  返回:

    - ESP_OK Success

esp_err_t gpio_sleep_set_direction(gpio_num_t gpio_num, gpio_mode_t mode)

  GPIO set direction at sleep.

  Configure GPIO direction,such as output_only,input_only,output_and_input

  参数:

    - gpio_num -- Configure GPIO pins number, it should be GPIO number. If you want to set direction of e.g. GPIO16, gpio_num should be GPIO_NUM_16 (16);

    - mode -- GPIO direction

  返回:

    - ESP_OK Success

    - ESP_ERR_INVALID_ARG GPIO error

esp_err_t gpio_sleep_set_pull_mode(gpio_num_t gpio_num, gpio_pull_mode_t pull)

  Configure GPIO pull-up/pull-down resistors at sleep.

  备注

  ESP32: Only pins that support both input & output have integrated pull-up and pull-down resistors. Input-only GPIOs 34-39 do not.

  参数:

    - gpio_num -- GPIO number. If you want to set pull up or down mode for e.g. GPIO16, gpio_num should be GPIO_NUM_16 (16);

    - pull -- GPIO pull up/down mode.

  返回:

    - ESP_OK Success

    - ESP_ERR_INVALID_ARG : Parameter error

esp_err_t gpio_dump_io_configuration(FILE *out_stream, uint64_t io_bit_mask)

  Dump IO configuration information to console.

  参数:

    - out_stream -- IO stream (e.g. stdout)

    - io_bit_mask -- IO pin bit mask, each bit maps to an IO

  返回:

    - ESP_OK Success

    - ESP_ERR_INVALID_ARG Parameter error

esp_err_t gpio_get_io_config(gpio_num_t gpio_num, gpio_io_config_t *out_io_config)

  Get the configuration for an IO.

  参数:

    - gpio_num -- GPIO number

    - out_io_config -- [out] Pointer to the structure that saves the specific IO configuration

  返回:

    - ESP_OK Success

    - ESP_ERR_INVALID_ARG Parameter error

### Structures

struct gpio_config_t

  Configuration parameters of GPIO pad for gpio_config function.

  Public Members

  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

  gpio_hys_ctrl_mode_t hys_ctrl_mode

    GPIO hysteresis: hysteresis filter on slope input

### Macros

GPIO_PIN_COUNT

GPIO_IS_VALID_GPIO(gpio_num)

  Check whether it is a valid GPIO number.

GPIO_IS_VALID_OUTPUT_GPIO(gpio_num)

  Check whether it can be a valid GPIO number of output mode.

GPIO_IS_VALID_DIGITAL_IO_PAD(gpio_num)

  Check whether it can be a valid digital I/O pad.

### Type Definitions

typedef intr_handle_t gpio_isr_handle_t

typedef void (*gpio_isr_t)(void *arg)

  GPIO interrupt handler.

  Param arg:

    User registered data

### Header File

- components/hal/include/hal/gpio_types.h

- This header file can be included with:

  >     #include "hal/gpio_types.h"

### Structures

struct gpio_io_config_t

  Structure that contains the configuration of an IO.

  Public Members

  uint32_t fun_sel

    Value of IOMUX function selection

  uint32_t sig_out

    Index of the outputting peripheral signal

  gpio_drive_cap_t drv

    Value of drive strength

  bool pu

    Status of pull-up enabled or not

  bool pd

    Status of pull-down enabled or not

  bool ie

    Status of input enabled or not

  bool oe

    Status of output enabled or not

  bool oe_ctrl_by_periph

    True if use output enable signal from peripheral, otherwise False

  bool oe_inv

    Whether the output enable signal is inversed or not

  bool od

    Status of open-drain enabled or not

  bool slp_sel

    Status of pin sleep mode enabled or not

### Macros

GPIO_PIN_REG_0

GPIO_PIN_REG_1

GPIO_PIN_REG_2

GPIO_PIN_REG_3

GPIO_PIN_REG_4

GPIO_PIN_REG_5

GPIO_PIN_REG_6

GPIO_PIN_REG_7

GPIO_PIN_REG_8

GPIO_PIN_REG_9

GPIO_PIN_REG_10

GPIO_PIN_REG_11

GPIO_PIN_REG_12

GPIO_PIN_REG_13

GPIO_PIN_REG_14

GPIO_PIN_REG_15

GPIO_PIN_REG_16

GPIO_PIN_REG_17

GPIO_PIN_REG_18

GPIO_PIN_REG_19

GPIO_PIN_REG_20

GPIO_PIN_REG_21

GPIO_PIN_REG_22

GPIO_PIN_REG_23

GPIO_PIN_REG_24

GPIO_PIN_REG_25

GPIO_PIN_REG_26

GPIO_PIN_REG_27

GPIO_PIN_REG_28

GPIO_PIN_REG_29

GPIO_PIN_REG_30

GPIO_PIN_REG_31

GPIO_PIN_REG_32

GPIO_PIN_REG_33

GPIO_PIN_REG_34

GPIO_PIN_REG_35

GPIO_PIN_REG_36

GPIO_PIN_REG_37

GPIO_PIN_REG_38

GPIO_PIN_REG_39

GPIO_PIN_REG_40

GPIO_PIN_REG_41

GPIO_PIN_REG_42

GPIO_PIN_REG_43

GPIO_PIN_REG_44

GPIO_PIN_REG_45

GPIO_PIN_REG_46

GPIO_PIN_REG_47

GPIO_PIN_REG_48

GPIO_PIN_REG_49

GPIO_PIN_REG_50

GPIO_PIN_REG_51

GPIO_PIN_REG_52

GPIO_PIN_REG_53

GPIO_PIN_REG_54

### Enumerations

enum gpio_port_t

  Values:

  enumerator GPIO_PORT_0
  enumerator GPIO_PORT_MAX

enum gpio_int_type_t

  Values:

  enumerator GPIO_INTR_DISABLE

    Disable GPIO interrupt

  enumerator GPIO_INTR_POSEDGE

    GPIO interrupt type : rising edge

  enumerator GPIO_INTR_NEGEDGE

    GPIO interrupt type : falling edge

  enumerator GPIO_INTR_ANYEDGE

    GPIO interrupt type : both rising and falling edge

  enumerator GPIO_INTR_LOW_LEVEL

    GPIO interrupt type : input low level trigger

  enumerator GPIO_INTR_HIGH_LEVEL

    GPIO interrupt type : input high level trigger

  enumerator GPIO_INTR_MAX

enum gpio_mode_t

  Values:

  enumerator GPIO_MODE_DISABLE

    GPIO mode : disable input and output

  enumerator GPIO_MODE_INPUT

    GPIO mode : input only

  enumerator GPIO_MODE_OUTPUT

    GPIO mode : output only mode

  enumerator GPIO_MODE_OUTPUT_OD

    GPIO mode : output only with open-drain mode

  enumerator GPIO_MODE_INPUT_OUTPUT_OD

    GPIO mode : output and input with open-drain mode

  enumerator GPIO_MODE_INPUT_OUTPUT

    GPIO mode : output and input mode

enum gpio_pullup_t

  Values:

  enumerator GPIO_PULLUP_DISABLE

    Disable GPIO pull-up resistor

  enumerator GPIO_PULLUP_ENABLE

    Enable GPIO pull-up resistor

enum gpio_pulldown_t

  Values:

  enumerator GPIO_PULLDOWN_DISABLE

    Disable GPIO pull-down resistor

  enumerator GPIO_PULLDOWN_ENABLE

    Enable GPIO pull-down resistor

enum gpio_pull_mode_t

  Values:

  enumerator GPIO_PULLUP_ONLY

    Pad pull up

  enumerator GPIO_PULLDOWN_ONLY

    Pad pull down

  enumerator GPIO_PULLUP_PULLDOWN

    Pad pull up + pull down

  enumerator GPIO_FLOATING

    Pad floating

enum gpio_drive_cap_t

  Values:

  enumerator GPIO_DRIVE_CAP_0

    Pad drive capability: weak

  enumerator GPIO_DRIVE_CAP_1

    Pad drive capability: stronger

  enumerator GPIO_DRIVE_CAP_2

    Pad drive capability: medium

  enumerator GPIO_DRIVE_CAP_DEFAULT

    Pad drive capability: medium

  enumerator GPIO_DRIVE_CAP_3

    Pad drive capability: strongest

  enumerator GPIO_DRIVE_CAP_MAX

enum gpio_hys_ctrl_mode_t

  Available option for configuring hysteresis feature of GPIOs.

  Values:

  enumerator GPIO_HYS_CTRL_EFUSE

    Pad input hysteresis ctrl by efuse

  enumerator GPIO_HYS_SOFT_DISABLE

    Pad input hysteresis disable by software

  enumerator GPIO_HYS_SOFT_ENABLE

    Pad input hysteresis enable by software

## API 参考 - GPIO 毛刺过滤器

### Header File

- components/esp_driver_gpio/include/driver/gpio_filter.h

- This header file can be included with:

  >     #include "driver/gpio_filter.h"

- This header file is a part of the API provided by the `esp_driver_gpio` component. To declare that your component depends on `esp_driver_gpio`, add the following to your CMakeLists.txt:

  >     REQUIRES esp_driver_gpio

  > or

  >     PRIV_REQUIRES esp_driver_gpio

### Functions

esp_err_t gpio_new_pin_glitch_filter(const gpio_pin_glitch_filter_config_t *config, gpio_glitch_filter_handle_t *ret_filter)

  Create a pin glitch filter.

  备注

  Pin glitch filter parameters are fixed, pulses shorter than two sample clocks (IO-MUX's source clock) will be filtered out. It's independent with "flex" glitch filter. See also `gpio_new_flex_glitch_filter`.

  备注

  The created filter handle can later be deleted by `gpio_del_glitch_filter`.

  参数:

    - config -- [in] Glitch filter configuration

    - ret_filter -- [out] Returned glitch filter handle

  返回:

    - ESP_OK: Create a pin glitch filter successfully

    - ESP_ERR_INVALID_ARG: Create a pin glitch filter failed because of invalid arguments (e.g. wrong GPIO number)

    - ESP_ERR_NO_MEM: Create a pin glitch filter failed because of out of memory

    - ESP_FAIL: Create a pin glitch filter failed because of other error

esp_err_t gpio_new_flex_glitch_filter(const gpio_flex_glitch_filter_config_t *config, gpio_glitch_filter_handle_t *ret_filter)

  Allocate a flex glitch filter.

  备注

  "flex" means the filter parameters (window, threshold) are adjustable. It's independent with pin glitch filter. See also `gpio_new_pin_glitch_filter`.

  备注

  The created filter handle can later be deleted by `gpio_del_glitch_filter`.

  参数:

    - config -- [in] Glitch filter configuration

    - ret_filter -- [out] Returned glitch filter handle

  返回:

    - ESP_OK: Allocate a flex glitch filter successfully

    - ESP_ERR_INVALID_ARG: Allocate a flex glitch filter failed because of invalid arguments (e.g. wrong GPIO number, filter parameters out of range)

    - ESP_ERR_NO_MEM: Allocate a flex glitch filter failed because of out of memory

    - ESP_ERR_NOT_FOUND: Allocate a flex glitch filter failed because the underlying hardware resources are used up

    - ESP_FAIL: Allocate a flex glitch filter failed because of other error

esp_err_t gpio_del_glitch_filter(gpio_glitch_filter_handle_t filter)

  Delete a glitch filter.

  参数:

    filter -- [in] Glitch filter handle returned from `gpio_new_flex_glitch_filter` or `gpio_new_pin_glitch_filter`

  返回:

    - ESP_OK: Delete glitch filter successfully

    - ESP_ERR_INVALID_ARG: Delete glitch filter failed because of invalid arguments

    - ESP_ERR_INVALID_STATE: Delete glitch filter failed because the glitch filter is still in working

    - ESP_FAIL: Delete glitch filter failed because of other error

esp_err_t gpio_glitch_filter_enable(gpio_glitch_filter_handle_t filter)

  Enable a glitch filter.

  参数:

    filter -- [in] Glitch filter handle returned from `gpio_new_flex_glitch_filter` or `gpio_new_pin_glitch_filter`

  返回:

    - ESP_OK: Enable glitch filter successfully

    - ESP_ERR_INVALID_ARG: Enable glitch filter failed because of invalid arguments

    - ESP_ERR_INVALID_STATE: Enable glitch filter failed because the glitch filter is already enabled

    - ESP_FAIL: Enable glitch filter failed because of other error

esp_err_t gpio_glitch_filter_disable(gpio_glitch_filter_handle_t filter)

  Disable a glitch filter.

  参数:

    filter -- [in] Glitch filter handle returned from `gpio_new_flex_glitch_filter` or `gpio_new_pin_glitch_filter`

  返回:

    - ESP_OK: Disable glitch filter successfully

    - ESP_ERR_INVALID_ARG: Disable glitch filter failed because of invalid arguments

    - ESP_ERR_INVALID_STATE: Disable glitch filter failed because the glitch filter is not enabled yet

    - ESP_FAIL: Disable glitch filter failed because of other error

### Structures

struct gpio_pin_glitch_filter_config_t

  Configuration of GPIO pin glitch filter.

  Public Members

  glitch_filter_clock_source_t clk_src

    Clock source for the glitch filter

  gpio_num_t gpio_num

    GPIO number

struct gpio_flex_glitch_filter_config_t

  Configuration of GPIO flex glitch filter.

  Public Members

  glitch_filter_clock_source_t clk_src

    Clock source for the glitch filter

  gpio_num_t gpio_num

    GPIO number

  uint32_t window_width_ns

    Sample window width (in ns)

  uint32_t window_thres_ns

    Sample window threshold (in ns), during the `window_width_ns` sample window, any pulse whose width < window_thres_ns will be discarded.

### Type Definitions

typedef struct gpio_glitch_filter_t *gpio_glitch_filter_handle_t

  Typedef of GPIO glitch filter handle.

此文档对您有帮助吗？

- 反馈已收到，谢谢！
- 如果您有其他意见，欢迎填写乐鑫文档反馈表。

- 我们重视您的反馈。
- 您可以填写乐鑫文档反馈表告诉我们如何改进该文档。