# 外设驱动

[English]

## 公共变化

### 旧版驱动依赖移除

旧版驱动组件 driver 已被弃用，不再包含对以下驱动组件的公共依赖：

- esp_driver_ana_cmpr

- esp_driver_dac

- esp_driver_gptimer

- esp_driver_i2s

- esp_driver_ledc

- esp_driver_mcpwm

- esp_driver_parlio

- esp_driver_pcnt

- esp_driver_rmt

- esp_driver_sdio

- esp_driver_sdm

- esp_driver_sdmmc

- esp_driver_sdspi

- esp_driver_spi

- esp_driver_tsens

- esp_driver_twai

- esp_driver_uart

- esp_driver_usb_serial_jtag

如果您的项目使用了老旧的 driver 驱动组件，强烈建议移除对 driver 驱动组件的依赖，并为项目添加新驱动组件（通常是 `esp_driver_xxx`）的依赖。

如仍需保留老旧的 driver 驱动组件（例如您的项目依赖旧版 `i2c` 驱动），请将 driver 组件保留在项目的组件依赖列表文件中（通常是 `<project_root>/main/CMakeLists.txt` ），并根据项目需要手动添加 driver 中不再包含的驱动组件依赖。

### 所有驱动的 `io_loop_back` 配置已被移除

不同的驱动对象可以共享同一个 GPIO 编号，联合起来可以实现更加复杂的功能。比如将 RMT 外设的 TX 通道和 RX 通道绑定在同一个 GPIO 上，进而模拟单总线的读写时序。在以前的版本中，你需要在驱动的配置中额外设置 `io_loop_back` 来实现这种“回环”功能，现在，这个配置已经被移除。不同的驱动只需要在配置中设置相同的 GPIO 编号就能实现这个功能。

### 外设时钟门控

外设的时钟门控现在由驱动层统一管理，用户无需手动控制外设模块的时钟开关。相关的 API 位于私有头文件 `esp_private/periph_ctrl.h` 中。原先用于同样目的的头文件 `driver/periph_ctrl.h` 已被移除。

### RTC 子系统控制

低功耗模块通常会共享一些资源，比如中断号。为避免资源冲突，私有头文件 `esp_private/rtc_ctrl.h` 提供了相关 API 方便管理这些共享资源。原先用于同样目的的头文件 `driver/rtc_cntl.h` 已被移除。

### 驱动头文件移除 FreeRTOS 依赖

自 v6.0 起，为了增强 IDF 驱动的通用性，所有公开的驱动头文件不再包含具体操作系统(FreeRTOS)相关的头文件。因此，以前依赖这种隐式包含逻辑的应用代码，在 v6.0 之后需要显示添加对应的 FreeRTOS 头文件。

## ADC

旧版的 ADC 驱动 `driver/adc.h` 在 5.0 的版本中就已经被弃用 （参考 ADC）。从 6.0 版本开始，旧版驱动被完全移除。新驱动位于 esp_adc 组件中，头文件引用路径为 `esp_adc/adc_oneshot.h`, `esp_adc/adc_continuous.h`, `esp_adc/adc_cali.h` 和 `esp_adc/adc_cali_scheme.h`。

## RMT

`rmt_tx_channel_config_t` 配置结构体中的 `io_od_mode` 已经被移除。如果想要使用开漏模式，你需要手动调用 GPIO 驱动中的 `gpio_od_enable()` 函数。

## GPIO

- `gpio_iomux_in()` 和 `gpio_iomux_out()` 已被 `gpio_iomux_input()` 和 `gpio_iomux_output()` 函数取代， 并移至 `esp_private/gpio.h` 头文件中作为仅供内部使用的私有 API。

- `rom_` 前缀已添加进 `components/esp_rom/esp32xx/include/esp32xx/rom/gpio.h` 中的所有 GPIO ROM API。例如，`gpio_iomux_in()` 现在为 `rom_gpio_iomux_in()`。

- `MAX_PAD_GPIO_NUM`、 `MAX_GPIO_NUM` 和 `DIG_IO_HOLD_BIT_SHIFT` 宏已被移除。

