摄像头控制器驱动程序

[English]

简介

ESP32-P4 具有以下硬件，用于与外部摄像头传感器通信：

MIPI 摄像头串行接口 (CSI)
ISP 数字视频端口 (ISP DVP)

摄像头控制器驱动程序是为上述硬件外设而设计的。

功能概述

资源分配 - 涵盖如何通过恰当的配置来分配摄像头控制器实例，以及如何回收资源。
启用和禁用摄像头控制器驱动程序 - 涵盖如何启用和禁用摄像头控制器。
启动和停止摄像头控制器驱动程序 - 涵盖如何启动和停止摄像头控制器。
从摄像头传感器处接收信号 - 涵盖如何从传感器或其他设备接收摄像头信号。
注册事件回调函数 - 涵盖如何将用户特定代码挂接到摄像头控制器驱动程序事件回调函数。
线程安全 - 列出了驱动程序中线程安全的 API。
Kconfig 选项 - 列出了支持的 Kconfig 选项，这些选项可以对驱动程序产生不同的影响。
IRAM 安全 - 描述了当 cache 被禁用时，如何使 CSI 中断和控制功能更好地工作。

资源分配

安装摄像头控制器驱动程序

摄像头控制器驱动程序可以通过 CSI 外设实现，需要应用 esp_cam_ctlr_csi_config_t 指定的配置。

如果指定了 esp_cam_ctlr_csi_config_t 中的配置，就可以调用 esp_cam_new_csi_ctlr() 来分配和初始化 CSI 摄像头控制器句柄。如果函数运行正确，将返回一个 CSI 摄像头控制器句柄。请参考以下代码。

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));

摄像头控制器驱动程序可以通过 ISP 外设实现，需要应用 esp_cam_ctlr_isp_dvp_cfg_t 指定的配置。

如果指定了 esp_cam_ctlr_isp_dvp_cfg_t 中的配置，就可以调用 esp_cam_new_isp_dvp_ctlr() 来分配和初始化 ISP DVP 摄像头控制器句柄。如果函数运行正确，将返回一个 ISP DVP 摄像头控制器句柄。请参考以下代码。

在调用 esp_cam_new_isp_dvp_ctlr() 之前，还应调用 esp_isp_new_processor() 来创建 ISP 句柄。

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_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_del() 来回收资源，从而释放底层硬件。

启用和禁用摄像头控制器驱动程序

在开始摄像头控制器操作之前，首先要调用 esp_cam_ctlr_enable() 以启用摄像头控制器驱动程序。此函数：

将驱动程序状态从 init 切换到 enable。

ESP_ERROR_CHECK(esp_cam_ctlr_enable(handle));

调用 esp_cam_ctlr_disable() 则会执行与上述过程相反的操作，即将驱动程序切回到 init 状态。

ESP_ERROR_CHECK(esp_cam_ctlr_disable(handle));

启动和停止摄像头控制器驱动程序

从摄像头传感器接收信号之前，首先要调用 esp_cam_ctlr_start() 以启动摄像头控制器驱动程序。此函数：

将驱动程序状态从 enable 切换到 start。

ESP_ERROR_CHECK(esp_cam_ctlr_start(handle));

调用 esp_cam_ctlr_stop() 则会执行与上述过程相反的操作，即将驱动程序切回到 enable 状态。

ESP_ERROR_CHECK(esp_cam_ctlr_stop(handle));

从摄像头传感器处接收信号

调用 esp_cam_ctlr_receive()，可以接收来自摄像头传感器或其他设备的信号。

ESP_ERROR_CHECK(esp_cam_ctlr_receive(handle, &my_trans, ESP_CAM_CTLR_MAX_DELAY));

注册事件回调函数

摄像头控制器驱动程序开始接收信号时，会动态生成特定事件。如果在事件发生时需要调用一些函数，请通过调用 esp_cam_ctlr_register_event_callbacks() 将这些函数挂接到中断服务程序。所有支持的事件回调函数参见 esp_cam_ctlr_evt_cbs_t：

