# 外设驱动

[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` 已被移除。

## 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()` 函数。

## MCPWM

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

以下配置结构体中的 `pull_up` 和 `pull_down` 成员已经被移除，你需要手动调用 GPIO 驱动中的 `gpio_set_pull_mode()` 函数来配置 IO 上拉和下拉电阻：

- `mcpwm_generator_config_t`

- `mcpwm_gpio_fault_config_t`

- `mcpwm_gpio_sync_src_config_t`

- `mcpwm_capture_channel_config_t`

默认的 MCPWM 群组时钟分频器已改为 1。这样，你就可以获得比以前更高的默认分辨率。

### 旧版 MCPWM 驱动被移除

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

### 可变参数生成器 API 已被移除

本版本中已移除旧版的可变参数（"varg"）生成器 API。原先使用可变参数方式配置生成器动作的代码，需迁移到显式、类型化的 API。这些新 API 使用配置结构体和类型明确的设置函数（例如 `mcpwm_generator_config_t`、`mcpwm_gen_timer_event_action_t` 和 `mcpwm_generator_set_action_on_timer_event`）。

迁移步骤（摘要）：

- 用辅助结构体/宏和专用设置函数替换 varg 风格的动作配置:

      .. code-block:: c

          /* 旧版（varg）*/
          mcpwm_generator_set_actions_on_compare_event(my_generator,
              MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, my_comparator, MCPWM_GEN_ACTION_LOW),
              MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_DOWN, my_comparator, MCPWM_GEN_ACTION_HIGH),
              MCPWM_GEN_COMPARE_EVENT_ACTION_END());

          /* 新版 */
          mcpwm_generator_set_action_on_compare_event(my_generator,
              MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, my_comparator, MCPWM_GEN_ACTION_LOW));
          mcpwm_generator_set_action_on_compare_event(my_generator,
              MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_DOWN, my_comparator, MCPWM_GEN_ACTION_HIGH));

## GPIO

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

## 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`。

## 旧版 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`。

## GDMA

- `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`。

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

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

## 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` 成员取代，用于指示一个完整的帧缓冲区已被发送给 LCD 控制器。

- 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 驱动输入的像素数据格式。

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

## 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()`。

备注

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

## 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"`，将此依赖添加到项目中。

此文档对您有帮助吗？

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

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