- 为 `gpio_uninstall_isr_service()` 添加了 `esp_err_t` 返回类型。

### GPIO 深度睡眠唤醒 API 已移除

以下 GPIO 驱动 API 已被移除：

- `gpio_deep_sleep_wakeup_enable()` - 请使用 `gpio_wakeup_enable_on_hp_periph_powerdown_sleep()` 替代

- `gpio_deep_sleep_wakeup_disable()` - 请使用 `gpio_wakeup_disable_on_hp_periph_powerdown_sleep()` 替代

已弃用的宏 `GPIO_IS_DEEP_SLEEP_WAKEUP_VALID_GPIO()` 已被移除。请使用 `GPIO_IS_HP_PERIPH_PD_WAKEUP_VALID_IO()` 替代。

迁移示例：

旧代码：

    #include "driver/gpio.h"

    // 启用 GPIO 唤醒
    gpio_deep_sleep_wakeup_enable(GPIO_NUM_0, GPIO_INTR_LOW_LEVEL);

    // 检查有效性
    if (GPIO_IS_DEEP_SLEEP_WAKEUP_VALID_GPIO(GPIO_NUM_0)) {
        // ...
    }

新代码：

    #include "driver/gpio.h"

    // 启用 GPIO 唤醒（同时支持深度睡眠和外设电源域掉电时的 Light Sleep）
    gpio_wakeup_enable_on_hp_periph_powerdown_sleep(GPIO_NUM_0, GPIO_INTR_LOW_LEVEL);

    // 检查 GPIO 外设掉电的睡眠唤醒有效性
    if (GPIO_IS_HP_PERIPH_PD_WAKEUP_VALID_IO(GPIO_NUM_0)) {
        // ...
    }

更多详细信息，请参阅系统迁移指南中的 GPIO 唤醒 API 变更 部分。

## LEDC

- `ledc_timer_set()` 已被移除。请使用 `ledc_timer_config()` 或 `ledc_set_freq()` 代替。

- `LEDC_APB_CLK_HZ` 和 `LEDC_REF_CLK_HZ` 已被移除。

- `LEDC_SLOW_CLK_RTC8M` 宏已被移除。请使用 `LEDC_SLOW_CLK_RC_FAST` 代替。

- esp_driver_gpio 不再作为 esp_driver_ledc 的公共依赖组件。

- `ledc_isr_register()` 已被弃用。LEDC 中断处理由驱动内部实现，如果需要注册中断回调，仅需要注册事件回调即可。

- `ledc_channel_config_t::intr_type` 已被弃用。LEDC_INTR_FADE_END 中断使能/禁用控制由驱动内部处理。用户仍可以通过 `ledc_cb_register()` 注册该中断的回调。

- `soc_periph_ledc_clk_src_legacy_t::LEDC_USE_RTC8M_CLK` 已被移除。请使用 `LEDC_USE_RC_FAST_CLK` 代替。

## UART

- `UART_FIFO_LEN` 已被移除。请使用 `UART_HW_FIFO_LEN` 代替。

- `soc/uart_channel.h` 头文件已被移除。所有 UART GPIO 查找宏都可以在 `soc/uart_pins.h` 中找到。例如，`UART_NUM_0_TXD_DIRECT_GPIO_NUM` 等同于 `U0TXD_GPIO_NUM`。

## I2C

### 旧版 I2C 驱动生命周期终止

警告

旧版 I2C 驱动（`driver/i2c.h`）已在 ESP-IDF v6.0 中被标记为 生命周期终止（End-of-Life, EOL），并计划在 v7.0 中彻底移除。

- ESP-IDF 将不再为旧版驱动提供及时的更新、错误修复或安全补丁。

- 强烈建议用户尽快迁移到新版 I2C 驱动：`driver/i2c_master.h` 和 `driver/i2c_slave.h`。

- 如需暂时抑制编译警告，可在 menuconfig 中启用 `Component config` > `Legacy Driver Configurations` > `Legacy I2C Driver Configurations` > `Suppress legacy driver deprecated warning`。

新版 I2C 驱动主要改进了从机和主机的使用方式，详细内容请参考 I2C 迁移指南 和 I2C 驱动编程指南。