esp_cam_ctlr_evt_cbs_t::on_get_new_trans 可设置回调函数，当摄像头控制器驱动程序完成传输并尝试获取新的事务描述符时，该回调函数会被调用。在 s_ctlr_csi_start() 中也会调用此回调函数。如果此回调函数未能获取新的事务描述符，但设置了 bk_buffer_dis 标志，则摄像头控制器驱动程序将使用内部备份 buffer。
esp_cam_ctlr_evt_cbs_t::on_trans_finished 可设置回调函数，当摄像头控制器驱动程序完成传输时，该回调函数会被调用。此函数在 ISR 上下文中被调用，因此必须确保该函数不会尝试阻塞（例如，确保只从该函数中调用带有 ISR 后缀的 FreeRTOS API）。

线程安全

以下工厂函数：

esp_cam_new_csi_ctlr()
esp_cam_new_isp_dvp_ctlr()
esp_cam_ctlr_del()

由驱动程序保证线程安全。使用时，可以直接从不同的 RTOS 任务中调用此类函数，无需额外锁保护。

Kconfig 选项

当 cache 被禁用时，以下 Kconfig 选项会影响中断处理程序的行为：

CONFIG_CAM_CTLR_MIPI_CSI_ISR_CACHE_SAFE，详情请参阅线程安全。
CONFIG_CAM_CTLR_ISP_DVP_ISR_CACHE_SAFE，详情请参阅线程安全。

IRAM 安全

默认情况下，当 cache 因写入或擦除 flash 等原因而被禁用时，CSI 中断将被推迟。

有以下 Kconfig 选项：

这些选项支持

即使 cache 被禁用也能启用中断服务
将 ISR 使用的所有函数放入 IRAM
将驱动程序对象放入 DRAM（以防意外映射到 PSRAM）

启用上述 Kconfig 选项，保证 cache 被禁用时中断可以正常运行，但这会增加 IRAM 使用量。因此，当 cache 被禁用时，用户回调函数需要注意（回调函数的）代码和数据应该是 IRAM 安全或 DRAM 安全的。

应用示例

peripherals/camera/mipi_isp_dsi 演示了如何使用 esp_driver_cam 组件从 MIPI CSI 摄像头传感器捕获信号，传入 ISP 模块，并通过 DSI 接口将其显示在 LCD 屏幕上。
peripherals/camera/dvp_isp_dsi 演示了如何使用 esp_driver_cam 组件从 DVP 摄像头传感器捕获信号，传入 ISP 模块，并通过 DSI 接口将其显示在 LCD 屏幕上。

API 参考

Header File

components/esp_driver_cam/include/esp_cam_ctlr.h
This header file can be included with:
#include "esp_cam_ctlr.h"
This header file is a part of the API provided by the esp_driver_cam component. To declare that your component depends on esp_driver_cam, add the following to your CMakeLists.txt:
REQUIRES esp_driver_cam
or
PRIV_REQUIRES esp_driver_cam

Functions

esp_err_t esp_cam_ctlr_enable(esp_cam_ctlr_handle_t handle)

Enable ESP CAM controller.

参数:

handle -- [in] ESP CAM controller handle

返回:

ESP_OK
ESP_ERR_INVALID_ARG: Invalid argument
ESP_ERR_INVALID_STATE: Invalid state

esp_err_t esp_cam_ctlr_start(esp_cam_ctlr_handle_t handle)

Start ESP CAM controller.

参数:

handle -- [in] ESP CAM controller handle

返回:

ESP_OK
ESP_ERR_INVALID_ARG: Invalid argument
ESP_ERR_INVALID_STATE: Invalid state

esp_err_t esp_cam_ctlr_stop(esp_cam_ctlr_handle_t handle)

Stop ESP CAM controller.

参数:

handle -- [in] ESP CAM controller handle

返回:

ESP_OK
ESP_ERR_INVALID_ARG: Invalid argument
ESP_ERR_INVALID_STATE: Invalid state

esp_err_t esp_cam_ctlr_disable(esp_cam_ctlr_handle_t handle)

Disable ESP CAM controller.

参数:

handle -- [in] ESP CAM controller handle

返回:

