ESP-IDF 相机控制器驱动esp_driver_cam开发指南MIPI CSI / ISP DVP / LCD_CAM DVP 统一接口实战【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idf本指南以 ESP-IDF 官方文档 Camera Controller Driver 为主体系统讲解esp_driver_cam组件中相机控制器驱动的完整使用方法如何在 MIPI CSI、ISP DVP 与 LCD_CAM DVP 三种硬件通路之间做资源分配、驱动使能、启停、收帧与事件回调并给出缓存关闭Cache-Safe / IRAM-Safe场景下的配置建议。读完本文你将能够基于esp_cam_ctlr_*系列 API 快速搭建一条相机传感器 → 控制器 → 应用缓冲区的完整数据通路并理解其底层接口抽象与 SOC 能力约束。概述三种硬件通路与一个统一驱动接口ESP32 系列芯片为连接外部相机传感器设计了三种硬件通路在 components/esp_driver_cam 组件中分别由三个工厂函数承载MIPI CSISOC_MIPI_CSI_SUPPORTEDMIPI Camera Serial Interface面向 MIPI CSI 协议相机对应esp_cam_new_csi_ctlrISP DVPSOC_ISP_DVP_SUPPORTED经 ISP 模块接入的 Digital Video Port对应esp_cam_new_isp_dvp_ctlrLCD_CAM DVPSOC_LCDCAM_CAM_SUPPORTED经 LCD_CAM 模块实现的 DVP 端口对应esp_cam_new_lcd_cam_ctlr。这些能力宏定义在各芯片的soc_caps.h中从仓库源码可以确认当前的支持矩阵esp32p4 同时使能了SOC_LCDCAM_CAM_SUPPORTED、SOC_MIPI_CSI_SUPPORTED与SOC_ISP_DVP_SUPPORTEDesp32s3 与 esp32s31 使能了SOC_LCDCAM_CAM_SUPPORTED。无论底层走哪条通路驱动最终都返回统一的esp_cam_ctlr_handle_t句柄。这一统一抽象定义在 esp_cam_ctlr_interface.h 中struct esp_cam_ctlr_t是一张纯函数指针表包含enable、start、stop、disable、receive、del、register_event_callbacks、get_internal_buffer、get_buffer_len、alloc_buffer、format_conversion等操作。公共 API 层 esp_cam_ctlr.c 只是对这些函数指针做参数校验如空指针检查、能力未实现检查后转发因此上层业务代码可以完全与具体硬件通路解耦。资源分配创建相机控制器实例三种工厂函数创建控制器实例有三种方式按 SOC 能力选择其一esp_cam_new_csi_ctlrMIPI CSI配置结构体esp_cam_ctlr_csi_config_tesp_cam_new_isp_dvp_ctlrISP DVP配置结构体esp_cam_ctlr_isp_dvp_cfg_t需先创建 ISP 处理器句柄esp_cam_new_lcd_cam_ctlrLCD_CAM DVP配置结构体esp_cam_ctlr_dvp_config_t创建成功后返回控制器句柄失败时返回错误码。从 esp_cam_ctlr_csi.h 的注释可以看到典型返回值ESP_OK、ESP_ERR_INVALID_ARG、ESP_ERR_NO_MEM、ESP_ERR_NOT_SUPPORTED以及ESP_ERR_NOT_FOUND表示该通路控制器已被注册。方式一MIPI CSI 控制器以下示例创建一个 2-lane MIPI CSI 控制器输入 RAW8、输出 RGB565#include esp_cam_ctlr.h #include esp_cam_ctlr_types.h #include esp_cam_ctlr_csi.h void app_main(void) { esp_cam_ctlr_csi_config_t csi_config { .ctlr_id 0, .h_res MIPI_CSI_DISP_HSIZE, .v_res MIPI_CSI_DISP_VSIZE_640P, .lane_bit_rate_mbps MIPI_CSI_LANE_BITRATE_MBPS, .input_data_color_type CAM_CTLR_COLOR_RAW8, .output_data_color_type CAM_CTLR_COLOR_RGB565, .data_lane_num 2, .byte_swap_en false, .queue_items 1, }; esp_cam_ctlr_handle_t handle NULL; ESP_ERROR_CHECK(esp_cam_new_csi_ctlr(csi_config, handle)); }esp_cam_ctlr_csi_config_t的完整字段见 esp_cam_ctlr_csi.h要点如下字段含义备注ctlr_idCSI 控制器 ID通常取 0clk_srcCSI PHY 时钟源mipi_csi_phy_clock_source_t类型h_res/v_res输入水平 / 垂直分辨率单位分别为像素/行、行/帧data_lane_num数据 lane 数如 1、2、4lane_bit_rate_mbps单 lane 比特率单位 Mbpsinput_data_color_type/output_data_color_type输入 / 输出颜色格式见下方cam_ctlr_color_tdata_type自定义数据类型默认置 0 即可支持 embedded data 与标准数据类型queue_items队列项数内部缓冲队列深度input_8bit_swap_en输入 8bit 位交换使能后[31:24][23:16][15:8][7:0]→[7:0][15:8][23:16][31:24]input_16bit_swap_en输入 16bit 位交换使能后[31:16][15:0]→[15:0][31:16]byte_swap_en输出字节交换调节输出字节序bk_buffer_dis禁用备用缓冲区置 1 时驱动不再分配内部 backup bufferMIPI CSI 供电要求CSI 外设在芯片内需要稳定的 2.5 V 电源使用前请对照原理图确认电源引脚已接 2.5 V。在支持内部可调 LDOSOC_GP_LDO_SUPPORTED的芯片上可以将 LDO 通道输出引脚接到 CSI 供电引脚在初始化 CSI 驱动前调用 ldo_regulator 的 API 将 LDO 配置为输出 2.5 V。方式二ISP DVP 控制器使用 ISP DVP 通路时必须先通过esp_isp_new_processor创建 ISP 处理器句柄再以该句柄创建 DVP 控制器#include esp_err.h #include esp_cam_ctlr.h #include esp_cam_ctlr_isp_dvp.h #include driver/isp.h #define MIPI_CSI_DISP_HSIZE 800 // example value, replace with actual resolution #define MIPI_CSI_DISP_VSIZE 600 // example value, replace with actual resolution void app_main(void) { isp_proc_handle_t isp_proc NULL; esp_isp_processor_cfg_t isp_config { .clk_hz 120 * 1000 * 1000, .input_data_source ISP_INPUT_DATA_SOURCE_DVP, .input_data_color_type ISP_COLOR_RAW8, .output_data_color_type ISP_COLOR_RGB565, .has_line_start_packet false, .has_line_end_packet false, .h_res MIPI_CSI_DISP_HSIZE, .v_res MIPI_CSI_DISP_VSIZE, }; ESP_ERROR_CHECK(esp_isp_new_processor(isp_config, isp_proc)); esp_cam_ctlr_handle_t cam_handle NULL; esp_cam_ctlr_isp_dvp_cfg_t dvp_ctlr_config { .data_width 8, .data_io {53, 54, 52, 0, 1, 45, 46, 47, -1, -1, -1, -1, -1, -1, -1, -1}, .pclk_io 21, .hsync_io 5, .vsync_io 23, .de_io 22, .io_flags.vsync_invert 1, .queue_items 10, }; ESP_ERROR_CHECK(esp_cam_new_isp_dvp_ctlr(isp_proc, dvp_ctlr_config, cam_handle)); }esp_cam_ctlr_isp_dvp_cfg_t的关键字段esp_cam_ctlr_isp_dvp.hdata_width数据线宽度cam_ctlr_data_width_t可取值 8/10/12/16见 cam_ctlr_types.hdata_io[16]DVP 数据输入 IO最多 16 路未用引脚填-1ESP_CAM_CTLR_ISP_DVP_DATA_SIG_NUM_MAX定义为 16pclk_io/hsync_io/vsync_io/de_io像素时钟、行同步、场同步、数据使能引脚io_flagspclk_invert、hsync_invert低有效、vsync_invert高有效、de_invert低有效用于适配不同传感器极性queue_items队列项数。方式三LCD_CAM DVP 控制器LCD_CAM DVP 通路先配置引脚esp_cam_ctlr_dvp_pin_config_t再配置控制器esp_cam_ctlr_dvp_config_t#include esp_err.h #include esp_cam_ctlr.h #include esp_cam_ctlr_types.h #include esp_cam_ctlr_dvp.h void app_main(void) { esp_cam_ctlr_handle_t cam_handle NULL; esp_cam_ctlr_dvp_pin_config_t pin_cfg { .data_width EXAMPLE_DVP_CAM_DATA_WIDTH, .data_io { EXAMPLE_DVP_CAM_D0_IO, EXAMPLE_DVP_CAM_D1_IO, EXAMPLE_DVP_CAM_D2_IO, EXAMPLE_DVP_CAM_D3_IO, EXAMPLE_DVP_CAM_D4_IO, EXAMPLE_DVP_CAM_D5_IO, EXAMPLE_DVP_CAM_D6_IO, EXAMPLE_DVP_CAM_D7_IO, }, .vsync_io EXAMPLE_DVP_CAM_VSYNC_IO, .de_io EXAMPLE_DVP_CAM_DE_IO, .pclk_io EXAMPLE_DVP_CAM_PCLK_IO, .xclk_io EXAMPLE_DVP_CAM_XCLK_IO, // Set XCLK pin to generate XCLK signal }; esp_cam_ctlr_dvp_config_t dvp_config { .ctlr_id 0, .clk_src CAM_CLK_SRC_DEFAULT, .h_res CONFIG_EXAMPLE_CAM_HRES, .v_res CONFIG_EXAMPLE_CAM_VRES, .input_data_color_type CAM_CTLR_COLOR_RGB565, .output_data_color_type CAM_CTLR_COLOR_RGB565, .dma_burst_size 128, .pin pin_cfg, .bk_buffer_dis 1, .xclk_freq EXAMPLE_DVP_CAM_XCLK_FREQ_HZ, }; ESP_ERROR_CHECK(esp_cam_new_dvp_ctlr(dvp_config, cam_handle)); }esp_cam_ctlr_dvp_config_t的完整字段见 esp_cam_ctlr_dvp.h要点external_xtal置 1 时使用外部晶振产生 XCLK此时xclk_io与驱动内部生成的输出时钟都会被忽略否则由驱动内部生成 XCLKcam_data_width数据位宽8/16/24 位默认 8bit_swap_en/byte_swap_en位交换 / 字节交换开关其组合效果可参考头文件内附的 GDMA 数据字节序表以输入B0,B1,B2,B3,B4,B5、地址由低到高为例cam_data_widthbit_swap_enbyte_swap_en阶段 1 输出数据序列8-bit00{B0}{B1}{B2}{B3}{B4}{B5}8-bit01{B1,B0}{B3,B2}{B5,B4}8-bit10{B0}{B1}{B2}{B3}{B4}{B5}8-bit11{B1,B0}{B3,B2}{B5,B4}16-bit00{B1,B0}{B3,B2}{B5,B4}16-bit01{B0,B1}{B2,B3}{B4,B5}24-bit00{B2,B1,B0}{B5,B4,B3}24-bit01{B0,B1,B2}{B3,B4,B5}其中B0表示按位取反序Bn[7:0] Bn[0:7]{}内为大端并行数据{}之间为串行输出、从左到右。bk_buffer_dis禁用备用缓冲区pin_dont_init若此前已调用过esp_cam_ctlr_dvp_init可跳过引脚初始化pic_format_jpeg输入为 JPEG 时置位此时input_data_color_type会被忽略dma_burst_sizeDMA 突发传输块大小置 0 表示禁用突发其他值必须为 2 的幂如 4/8/16/32/64/128xclk_freqDVP 输出时钟频率Hz。创建 DVP 控制器后需要分配满足对齐约束的相机缓冲区可自行分配也可调用esp_cam_ctlr_alloc_buffer自动分配该函数必须在esp_cam_new_*_ctlr之后调用buf_caps支持MALLOC_CAP_SPIRAM || MALLOC_CAP_DMA或MALLOC_CAP_INTERNAL || MALLOC_CAP_DMA见 esp_cam_ctlr.h。颜色格式枚举三种通路共用的cam_ctlr_color_t定义于 cam_ctlr_types.h采用 FourCC 编码包括CAM_CTLR_COLOR_RAW8/RAW10/RAW12、CAM_CTLR_COLOR_RGB565、CAM_CTLR_COLOR_RGB888、CAM_CTLR_COLOR_YUV420、四种 YUV422 变体YVYU/YUYV/UYVY/VYUY与CAM_CTLR_COLOR_GRAY8。格式转换LCD_CAM DVP 通路支持调用esp_cam_ctlr_format_conversion配置格式转换配置结构体cam_ctlr_format_conv_config_t包含src_format、dst_format、conv_std、data_width、input_range、output_range见 cam_ctlr_types.h。驱动支持以下转换类型与色域范围转换类型YUV → RGB、RGB → YUV、YUV → YUV色域范围Full rangeRGB 与 YUV 均为 0-255Limited rangeRGB 16-240YUV Y 为 16-240、U-V 为 16-235。PCLK 频率限制来自文档注意事项cam_data_width 8时建议 CAM_PCLK 频率低于 80 MHz若同时启用 YUV-RGB 格式转换建议低于 60 MHzcam_data_width 16时建议 CAM_PCLK 频率低于 40 MHz若同时启用 YUV-RGB 格式转换建议低于 30 MHz。卸载驱动当不再需要相机控制器时调用esp_cam_ctlr_del释放底层硬件资源。公共层实现位于 esp_cam_ctlr.c同样会先做空指针校验再转发到对应通路的del实现。使能与禁用init ↔ enable对控制器执行任何操作前先调用esp_cam_ctlr_enable将驱动状态从init切换到enable#include esp_cam_ctlr.h #include esp_cam_ctlr_types.h #include esp_err.h void app_main(void) { esp_cam_ctlr_handle_t handle; ESP_ERROR_CHECK(esp_cam_ctlr_enable(handle)); }需要回到init状态时调用esp_cam_ctlr_disable#include esp_err.h #include esp_cam_ctlr.h #include esp_cam_ctlr_types.h void app_main(void) { esp_cam_ctlr_handle_t handle; ESP_ERROR_CHECK(esp_cam_ctlr_disable(handle)); }两个 API 的返回值均为ESP_OK、ESP_ERR_INVALID_ARG参数非法或ESP_ERR_INVALID_STATE状态非法见 esp_cam_ctlr.h。启动与停止enable ↔ start开始接收相机信号前调用esp_cam_ctlr_start将驱动状态从enable切换到start#include esp_err.h #include esp_log.h #include esp_cam_ctlr.h #include esp_cam_ctlr_types.h void app_main(void) { esp_cam_ctlr_handle_t handle NULL; ESP_ERROR_CHECK(esp_cam_ctlr_start(handle)); ESP_LOGI(CAM, Camera controller started successfully); }停止接收并回到enable状态则调用esp_cam_ctlr_stop#include esp_err.h #include esp_cam_ctlr.h #include esp_cam_ctlr_types.h void app_main(void) { esp_cam_ctlr_handle_t handle NULL; ESP_ERROR_CHECK(esp_cam_ctlr_stop(handle)); }由此可归纳驱动的生命周期状态机init → enable → start逆向依次为start → enable → init每一层都由一对 API 完成单向切换。接收相机数据通过esp_cam_ctlr_receive接收来自相机传感器的数据。事务描述符类型esp_cam_ctlr_trans_t包含三个字段esp_cam_ctlr_types.hbuffer事务缓冲区指针、buflen缓冲区长度、received_size实际接收长度由驱动回填#include esp_err.h #include esp_cam_ctlr.h #include esp_cam_ctlr_types.h ESP_ERROR_CHECK(esp_cam_ctlr_receive(handle, my_trans, ESP_CAM_CTLR_MAX_DELAY));其中ESP_CAM_CTLR_MAX_DELAY定义为UINT32_MAXesp_cam_ctlr_types.h表示不设超时上限timeout_ms以毫秒为单位可传入任意有限超时值。注册事件回调驱动开始接收数据后可能动态产生事件。通过esp_cam_ctlr_register_event_callbacks注册用户回调回调集合定义于esp_cam_ctlr_evt_cbs_tesp_cam_ctlr_types.h包含三个回调on_get_new_trans驱动完成一个事务并尝试获取新的事务描述符时被调用在 CSI 通路的s_ctlr_csi_start中也会被调用。若该回调未提供新的事务描述符且bk_buffer_dis标志未置位驱动会使用内部备用缓冲区on_trans_finished驱动完成一个事务时被调用。该函数运行在 ISR 上下文中必须避免阻塞例如只能使用带ISR后缀的 FreeRTOS APIon_error检测到错误时被调用同样运行在 ISR 上下文禁止调用阻塞 API。当控制器的 ISR Cache-Safe 选项使能时该回调及其 user data 必须放在内部 RAM 中。错误事件数据esp_cam_ctlr_error_event_data_t携带csi_host_err_evts位掩码可组合ESP_CAM_CTLR_CSI_HOST_ERR_PHYPHY 错误、ESP_CAM_CTLR_CSI_HOST_ERR_PACKET数据包错误、ESP_CAM_CTLR_CSI_HOST_ERR_FRAME帧边界/序列错误、ESP_CAM_CTLR_CSI_HOST_ERR_CRC帧或负载 CRC 错误、ESP_CAM_CTLR_CSI_HOST_ERR_DATA_ID无法识别或不受支持的数据类型等标志具体枚举见 esp_cam_ctlr_types.h。此外若启用了内部备用缓冲区可调用esp_cam_ctlr_get_frame_buffer/esp_cam_ctlr_get_frame_buffer_len获取内部缓冲区地址与长度——内部缓冲区的数据通常在on_trans_finished事件发生时已就绪见 esp_cam_ctlr.h。线程安全以下工厂函数是线程安全的可以从不同的 RTOS 任务中直接调用而无需额外加锁esp_cam_new_csi_ctlrSOC_MIPI_CSI_SUPPORTEDesp_cam_new_isp_dvp_ctlrSOC_ISP_DVP_SUPPORTEDesp_cam_ctlr_delKconfig 配置选项相机控制器驱动提供三个 Kconfig 选项均位于 components/esp_driver_cam/Kconfig用于控制缓存禁用场景下的中断行为选项依赖默认值作用CAM_CTLR_MIPI_CSI_ISR_CACHE_SAFESOC_MIPI_CSI_SUPPORTEDn确保 CSI 驱动 ISR 在缓存关闭时仍可用CAM_CTLR_ISP_DVP_ISR_CACHE_SAFESOC_ISP_DVP_SUPPORTEDn确保 ISP DVP 驱动 ISR 在缓存关闭时仍可用CAM_CTLR_DVP_CAM_ISR_CACHE_SAFESOC_LCDCAM_CAM_SUPPORTEDn确保 DVP 驱动 ISR 在缓存关闭时仍可用使能 CSI/ISP_DVP 的 Cache-Safe 选项后Kconfig 会联动选择 DW_GDMA 的ISR_IRAM_SAFE、CTRL_FUNC_IN_IRAM、SETTER_FUNC_IN_IRAM、GETTER_FUNC_IN_IRAM使能 DVP 选项后会联动选择 GDMA 的ISR_HANDLER_IN_IRAM、CTRL_FUNC_IN_IRAM在SOC_GDMA_SUPPORTED时生效。IRAM Safety缓存禁用时的中断可靠性默认情况下在 Flash 写入或擦除等缓存被禁用的操作期间CSI 中断会被延迟直到缓存重新使能后才被处理。启用上述 Cache-Safe Kconfig 选项会带来以下效果即使缓存被禁用中断也能得到及时服务ISR 用到的所有函数被放入 IRAM驱动对象被放入 DRAM避免映射到 PSRAM。代价是 IRAM 占用增加。在缓存关闭期间必须确保用户回调及其相关代码/数据同样是 IRAM-Safe 或 DRAM-Safe例如使用IRAM_ATTR修饰回调函数、将数据放在内部 RAM否则仍可能出现取指/取数异常。应用示例仓库提供了三个开箱即用的完整示例均位于 examples/peripherals/camera演示了从采集到显示的完整链路mipi_isp_dsi使用esp_driver_cam组件经 ISP 模块采集 MIPI CSI 相机信号并通过 DSI 接口在 LCD 上显示dvp_isp_dsi使用esp_driver_cam组件经 ISP 模块采集 DVP 相机信号并通过 DSI 接口在 LCD 上显示dvp_dsi使用esp_driver_cam组件采集 DVP 相机数据并在 MIPI DSI LCD 上显示。配套的自动化测试位于 components/esp_driver_cam/test_appscsi / dvp / isp_dvp 三个子目录测试代码覆盖了驱动创建、使能、收帧等核心路径例如test_csi_ov5647.c、test_dvp_ov2640.c、test_isp_dvp_driver.c并配有 cache_safe、pm_enable、release 等不同sdkconfig.ci.*构建配置可帮助理解不同场景下的正确用法。小结相机控制器驱动通过统一的esp_cam_ctlr_handle_t句柄屏蔽了 MIPI CSI、ISP DVP、LCD_CAM DVP 三种硬件通路的差异资源分配阶段按 SOC 能力选择对应的工厂函数并配置各自的配置结构体运行阶段则使用同一套 enable/start/receive/stop/disable 状态机 API。需要特别留意三点MIPI CSI 的 2.5 V 供电必要时用内部 LDO 提供、DVP 通路的 PCLK 频率上限尤其开启格式转换后、以及缓存关闭场景下通过 Cache-Safe Kconfig 选项配合 IRAM/DRAM 安全的回调代码。对上述细节的完整实现参考可继续阅读 esp_cam_ctlr.h、esp_cam_ctlr_types.h 及各通路头文件。【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考