### I2C 从机驱动更新

I2C 从机驱动在 v5.4 上已经被重新设计。在当前版本上，旧的 I2C 从机驱动已经被移除。

#### 主要概念更新

- 旧版本的 I2C 从机驱动是主动读写，这不符合 I2C 从机的一般用法。在新版的 I2C 从机中，I2C 的读写通过主机驱动产生的事件以触发回调被动完成。

#### 主要用法更新

- `i2c_slave_receive` 被移除，在新驱动中使用回调接收数据。

- `i2c_slave_transmit` 已被 `i2c_slave_write` 取代。

- `i2c_slave_write_ram` 被移除。

- `i2c_slave_read_ram` 被移除。

### I2C 主机驱动更新

I2C 主机驱动的 API 也有一些用法上的改动。

#### 主要用法更新

当主机在 I2C 总线上检测到 NACK，以下的函数目前会返回 `ESP_ERR_INVALID_RESPONSE`，而不是像之前一样返回 `ESP_ERR_INVALID_STATE`：

- `i2c_master_transmit`

- `i2c_master_multi_buffer_transmit`

- `i2c_master_transmit_receive`

- `i2c_master_execute_defined_operations`

## 旧版定时器组驱动被移除

旧版的定时器组驱动 `driver/timer.h` 在 5.0 的版本中就已经被弃用 （参考 旧版定时器组驱动被弃用）。从 6.0 版本开始，旧版驱动被完全移除。新驱动位于 esp_driver_gptimer 组件中，头文件引用路径为 `driver/gptimer.h`。

## 旧版 I2S 驱动被移除

- 旧版的 I2S 驱动 `driver/i2s.h` 在 5.0 的版本中就已经被弃用（请参考 I2S 驱动）。从 6.0 版本开始，旧版驱动被完全移除。新驱动位于 esp_driver_i2s 组件中，头文件引用路径为 `driver/i2s_std.h`, `driver/i2s_pdm.h` and `driver/i2s_tdm.h`。

- `i2s_set_adc_mode`, `i2s_adc_enable` 和 `i2s_adc_disable` 在 5.0 版本中就已经被弃用。从 6.0 版本开始，这三个接口被完全移除。

## 旧版 PCNT 驱动被移除

旧版的 PCNT 驱动 `driver/pcnt.h` 在 5.0 的版本中就已经被弃用 （参考 旧版 PCNT 驱动被弃用）。从 6.0 版本开始，旧版驱动被完全移除。新驱动位于 esp_driver_pcnt 组件中，头文件引用路径为 `driver/pulse_cnt.h`。

## PCNT GPIO 上下拉配置

新版 PCNT 驱动不再对边沿信号、电平信号或清零信号所使用的 GPIO 自动使能或关闭内部上拉/下拉电阻。如果输入信号需要确定的空闲电平，请调用相应的 GPIO API 显式配置 GPIO 的上下拉模式。

## 旧版 RMT 驱动被移除

旧版的 RMT 驱动 `driver/rmt.h` 在 5.0 的版本中就已经被弃用（请参考 旧版 RMT 驱动已被弃用）。从 6.0 版本开始，旧版驱动被完全移除。新驱动位于 esp_driver_rmt 组件中，头文件引用路径为 `driver/rmt_tx.h`, `driver/rmt_rx.h` 和 `driver/rmt_encoder.h`。

## DMA 驱动

- DMA 核心驱动程序现已从原来的 `esp_hw_support` 组件中移出，现作为单独的 `esp_driver_dma` 组件提供。如果你使用了 `esp_async_memcpy.h` 和 `esp_dma_utils.h` 驱动，请确保在项目中添加对 `esp_driver_dma` 组件的依赖。

- `GDMA_ISR_IRAM_SAFE` Kconfig 选项会带来不必要的风险，因此被移除。现在，不同的 GDMA 通道它们的中断在 Cache 关闭期间的行为可以互不影响。

- `gdma_new_channel` 已经被移除。现在当申请一个 GDMA 通道时，必须要根据实际使用的总线调用 `gdma_new_ahb_channel` 或 `gdma_new_axi_channel` 函数。