ESP_OK
ESP_ERR_INVALID_ARG: Invalid argument
ESP_ERR_INVALID_STATE: Invalid state

esp_err_t esp_cam_ctlr_receive(esp_cam_ctlr_handle_t handle, esp_cam_ctlr_trans_t *trans, uint32_t timeout_ms)

Receive data to the given transaction.

参数:

handle -- [in] ESP CAM controller handle
trans -- [in] ESP CAM controller transaction type
timeout_ms -- [in] Timeout in ms

返回:

ESP_OK
ESP_ERR_INVALID_ARG: Invalid argument
ESP_ERR_INVALID_STATE: Invalid state

esp_err_t esp_cam_ctlr_del(esp_cam_ctlr_handle_t handle)

Delete ESP CAM controller handle.

参数:

handle -- [in] ESP CAM controller handle

返回:

ESP_OK
ESP_ERR_INVALID_ARG: Invalid argument
ESP_ERR_INVALID_STATE: Invalid state

esp_err_t esp_cam_ctlr_register_event_callbacks(esp_cam_ctlr_handle_t handle, const esp_cam_ctlr_evt_cbs_t *cbs, void *user_data)

Register ESP CAM controller event callbacks.

参数:

handle -- [in] ESP CAM controller handle
cbs -- [in] ESP CAM controller event callbacks
user_data -- [in] User data

返回:

ESP_OK
ESP_ERR_INVALID_ARG: Invalid argument
ESP_ERR_INVALID_STATE: Invalid state

esp_err_t esp_cam_ctlr_get_frame_buffer(esp_cam_ctlr_handle_t handle, uint32_t fb_num, const void **fb0, ...)

Get ESP CAM controller internal malloced backup buffer(s) addr.

备注

Generally, data in internal buffer is ready when on_trans_finished event

参数:

handle -- [in] ESP CAM controller handle
fb_num -- [in] Number of frame buffer(s) to get. This value must be the same as the number of the followed fbN parameters
fb0 -- [out] Address of the frame buffer 0 (first frame buffer)
... -- [out] List of other frame buffers if any

返回:

ESP_OK
ESP_ERR_INVALID_ARG: Invalid argument
ESP_ERR_INVALID_STATE: Invalid driver state

esp_err_t esp_cam_ctlr_get_frame_buffer_len(esp_cam_ctlr_handle_t handle, size_t *ret_fb_len)

Get ESP CAM controller internal backup buffer length.

参数:

handle -- [in] ESP CAM controller handle
ret_fb_len -- [out] Optional, The size of each frame buffer, in bytes.

返回:

ESP_OK
ESP_ERR_INVALID_ARG: NULL ptr
ESP_ERR_INVALID_STATE: Invalid driver state

Header File

components/esp_driver_cam/include/esp_cam_ctlr_types.h
This header file can be included with:
#include "esp_cam_ctlr_types.h"
This header file is a part of the API provided by the esp_driver_cam component. To declare that your component depends on esp_driver_cam, add the following to your CMakeLists.txt:
REQUIRES esp_driver_cam
or
PRIV_REQUIRES esp_driver_cam

Structures

struct esp_cam_ctlr_trans_t

ESP CAM controller transaction type.

Public Members

void *buffer: Transaction buffer.

size_t buflen: Len of the transaction buffer.

size_t received_size: Received size, this received_size will be written by the driver, indicating the real received size.

struct esp_cam_ctlr_evt_cbs_t

ESP CAM controller event callbacks.

Public Members

bool (*on_get_new_trans)(esp_cam_ctlr_handle_t handle, esp_cam_ctlr_trans_t *trans, void *user_data)

On get new transaction callback.

Param handle:: [in] ESP CAM controller handle
Param trans:: [in] New transaction
Param user_data:: [in] User registered data
Return:: Whether a high priority task is woken up by this function

bool (*on_trans_finished)(esp_cam_ctlr_handle_t handle, esp_cam_ctlr_trans_t *trans, void *user_data)

On transaction finish callback.

Param handle:: [in] ESP CAM controller handle
Param trans:: [out] Finished transaction
Param user_data:: [in] User registered data
Return:: Whether a high priority task is woken up by this function

