企业官网建设流程全解析

升级到 ESP-IDF 6.0 后如何从旧 driver 组件迁移到独立的 esp_driver_xxx 组件？

【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idf

如果你的 ESP-IDF 项目升级到 6.0 后，main/CMakeLists.txt里还声明着旧版driver组件依赖，那么 ADC、GPTimer、I2S、RMT、PCNT 等外设的旧头文件（如driver/adc.h、driver/timer.h）已经不再存在，编译会因为找不到头文件或符号而失败。本文的任务就是：按官方 6.0 外设迁移指南 的说法，把项目对旧driver组件的依赖替换为独立的esp_driver_xxx组件，并完成配套的头文件路径与 API 改动，让项目重新正常构建。

6.0 中 driver 组件发生了什么

6.0 里旧driver组件被标记为废弃（deprecated），并且不再包含对下列组件的公共依赖，也就是说只写REQUIRES 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

官方建议是两条路径二选一：

1. 推荐：移除项目中的driver组件依赖，改为直接依赖你实际用到的esp_driver_xxx组件；
2. 暂留：如果项目仍依赖 legacyi2c等仍保留在旧组件里的驱动，就保留driver依赖，并手动补上它不再传递的那些esp_driver_xxx依赖。

另外两个全局性变化会影响所有驱动代码：

• 所有公共驱动头文件不再隐式包含 FreeRTOS 头文件。代码里如果之前靠driver/*.h间接引入FreeRTOS.h、task.h等，现在必须显式包含对应头文件。
• 各驱动的io_loop_back配置项已删除。不同驱动对象绑定同一个 GPIO 编号即可实现原来的“回环”效果（例如把 RMT 的 TX/RX 通道绑到同一 GPIO 模拟 1-Wire 时序），不再需要单独配置。

第一步：清点项目用到的旧 driver 头文件

打开应用代码，搜索#include "driver/形式的包含语句，列出实际用到的驱动头文件。旧头文件和新组件的对应关系（以迁移指南为准）如下：

上表只列了迁移指南中“旧驱动被完全移除”的部分；SPI、UART、TWAI、SDIO 等没有整表列出，但它们同样属于driver不再传递的组件列表，用到时同样要在依赖里显式加上对应组件。

第二步：修改 main/CMakeLists.txt 的组件依赖

在<project_root>/main/CMakeLists.txt的idf_component_register调用中，把driver换成（或补上）你实际用到的组件。REQUIRES用于公共依赖，PRIV_REQUIRES用于私有依赖，用法见 组件依赖说明：

# 迁移前：依赖旧 driver 组件 idf_component_register(SRCS main.c REQUIRES driver) # 迁移后：按实际用到的外设显式依赖 idf_component_register(SRCS main.c REQUIRES esp_driver_uart esp_driver_gptimer esp_driver_rmt)

把表里对应你项目的组件都替换进去即可。注意esp_adc是 ADC 的新组件名，不带_driver_前缀，不要写成esp_driver_adc。

如果你代码里还用了esp_async_memcpy.h或esp_dma_utils.h，DMA 核心驱动已从esp_hw_support拆出为独立的esp_driver_dma组件，需要额外加上这个依赖。

第三步：替换头文件并处理配套 API 变化

按上表替换包含路径后，还要处理迁移指南列出的配套删除项，这些代码改动不做完，换好依赖也编不过：

• SDM：sdm_channel_set_duty已移除，改用sdm_channel_set_pulse_density。
• I2S：i2s_set_adc_mode、i2s_adc_enable、i2s_adc_disable从 6.0 起彻底移除；i2s_port_t类型也移除了，改用int（原枚举项I2S_NUM_0等被替换为宏定义以保持兼容）。
• 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）。
• MCPWM：旧变参（varg）风格的 generator API 移除，必须改为带类型设置的写法，迁移指南给出的示例：

/* 旧（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));

此外mcpwm_generator_config_t等配置结构里的io_od_mode、pull_up、pull_down成员已移除，需要时手动调用gpio_od_enable、gpio_set_pull_mode；MCPWM 分组时钟默认分频改为 1。RMT 同样移除了rmt_tx_channel_config_t中的io_od_mode，开漏模式需手动调用gpio_od_enable。

• 外设时钟门控：driver/periph_ctrl.h已移除，时钟门控改由驱动层内部管理，对应的私有 API 在esp_private/periph_ctrl.h。

可选分支：仍要保留 legacy 驱动时的处理

如果项目还依赖仍然留在旧driver组件里的驱动（如 legacyi2c），按官方建议保留driver在依赖列表中，并手动补上它不再传递的esp_driver_xxx依赖。此时注意两点：

• legacy I2C 已被标记 EOL：6.0 起标记 End-of-Life，计划在v7.0 移除，官方建议尽早迁移到新的driver/i2c_master.h和driver/i2c_slave.h，详见 5.2 I2C 驱动迁移指南。想临时压掉编译告警，可在 menuconfig 中启用Component config→Legacy Driver Configurations→Legacy I2C Driver Configurations→Suppress legacy driver deprecated warning（对应选项见 components/driver/Kconfig）。
• legacy TWAI：新 TWAI 驱动接口自 5.5 提供，官方不再推荐使用旧驱动；确需继续用旧版时，可启用CONFIG_TWAI_SUPPRESS_DEPRECATE_WARN关闭告警。

另外，usb、touch_element、NT35510 屏驱等组件已移出仓库、托管到 ESP Component Registry，文档给出的获取方式是idf.py add-dependency "espressif/usb"、idf.py add-dependency "espressif/touch_element"、idf.py add-dependency "espressif/esp_lcd_nt35510"。只有项目用到这些对象时才需要执行。

验证迁移结果

改完后执行构建来验证：

idf.py build

判断依据：

• 构建通过，说明依赖与头文件替换完整。若报头文件找不到（例如driver/adc.h: No such file or directory）或未定义符号，回到第一步核对：是否漏改某个旧头文件、是否漏加对应组件依赖、esp_adc名称是否写错。
• 如果暂时保留了 legacy 驱动，构建输出中对应的 deprecation 告警即是你尚未迁移的驱动清单，可按上表逐一处理；告警抑制选项只用于过渡，不等于完成迁移。

边界与限制

• 本文范围是 6.0 中“driver组件不再传递的 18 个esp_driver_xxx组件”以及旧驱动被完全移除的头文件替换；各驱动自身的功能变更（如 I2C 从机改为回调式）属于驱动编程范畴，不在本文展开，可按链接的编程指南跟进。
• 旧driver组件目前仍保留 legacyi2c、legacy touch sensor、legacy TWAI（见 components/driver/CMakeLists.txt 中实际注册的源文件），它们与上表“已移除”的驱动不同，处理方式见“可选分支”一节。
• driver/periph_ctrl.h、driver/rtc_cntl.h等被移除的头文件没有等价公共替代，属于私有 API 调整，应用代码不应再直接引用。

【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idf