- `async_memcpy_config_t` 中的 `sram_trans_align` 和 `psram_trans_align` 成员均已经被移除。请使用 `async_memcpy_config_t::dma_burst_size` 来设置 DMA 的突发传输大小。

- `esp_dma_capable_malloc` 和 `esp_dma_capable_calloc` 函数已经被移除。请使用 heap/include/esp_heap_caps.h 中的 `heap_caps_malloc()` 和 `heap_caps_calloc()` 函数搭配 `MALLOC_CAP_DMA|MALLOC_CAP_CACHE_ALIGNED` 分配满足 DMA 和 Cache 对齐要求的内存。

## SDMMC

- `sdmmc_host_t` 结构体中的 `get_dma_info` 成员接口已经被移除。对应的 `sdspi_host_get_dma_info` 和 `sdmmc_host_get_dma_info` 函数也已经被移除。DMA 相关的设置会由驱动内部处理好。

## 旧版 DAC 驱动被移除

旧版的 DAC 驱动 `driver/dac.h` 在 5.1 的版本中就已经被弃用（请参考 DAC）。从 6.0 版本开始，旧版驱动被完全移除。新驱动位于 esp_driver_dac 组件中，头文件引用路径为 `driver/dac_oneshot.h`， `driver/dac_continuous.h` 和 `driver/dac_cosine.h`。

## 旧版温度传感器驱动被移除

旧版的温度传感器驱动 `driver/temp_sensor.h` 在 5.1 的版本中就已经被弃用（请参考 旧版温度传感器驱动已被弃用）。从 6.0 版本开始，旧版驱动被完全移除。新驱动位于 esp_driver_tsens 组件中，头文件引用路径为 `driver/temperature_sensor.h`。

## 旧版 Sigma-Delta 调制器驱动被移除

旧版的 Sigma-Delta 调制器驱动 `driver/sigmadelta.h` 在 5.0 的版本中就已经被弃用（请参考 旧版 Sigma-Delta 调制器驱动已被弃用）。从 6.0 版本开始，旧版驱动被完全移除。新驱动位于 esp_driver_sdm 组件中，头文件引用路径为 `driver/sdm.h`。

- `sdm_channel_set_duty()` 已被移除。请使用 `sdm_channel_set_pulse_density()` 替代。

## LCD

- LCD 驱动中的 GPIO 编号已经从 `int` 类型修改为更加类型安全的 `gpio_num_t` 类型。比如原来使用 `5` 作为 GPIO 编号，现在需要使用 `GPIO_NUM_5`。

- `esp_lcd_i80_bus_config_t` 结构体中的 `psram_trans_align` 和 `sram_trans_align` 均已被 `esp_lcd_i80_bus_config_t::dma_burst_size` 成员取代，用来设置 DMA 的突发传输大小。

- `esp_lcd_rgb_panel_config_t` 结构体中的 `psram_trans_align` 和 `sram_trans_align` 均已被 `esp_lcd_rgb_panel_config_t::dma_burst_size` 成员取代，用来设置 DMA 的突发传输大小。

- `esp_lcd_panel_dev_config_t` 结构体中的 `color_space` 和 `rgb_endian` 配置均已被 `esp_lcd_panel_dev_config_t::rgb_ele_order` 成员取代，用来设置 RGB 元素的排列顺序。对应的类型 `lcd_color_rgb_endian_t` 和 `esp_lcd_color_space_t` 也已被移除，请使用 `lcd_rgb_element_order_t` 替代。

- `esp_lcd_panel_disp_off` 函数已被移除。请使用 `esp_lcd_panel_disp_on_off()` 函数来控制显示内容的开关。

- `esp_lcd_rgb_panel_event_callbacks_t` 中的 `on_bounce_frame_finish` 成员已被 `esp_lcd_rgb_panel_event_callbacks_t::on_frame_buf_complete` 成员取代，用于指示一个完整的帧缓冲区可以被安全复用。