Macros

ESP_CAM_CTLR_MAX_DELAY: ESP CAM controller max timeout value.

Type Definitions

typedef struct esp_cam_ctlr_t *esp_cam_ctlr_handle_t: ESP CAM controller handle.

Header File

components/esp_driver_cam/csi/include/esp_cam_ctlr_csi.h
This header file can be included with:
#include "esp_cam_ctlr_csi.h"
This header file is a part of the API provided by the esp_driver_cam component. To declare that your component depends on esp_driver_cam, add the following to your CMakeLists.txt:
REQUIRES esp_driver_cam
or
PRIV_REQUIRES esp_driver_cam

Functions

esp_err_t esp_cam_new_csi_ctlr(const esp_cam_ctlr_csi_config_t *config, esp_cam_ctlr_handle_t *ret_handle)

New ESP CAM CSI controller.

参数:

config -- [in] CSI controller configurations
ret_handle -- [out] Returned ESP CAM controller handle

返回:

ESP_OK
ESP_ERR_INVALID_ARG: Invalid argument
ESP_ERR_NO_MEM: Out of memory
ESP_ERR_NOT_SUPPORTED: Currently not support modes or types
ESP_ERR_NOT_FOUND: CSI is registered already

Structures

struct esp_cam_ctlr_csi_config_t

ESP CAM CSI controller configurations.

Public Members

int ctlr_id: CSI controller ID.

mipi_csi_phy_clock_source_t clk_src: CSI phy clock source.

uint32_t h_res: Input horizontal resolution, i.e. the number of pixels in a line.

uint32_t v_res: Input vertical resolution, i.e. the number of lines in a frame.

uint8_t data_lane_num: Data lane num.

int lane_bit_rate_mbps: Lane bit rate in Mbps.

cam_ctlr_color_t input_data_color_type: Input color type.

cam_ctlr_color_t output_data_color_type: Output color type.

int queue_items: Queue items.

uint32_t byte_swap_en: Enable byte swap.

uint32_t bk_buffer_dis: Disable backup buffer.

struct esp_cam_ctlr_csi_config_t: Boolean Flags.

Header File

components/esp_driver_cam/isp_dvp/include/esp_cam_ctlr_isp_dvp.h
This header file can be included with:
#include "esp_cam_ctlr_isp_dvp.h"
This header file is a part of the API provided by the esp_driver_cam component. To declare that your component depends on esp_driver_cam, add the following to your CMakeLists.txt:
REQUIRES esp_driver_cam
or
PRIV_REQUIRES esp_driver_cam

Functions

esp_err_t esp_cam_new_isp_dvp_ctlr(isp_proc_handle_t isp_proc, const esp_cam_ctlr_isp_dvp_cfg_t *ctlr_config, esp_cam_ctlr_handle_t *ret_handle)

New ESP CAM ISP DVP controller.

参数:

isp_proc -- [in] Processor handle
ctlr_config -- [in] ISP DVP controller configurations
ret_handle -- [out] Returned ESP CAM controller handle

返回:

ESP_OK
ESP_ERR_INVALID_ARG: Invalid argument
ESP_ERR_NO_MEM: Out of memory
ESP_ERR_NOT_SUPPORTED: Currently not support modes or types
ESP_ERR_NOT_FOUND: ISP DVP is registered already

Structures

struct esp_cam_ctlr_isp_dvp_cfg_t

ESP CAM ISP DVP controller configurations.

Public Members

cam_ctlr_data_width_t data_width: Number of data lines.

int data_io[ISP_DVP_DATA_SIG_NUM]: ISP DVP data-in IO numbers.

int pclk_io: ISP DVP pclk IO numbers.

int hsync_io: ISP DVP hsync IO numbers.

int vsync_io: ISP DVP vsync IO numbers.

int de_io: ISP DVP de IO numbers.

uint32_t pclk_invert: The pclk is inverted.

uint32_t hsync_invert: The hsync signal is inverted.

uint32_t vsync_invert: The vsync signal is inverted.

uint32_t de_invert: The de signal is inverted.

