ESP-IDF v6.1 外设迁移指南：MIPI DSI DPI 面板回调与 UART 唤醒 API 重构
发布时间：2026/9/17 7:55:39 作者：尧图编辑部 阅读量：1,286
ESP-IDF v6.1 外设迁移指南MIPI DSI DPI 面板回调与 UART 唤醒 API 重构【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idf本文是 ESP-IDF v6.1 外设Peripherals迁移指南的深度解读聚焦两个直接影响现有工程代码的破坏性变更MIPI DSI DPI 面板事件回调的语义调整与弃用on_refresh_done→on_frame_buf_complete以及 UART 轻睡眠唤醒 API 的全面重构uart_set/get_wakeup_threshold→uart_wakeup_setup。读完本文你将掌握新版回调的准确触发时机、UART 四种唤醒模式含字符序列检测的配置方法以及如何对照源码完成无痛迁移。本文对应迁移指南原文docs/en/migration-guides/release-6.x/6.1/peripherals.rst。LCDMIPI DSI DPI 面板事件回调的语义重构在 v6.1 中LCD 外设的变更集中在 MIPI DSI DPI 面板的事件回调上共两点一是回调的弃用与更名二是 VSYNC 事件的正式化。on_refresh_done 弃用改用 on_frame_buf_completeesp_lcd_dpi_panel_event_callbacks_t::on_refresh_done回调已被标记为弃用deprecated请改用esp_lcd_dpi_panel_event_callbacks_t::on_frame_buf_complete来判断帧缓冲区何时可以被安全复用。从 components/esp_lcd/dsi/include/esp_lcd_mipi_dsi.h 的结构体定义可以清晰看到这次更名的动机typedef bool (*esp_lcd_dpi_panel_general_cb_t)(esp_lcd_panel_handle_t panel, esp_lcd_dpi_panel_event_data_t *edata, void *user_ctx); /* deprecated Use esp_lcd_dpi_panel_frame_buf_complete_cb_t instead. */ typedef esp_lcd_dpi_panel_general_cb_t esp_lcd_dpi_panel_refresh_done_cb_t; /* 帧缓冲区可以安全复用时调用 */ typedef esp_lcd_dpi_panel_general_cb_t esp_lcd_dpi_panel_frame_buf_complete_cb_t; typedef struct { esp_lcd_dpi_panel_color_trans_done_cb_t on_color_trans_done; union { esp_lcd_dpi_panel_refresh_done_cb_t on_refresh_done __attribute__((deprecated(Deprecated, use on_frame_buf_complete instead))); esp_lcd_dpi_panel_frame_buf_complete_cb_t on_frame_buf_complete; /*! Invoked when the frame buffer can be reused safely when the frame buffer is the draw buffer. */ }; esp_lcd_dpi_panel_vsync_cb_t on_vsync; /*! VSYNC event callback */ } esp_lcd_dpi_panel_event_callbacks_t;关键点在于on_refresh_done与on_frame_buf_complete在结构体中位于同一个union内二者在内存上重叠。旧回调名容易让人误以为刷新动作已经完成而新名称on_frame_buf_complete准确描述了真实语义——当帧缓冲区frame buffer本身即绘制缓冲区draw buffer时该回调在帧缓冲区可被安全复用重新写入时触发。在驱动实现 components/esp_lcd/dsi/esp_lcd_panel_dpi.c 中可以看到实际触发逻辑约 L99-L108if (dpi_panel-on_frame_buf_complete) { if (dpi_panel-on_frame_buf_complete(dpi_panel-base, NULL, dpi_panel-user_ctx)) { ... } }VSYNC 时序事件正式化on_vsyncMIPI DSI DPI 面板的 VSYNC 时序事件现在统一由esp_lcd_dpi_panel_event_callbacks_t::on_vsync上报。在驱动中VSYNC 中断到来时会调用该回调esp_lcd_panel_dpi.c 约 L107-L108 与 L131-L132 两处 VSYNC 相关处理路径。需要注意的是DPI 面板的回调运行在中断上下文中注册时驱动会强制校验回调函数必须位于 IRAM见 esp_lcd_panel_dpi.c L735-L739 的esp_ptr_in_iram检查因此实现on_vsync/on_frame_buf_complete/on_color_trans_done时需遵循 IRAM 安全约束使用IRAM_ATTR避免在回调内调用 Flash 中的函数。迁移动作归纳旧回调新回调触发时机on_refresh_done弃用on_frame_buf_complete帧缓冲区可安全复用时新增on_vsync控制器发出 VSYNC 信号时典型的新版注册写法可参考 test_apps/mipi_dsi_lcd/main/test_mipi_dsi_panel.c 与 test_mipi_dsi_iram.cesp_lcd_dpi_panel_event_callbacks_t cbs { .on_color_trans_done my_color_trans_done_cb, .on_frame_buf_complete my_frame_buf_complete_cb, .on_vsync my_vsync_cb, }; ESP_ERROR_CHECK(esp_lcd_dpi_panel_register_event_callbacks(dpi_panel, cbs, user_ctx));UART唤醒 API 全面重构ESP-IDF v6.1 将遗留的 UART 唤醒 APIuart_set_wakeup_threshold与uart_get_wakeup_threshold标记为弃用并将在未来版本移除。这两个遗留 API 仅支持 RXD 边沿阈值唤醒即 Mode 0。替代方案是统一的uart_wakeup_setup它提供更灵活的配置方式并支持多种唤醒模式。四种唤醒模式模式宏名称说明UART_WK_MODE_ACTIVE_THRESHMode 0有效边沿阈值唤醒对应遗留 API 的功能统计 RXD 上的有效边沿数UART_WK_MODE_FIFO_THRESHMode 1RX FIFO 阈值唤醒RX FIFO 中收到的数据字节数达到阈值即唤醒UART_WK_MODE_START_BITMode 2起始位检测唤醒检测到起始位即唤醒UART_WK_MODE_CHAR_SEQMode 3字符序列检测唤醒检测到预设字符序列触发短语即唤醒四种模式并非所有芯片都支持具体可用性由芯片 SOC 能力宏决定SOC_UART_WAKEUP_SUPPORT_XXX_MODE系列宏。详见 components/esp_driver_uart/include/driver/uart_wakeup.h 中的条件编译typedef struct { uart_wakeup_mode_t wakeup_mode; #if SOC_UART_WAKEUP_SUPPORT_ACTIVE_THRESH_MODE uint16_t rx_edge_threshold; /* RXD 边沿变化次数达到该次数唤醒芯片 */ #endif #if SOC_UART_WAKEUP_SUPPORT_FIFO_THRESH_MODE uint16_t rx_fifo_threshold; /* RX FIFO 收到字节数达到该值唤醒芯片 */ #endif #if SOC_UART_WAKEUP_SUPPORT_CHAR_SEQ_MODE NONSTRING_ATTR char wake_chars_seq[SOC_UART_WAKEUP_CHARS_SEQ_MAX_LEN]; /* 字符序列模式* 代表任意字符结尾字符不能是 * 例如 he**o 可匹配 hello、heyyo */ #endif } uart_wakeup_cfg_t;结构体中的成员同样按 SOC 能力宏条件编译这意味着在支持能力不足的芯片上对应成员根本不存在编译期即可暴露错误。实现位于 components/esp_driver_uart/src/uart_wakeup.cuart_wakeup_setup内部按模式分别校验阈值范围例如 ACTIVE_THRESH 模式校验rx_edge_threshold在UART_LL_WAKEUP_EDGE_THRED_MIN与UART_LL_WAKEUP_EDGE_THRED_MAX(hw)之间并调用对应的 LL 层寄存器配置。迁移示例旧代码v6.1 之前// 设置唤醒阈值 ESP_ERROR_CHECK(uart_set_wakeup_threshold(UART_NUM_0, 3)); ESP_ERROR_CHECK(esp_sleep_enable_uart_wakeup(UART_NUM_0)); // 获取唤醒阈值 int threshold; ESP_ERROR_CHECK(uart_get_wakeup_threshold(UART_NUM_0, threshold));新代码v6.1#include driver/uart_wakeup.h // 配置有效边沿阈值唤醒模式对应遗留 API 功能 uart_wakeup_cfg_t wakeup_cfg { .wakeup_mode UART_WK_MODE_ACTIVE_THRESH, .rx_edge_threshold 3, // 对应遗留 API 的 wakeup_threshold 参数 }; ESP_ERROR_CHECK(uart_wakeup_setup(UART_NUM_0, wakeup_cfg)); ESP_ERROR_CHECK(esp_sleep_enable_uart_wakeup(UART_NUM_0)); // 注意新 API 没有直接对应的 get 函数 // 如果需要在运行时获取当前配置请自行保存配置值若芯片支持字符序列唤醒还可实现更强的关键词唤醒参考 test_hp_uart_wakeup.c 中四种模式的测试用例uart_wakeup_cfg_t wakeup_cfg { .wakeup_mode UART_WK_MODE_CHAR_SEQ, .wake_chars_seq he**o, // 匹配 hello、heyyo 等 }; ESP_ERROR_CHECK(uart_wakeup_setup(UART_NUM_0, wakeup_cfg)); ESP_ERROR_CHECK(esp_sleep_enable_uart_wakeup(UART_NUM_0));遗留 API 与主要变更汇总在 components/esp_driver_uart/include/driver/uart.h 中两个遗留 API 已被显式标注弃用esp_err_t uart_set_wakeup_threshold(uart_port_t uart_num, int wakeup_threshold) __attribute__((deprecated(use uart_wakeup_setup instead))); esp_err_t uart_get_wakeup_threshold(uart_port_t uart_num, int* out_wakeup_threshold) __attribute__((deprecated));主要变更点API 替换uart_set_wakeup_threshold→uart_wakeup_setupuart_get_wakeup_threshold→ 移除无直接对应物。配置方式遗留 API 使用简单的整型参数新 API 使用uart_wakeup_cfg_t结构体支持多种唤醒模式。头文件新 API 需要包含driver/uart_wakeup.h头文件。功能扩展新 API 支持多种唤醒模式可按芯片能力选择不同唤醒模式的可用性取决于芯片的 SOC 能力由SOC_UART_WAKEUP_SUPPORT_XXX_MODE宏决定。迁移注意事项遗留 API 只支持 Mode 0有效边沿阈值唤醒。迁移时只需设置wakeup_mode UART_WK_MODE_ACTIVE_THRESH功能完全对应。新 API 的rx_edge_threshold参数与遗留 API 的wakeup_threshold参数含义相同。从 uart.h 的旧文档注释可知该值统计的是 RX 引脚上的正边沿0→1 跳变数量且停止位、校验位若使能也会贡献边沿数。例如 ASCII 码 97 的字母 a 在 8N1 配置下线上编码为0100001101含起始位和停止位共有 3 个正边沿因此要收到 a 就唤醒需设wakeup_threshold 3。合法取值范围为 3 到 0x3ff。注意触发唤醒的字符本身不会被 UART 接收无法从 FIFO 读出且根据波特率不同其后几个字符也可能丢失。新 API 没有提供获取当前唤醒配置的读取接口。如果运行期需要读取配置建议在调用uart_wakeup_setup时自行保存配置值。不同的芯片可能支持不同的唤醒模式请参考 ESP-IDF 官方文档中的 UART Wakeup (Light-sleep Only) 一节uart_wakeup_light_sleep。唤醒模式除 ACTIVE_THRESH 外其余模式对时钟有额外要求从 uart_wakeup.c 的实现看HP UART 在非 ACTIVE_THRESH 模式下要求源时钟为 XTAL否则返回ESP_ERR_NOT_SUPPORTED并且睡眠期间需要保持相关时钟与电源域开启LP UART 则由 RTC_FAST / RC_FAST / XTAL_D2 等时钟源决定是否支持。新 API 还提供了对应的清理函数uart_wakeup_clear(uart_port_t, uart_wakeup_mode_t)用于清除指定 UART 的唤醒配置并恢复默认状态见 uart_wakeup.h 与 uart_wakeup.c 的实现。迁移自检清单完成上述两项外设迁移后建议按以下清单自查DPI 面板代码中是否仍引用on_refresh_done—— 全部替换为on_frame_buf_complete并确认触发语义为帧缓冲区可安全复用。是否依赖 VSYNC 时序—— 改用on_vsync回调并确认回调函数位于 IRAM。UART 唤醒代码是否还在使用uart_set/get_wakeup_threshold—— 改用uart_wakeup_setup并包含driver/uart_wakeup.h。是否使用了目标芯片不支持的唤醒模式—— 依据SOC_UART_WAKEUP_SUPPORT_XXX_MODE宏与目标芯片手册确认。非 ACTIVE_THRESH 模式下是否满足了时钟源HP UART 需 XTAL等硬件前提运行期是否需要读取唤醒配置—— 如需自行保存uart_wakeup_cfg_t配置副本。遵循以上要点即可平滑升级到 ESP-IDF v6.1 的外设 API同时获得更精确的帧缓冲复用时机通知与更灵活的低功耗 UART 唤醒能力。【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
尧图网站开发 