- I2C 接口的 LCD IO 层驱动有两套实现，分别基于新、旧 I2C Master 总线驱动。由于旧版的 I2C Master 驱动逐渐被弃用，遂 LCD 的 IO 层也移除对旧版的支持，只使用 `driver/i2c_master.h` 中提供的 API。

- `esp_lcd_dpi_panel_config_t` 结构体中的 `pixel_format` 成员已经被删除。建议仅使用 `esp_lcd_dpi_panel_config_t::in_color_format` 来设定 MIPI DSI 驱动输入的像素数据格式。

- `esp_lcd_rgb_panel_config_t` 结构体中的 `bits_per_pixel` 成员已经被删除。内部帧缓冲区的色彩深度现在由 `esp_lcd_rgb_panel_config_t::in_color_format` 成员决定。

- `esp_lcd_dpi_panel_set_color_conversion` 函数已被 `esp_lcd_dpi_panel_set_yuv_conversion()` 取代,用于设置 YUV 到 RGB 的色彩转换配置。

- `esp_lcd_rgb_panel_set_yuv_conversion()` 函数的签名已改变。原先使用的 `esp_lcd_yuv_conv_config_t` 配置类型现已被 `esp_lcd_color_conv_yuv_config_t` 取代。

- NT35510 LCD 设备驱动已经从 ESP-IDF 中移动到外部仓库，并且托管在了 ESP Component Registry 上。如果你的项目使用到了 NT35510 驱动，你可以通过运行 `idf.py add-dependency "espressif/esp_lcd_nt35510"` 将它添加到你的项目中。

- `esp_lcd_dpi_panel_config_t` 结构体中的 `use_dma2d` 成员已被移除。请使用 `esp_lcd_dpi_panel_enable_dma2d()` 函数来启用 DMA2D 功能。当不使用 DMA2D 时，可以减小 10KB 左右的二进制文件大小。

## 颜色类型 (Color Types)

位于 `components/hal/include/hal/color_types.h` 头文件中的以下类型已被移除，请使用 FourCC 格式（`esp_color_fourcc_t`）替代：

- `color_space_t` - 颜色空间枚举类型已被移除。请使用 FourCC 格式来指定颜色空间和像素格式。

- `color_space_pixel_format_t` - 颜色空间像素格式联合体已被移除。请使用 `esp_color_fourcc_t` 类型和相应的 FourCC 宏定义来指定像素格式。

迁移示例：

    /* 旧版 */
    color_space_pixel_format_t format = {
        .color_space = COLOR_SPACE_RGB,
        .pixel_format = COLOR_PIXEL_RGB565
    };

    /* 新版 */
    esp_color_fourcc_t format = ESP_COLOR_FOURCC_RGB565;

## SPI

- CONFIG_SPI_MASTER_IN_IRAM 选项在 menuconfig 中默认不可见，并且依赖于 CONFIG_FREERTOS_IN_IRAM。这样修改是为了防止位于 IRAM 中的 SPI 函数调用位于 flash 中的 FreeRTOS 函数时可能发生的崩溃。

- 按照下列步骤，启用 SPI 主机 IRAM 优化：

  > 1. 在 menuconfig 中进入 `Component config` → `FreeRTOS` → `Port`。

  > 2. 启用 `Place FreeRTOS functions in IRAM` (CONFIG_FREERTOS_IN_IRAM)。

  > 3. 在 menuconfig 中进入 `Component config` → `ESP-Driver:SPI Configurations`。

  > 4. 启用 `Place transmitting functions of SPI master into IRAM` (CONFIG_SPI_MASTER_IN_IRAM)。

  > 备注

  > 启用 CONFIG_FREERTOS_IN_IRAM 会显著增加 IRAM 使用量。在优化 SPI 性能时，需进行权衡。

- ESP32 和 ESP32S2 上已弃用的 HSPI 和 VSPI 相关 IOMUX 引脚宏已被移除。

## PSRAM

已弃用的头文件 `esp_spiram.h` 已被移除，请改用 `esp_psram.h`。

## SPI flash 驱动

- 已弃用的 `enum` 类型 `esp_flash_speed_t` 已被移除。主 flash 速度由 CONFIG_ESPTOOLPY_FLASHFREQ 选项控制。