struct esp_cam_ctlr_isp_dvp_cfg_t io_flags: ISP DVP IO flags.

int queue_items: Queue items.

uint32_t byte_swap_en: Enable byte swap.

uint32_t bk_buffer_dis: Disable backup buffer.

Header File

components/esp_driver_isp/include/driver/isp_core.h
This header file can be included with:
#include "driver/isp_core.h"
This header file is a part of the API provided by the esp_driver_isp component. To declare that your component depends on esp_driver_isp, add the following to your CMakeLists.txt:
REQUIRES esp_driver_isp
or
PRIV_REQUIRES esp_driver_isp

Functions

esp_err_t esp_isp_new_processor(const esp_isp_processor_cfg_t *proc_config, isp_proc_handle_t *ret_proc)

New an ISP processor.

参数:

proc_config -- [in] Pointer to ISP config. Refer to esp_isp_processor_cfg_t.
ret_proc -- [out] Processor handle

返回:

ESP_OK On success
ESP_ERR_INVALID_ARG If the combination of arguments is invalid.
ESP_ERR_NOT_FOUND No free interrupt found with the specified flags
ESP_ERR_NOT_SUPPORTED Not supported mode
ESP_ERR_NO_MEM If out of memory

esp_err_t esp_isp_del_processor(isp_proc_handle_t proc)

Delete an ISP processor.

参数:

proc -- [in] Processor handle

返回:

ESP_OK On success
ESP_ERR_INVALID_ARG If the combination of arguments is invalid.
ESP_ERR_INVALID_STATE Driver state is invalid.

esp_err_t esp_isp_enable(isp_proc_handle_t proc)

Enable an ISP processor.

参数:

proc -- [in] Processor handle

返回:

ESP_OK On success
ESP_ERR_INVALID_ARG If the combination of arguments is invalid.
ESP_ERR_INVALID_STATE Driver state is invalid.

esp_err_t esp_isp_disable(isp_proc_handle_t proc)

Disable an ISP processor.

参数:

proc -- [in] Processor handle

返回:

ESP_OK On success
ESP_ERR_INVALID_ARG If the combination of arguments is invalid.
ESP_ERR_INVALID_STATE Driver state is invalid.

esp_err_t esp_isp_register_event_callbacks(isp_proc_handle_t proc, const esp_isp_evt_cbs_t *cbs, void *user_data)

Register ISP event callbacks.

备注

User can deregister a previously registered callback by calling this function and setting the to-be-deregistered callback member in the cbs structure to NULL.

备注

When CONFIG_ISP_ISR_IRAM_SAFE is enabled, the callback itself and functions called by it should be placed in IRAM. Involved variables (including user_data) should be in internal RAM as well.

参数:

proc -- [in] Processor handle
cbs -- [in] Group of callback functions
user_data -- [in] User data, which will be delivered to the callback functions directly

返回:

ESP_OK: On success
ESP_ERR_INVALID_ARG: Invalid arguments
ESP_ERR_INVALID_STATE: Driver state is invalid, you shouldn't call this API at this moment

Structures

struct esp_isp_processor_cfg_t

ISP configurations.

Public Members

isp_clk_src_t clk_src: Clock source.

uint32_t clk_hz: Clock frequency in Hz, suggest twice higher than cam sensor speed.

isp_input_data_source_t input_data_source: Input data source.

isp_color_t input_data_color_type: Input color type.

isp_color_t output_data_color_type: Output color type.

isp_color_range_t yuv_range: When the output_data_color_type is any YUV color space, this field is to describe its color range.

isp_yuv_conv_std_t yuv_std: This field is to describe YUV<->RGB conversion standard.

bool has_line_start_packet: Enable line start packet.

bool has_line_end_packet: Enable line end packet.

uint32_t h_res: Input horizontal resolution, i.e. the number of pixels in a line.

uint32_t v_res: Input vertical resolution, i.e. the number of lines in a frame.

color_raw_element_order_t bayer_order: Bayer order.

int intr_priority: The interrupt priority, range 0~3, if set to 0, the driver will try to allocate an interrupt with a relative low priority (1,2,3)

此文档对您有帮助吗？

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

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