- 已弃用的头文件 `esp_spi_flash.h` 已被移除。请改用 `spi_flash_mmap.h`。

- 已弃用的 API `spi_flash_dump_counters` 已被移除。请改用 `esp_flash_dump_counters()`。

- 已弃用的 API `spi_flash_get_counters` 已被移除。请改用 `esp_flash_get_counters()`。

- 已弃用的 API `spi_flash_reset_counters` 已被移除。请改用 `esp_flash_reset_counters()`。

- `esp_flash_os_functions_t::start` 新增了一个参数 `flags`。调用者和实现者应正确处理此参数。

- Kconfig 选项 `CONFIG_SPI_FLASH_ROM_DRIVER_PATCH` 已被移除，考虑到这个选项不会被广泛被用户使用，且有因误用而导致出现严重的问题，遂决定移除。

### 头文件重组

为了更好地反映其可见性和预期用途，多个内部头文件已重新组织：

- Flash 芯片驱动相关头文件 已移至 `esp_flash_chips/` 目录： - `spi_flash_chip_driver.h` - `spi_flash_chip_*.h` - `spi_flash_defs.h` - `spi_flash_override.h` - `esp_flash_types.h` - `esp_flash_t` 结构体定义已从 `esp_flash.h` 移至 `esp_flash_chips/esp_flash_types.h`。应用程序不应直接访问结构体成员；请改用公开 API（例如，使用 `esp_flash_get_size()` 而不是直接访问 `chip->size`）。 - `esp_flash_os_functions_t` 结构体定义已从 `esp_flash.h` 移至 `esp_flash_chips/esp_flash_types.h`。 - `spi_flash_chip_t` 类型的前向声明已从 `esp_flash.h` 和所有 ROM 头文件（`components/esp_rom/esp32xx/include/esp32xx/rom/esp_flash.h`）中移除。该类型现在仅在 `esp_flash_chips/esp_flash_types.h` 中定义。应用程序不应直接使用此类型；它仅用于自定义芯片驱动实现。

  备注

  `esp_flash_chips/` 中的头文件是**半公开的** - 它们面向需要为不支持的 flash 芯片实现自定义芯片驱动的专家用户，但**不被视为稳定 API**，可能会在不通知的情况下更改。对于大多数用例，您应该改用 `esp_flash.h` 中的公开 API。更多详情请参阅 SPI Flash 驱动覆盖。

- 内部头文件 已移至 `esp_private/` 目录，且不包含在公共（稳定）头文件中： - `esp_flash_internal.h` - `memspi_host_driver.h`

## Touch Element

`touch_element` 组件已移至 ESP Component Registry。

您可以通过运行 `idf.py add-dependency "espressif/touch_element"` 将这个依赖添加到您的项目中。

## Touch Sensor

第三版触摸传感器的驱动配置项 `touch_sensor_sample_config_t::bypass_shield_output` 已被移除，因为第三版触摸传感器硬件已不支持该功能。

旧版触摸传感器驱动依赖已被移除，现在你需要使用 `int` 类型代替 `touch_pad_t` 类型来指示触摸通道 ID。

## I2S

- `i2s_port_t` 类型已被移除。请使用 `int` 类型代替。该类型原有的 enum 项 `I2S_NUM_0`，`I2S_NUM_1`，`I2S_NUM_2` 和 `I2S_NUM_AUTO` 已用宏定义代替，以保证兼容性。

## USB

`usb` 组件已迁移至 乐鑫组件注册表。

你可以通过运行 `idf.py add-dependency "espressif/usb"`，将此依赖添加到项目中。

## 双线汽车接口 (TWAI)

TWAI 在 5.5 版本已经提供的新的驱动接口，支持更灵活的配置和更丰富的功能。旧版驱动不推荐再继续使用，请参考 5.5 迁移指南 TWAI迁移指南 和新版驱动编程指南 TWAI驱动编程指南 进行移植。

若需要继续使用旧版驱动，可以打开配置项 CONFIG_TWAI_SUPPRESS_DEPRECATE_WARN 以关闭编译警告。

此文档对您有帮助吗？

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

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