本文介绍 ESP32 Arduino Core 中的 ESP_Video 库,说明基于 V4L2 风格的采集 API 如何用于 MIPI-CSI 和 DVP 摄像头接口,并依次介绍硬件配置、帧采集流程,以及如何在 ESP32-P4 和 ESP32-S3 开发板上运行官方示例。
简介
在微控制器上点亮摄像头,通常需要先处理引脚表、传感器寄存器以及缓冲区管理等工作。ESP32 Arduino Core 中的 ESP_Video 库对 ESP-IDF 的 esp_video 组件进行了封装,将这些工作整合为一组精简的 C++ 类:配置摄像头总线、打开视频设备、启动视频流,并从队列中取出视频帧。
该采集 API 遵循 Linux V4L2 模型。硬件初始化完成后,应用程序通过 /dev/video0 等设备节点进行操作,请求 MMAP 缓冲区,并在循环中获取视频帧。典型应用包括实时预览、为计算机视觉抓取图像帧、JPEG 静态图像采集,以及传感器参数调节(如增益、曝光、翻转等)。
当 Arduino Core 基于 ESP-IDF 5.4.0 或更高版本构建,且目标芯片为 ESP32-S3 或 ESP32-P4 时,可使用 ESP_Video:

官方示例适用于 ESP32-P4-Function-EV-Board(MIPI-CSI 和 DVP)以及 ESP32-S3-EYE (DVP)。
对于熟悉经典 esp_camera / CameraWebServer 使用方式的开发者,可以将 ESP_Video 理解为更进一步的摄像头开发层:仍采用类似的 Arduino Sketch 方式,同时提供对 MIPI-CSI 的原生支持、ESP32-P4 片上 ISP(图像信号处理器)、V4L2 设备模型,以及更丰富的像素格式。
本文将介绍以下内容:
- 摄像头接口:MIPI-CSI与DVP的区别,以及二者如何呈现为视频设备
- ESP_Video API:配置、采集与缓冲区相关类
- Arduino IDE 快速入门:打开示例、选择开发板、烧录程序,并通过串口监视器查看视频帧
- 采集示例:解析示例程序内部实现,包括 MIPI-CSI (ESP32-P4) 和 DVP(ESP32-S3 或 ESP32-P4)的采集流程
- 像素格式与传感器控制:在 Arduino ESP32 文档中查找 setFormat() 可用值和 setSensor*() 方法
摄像头接口
摄像头传感器需要 SoC 提供两类连接:控制总线和像素总线。
SCCB(Serial Camera Control Bus,串行摄像头控制总线)本质上与 I2C 类似。主机通过 SCCB 检测传感器、加载寄存器配置,并在运行时调整增益、曝光、翻转和 JPEG 质量等参数。
像素总线用于实际传输图像数据。目前,ESP_Video 支持 DVP 和 MIPI-CSI。
DVP
DVP(Digital Video Port,数字视频端口)是一种并行摄像头接口。传感器通过 8 条数据线 (D0-D7) 传输数据,同时使用 VSYNC、DE (HREF)、PCLK,以及由 SoC 生成的外部时钟 (XCLK)。
开发者可能已在 ESP32-CAM 和 ESP32-S3-EYE 等开发板上使用过该接口。DVP 接线方式较直接,其带宽受并行总线和 GPIO 路由限制,适合 VGA 级传感器以及 JPEG 输出场景。
在 ESP_Video 中,未经过 ISP 路径的 DVP 摄像头会显示为 ESP_VIDEO_DVP_DEVICE_NAME (/dev/video2)。
MIPI-CSI
MIPI-CSI 是一种高速串行摄像头接口。像素数据通过差分通道传输,而非占用8个 GPIO。因此,ESP32-P4 可接收更高分辨率 RAW 传感器的数据,并通过片上 ISP(图像信号处理器)进行处理,再向应用程序提供 RGB、YUV 或 JPEG 数据。
在 ESP_Video 中,MIPI-CSI 摄像头显示 ESP_VIDEO_MIPI_CSI_DEVICE_NAME (/dev/video0)。
ESP32-P4 可同时运行 CSI 和 DVP。两个接口分别独立初始化,并在 ESPVideoClass::end() 中或对象销毁时释放。

备注
在 ESP-IDF 中,若开启对应的 Kconfig 配置选项,SPI 摄像头、USB UVC、JPEG/H.264 编解码器以及 ISP 设备会额外提供其他 V4L2 节点。本文中的 Arduino 示例使用 MIPI-CSI 和 DVP 采集节点。
ESP_Video API
在 Sketch 中包含库头文件:
#include <ESP_Video.h>
该 API 可分为七个层级:
- 像素格式 - esp_video_format_t 和 ESPVideoFormatClass
- 分辨率 - ESPVideoSolutionClass(帧宽和帧高)
- 硬件配置 - ESPVideoCamConfigClass、ESPVideoCSIConfigClass、ESPVideoDVPPinsConfigClass、ESPVideoDVPConfigClass
- 硬件初始化 - ESPVideoClass::begin()
- 采集设备 - ESPVideoCaptureDevClass
- 缓冲区 - ESPVideoBufferClass
- 传感器控制 - ESPVideoCaptureDevClass::setSensor*() 方法
一次完整的采集流程如下:

在查看代码之前,需要注意以下设计原则:
- 配置对象属于值类型。它们仅保存引脚和总线设置。通过 periman 预留引脚的操作发生在 ESPVideoClass::begin() 中,并在 end() 或析构函数中释放。
- 采集设备采用统一的打开方式。ESPVideoCaptureDevClass::begin() 会打开设备,读取并重新应用当前 V4L2 格式,保存宽度和高度信息,并申请采集缓冲区。
- 格式和分辨率信息会随视频帧传递。采集设备及每个出队缓冲区都会继承格式和分辨率元数据,因此 buffer.formatName()、getWidth() 和 getHeight() 描述的就是刚刚获取到的视频帧。
- 持有资源的类不可复制。在整个 Sketch 生命周期中,应使用一个 ESPVideoClass 和一个 ESPVideoCaptureDevClass。ESPVideoBufferClass 仅支持移动语义。
以下章节将依次介绍在 setup() 中实际创建的对象。
摄像头配置 (SCCB)
ESPVideoCamConfigClass 保存 CSI 和 DVP 共用的 SCCB / I2C 设置。调用 begin() 后,再将该对象传入 CSI 或 DVP 配置。
ESPVideoCamConfigClass cam_config;
cam_config.begin(port, scl_pin, sda_pin);
参数说明如下:
- port - 库初始化总线时用于 SCCB 的 I2C 端口
- scl_pin / sda_pin - SCCB 时钟和数据引脚
- i2c_freq - 可选参数;默认值为 100 kHz
- reset_pin / pwdn_pin - 可选的传感器复位和掉电 GPIO;未使用时传入 -1
如果 Sketch 已持有一个 I2C 主机总线,可使用接收 i2c_master_bus_handle_t 的重载版本。此时,库不会为 SCCB 创建第二个 I2C 驱动。
MIPI-CSI 配置
ESPVideoCSIConfigClass 在 ESP32-P4 上扩展摄像头配置,用于 MIPI-CSI + ISP。
ESPVideoCSIConfigClass csi_config;
csi_config.begin(cam_config);
如果 MIPI PHY 由外部供电,并且不希望 CSI 驱动初始化 LDO,可将第二个参数设置为 dont_init_ldo = true。
DVP 配置
DVP 还需要配置两项内容:并行接口引脚映射,以及传感器 XCLK 频率。
ESPVideoDVPPinsConfigClass dvp_pins;
dvp_pins.begin(vsync, de, pclk, xclk, d0, d1, d2, d3, d4, d5, d6, d7);
ESPVideoDVPConfigClass dvp_config;
dvp_config.begin(cam_config, dvp_pins, xclk_freq_hz);
引脚对象的 begin() 始终配置为 8 位数据宽度 (D0-D7)。xclk_freq_hz 是 SoC 为传感器生成的外部时钟频率:ESP32-S3-EYE 为 10 MHz,ESP32-P4-Function-EV-Board 的 DVP 摄像头为 20 MHz。
硬件初始化
创建一个 ESPVideoClass 实例(全局或静态),并根据接口类型调用对应的 begin() 重载:
ESPVideoClass video;
if (!video.begin(csi_config)) { // or dvp_config
Serial.println("failed to init camera");
return;
}
该调用会预留 GPIO,使用 CSI+ISP 或 DVP 标志初始化 esp_video,并保存配置以便后续释放资源。如果初始化成功或此前已完成初始化,则返回 true;如果失败,则会先释放已预留的引脚,再返回 false。
采集设备与视频帧
ESPVideoCaptureDevClass 用于打开 V4L2 采集节点、管理 MMAP 缓冲区,并从队列中取出视频帧。
ESPVideoCaptureDevClass capture;
if (!capture.begin(ESP_VIDEO_MIPI_CSI_DEVICE_NAME, 2)) {
Serial.println("failed to open capture device");
return;
}
if (!capture.setFormat(ESP_VIDEO_FORMAT_RGB565)) {
Serial.println("failed to set format");
return;
}
if (!capture.startCapture()) {
Serial.println("failed to start capture");
return;
}
- begin (path, buf_count) 会打开设备、应用当前格式,并申请 buf_count 个 MMAP 缓冲区。建议至少使用 2 个缓冲区,以便进行双缓冲采集并减少丢帧。
- setFormat() 将 esp_video_format_t 值映射为 V4L2 fourcc,并发出 VIDIOC_S_FMT。应在 begin() 之后、startCapture() 之前调用。如果已分配缓冲区且格式发生变化,系统会自动重新申请缓冲区。
- startCapture() 会将所有缓冲区加入队列,并通过 VIDIOC_STREAMON 启动视频流。
在 loop() 中,每次取出一帧并进行处理,随后让对象离开其作用域:
ESPVideoBufferClass frame = capture.captureBuffer();
if (frame.valid()) {
uint8_t *pixels = frame.data();
size_t nbytes = frame.size();
// process the frame
}
// destructor re-queues the buffer
ESPVideoBufferClass 是对单个已出队缓冲区的 RAII 封装。当对象被销毁、发生移动后失去资源所有权,或调用 end() 时,缓冲区会通过 VIDIOC_QBUF 返回驱动。请勿在对象生命周期结束后继续保存或使用 data() 返回的数据。如果一直持有缓冲区而不释放,captureBuffer() 将发生阻塞。
使用 Arduino IDE 快速入门
需要准备:
- Arduino IDE 2.x
- 包含 ESP_Video 库的 Arduino Core for ESP32(Core 3.3.10 或更高版本)
- 带摄像头的受支持开发板:ESP32-P4-Function-EV-Board(MIPI-CSI 或 DVP)或 ESP32-S3-EYE (DVP)
- 一根 USB 数据线
如果尚未安装 ESP32 开发板包,请参考《Getting Started with ESP32 Arduino》。如果希望在 ESP_Video 合入稳定版本之前使用包含该功能的最新 Core,可使用 development 版 Board Manager URL:
https://espressif.github.io/arduino-esp32/package_esp32_dev_index.json
选择开发板
- 通过 USB 连接开发板。
- 在 Arduino IDE 中,打开 Tools > Board > esp32,并选择与硬件匹配的开发板,例如 ESP32P4 Core Board。
- 如果 Tools 菜单中提供 PSRAM 选项,请启用 PSRAM。摄像头帧数据较大,如果没有 PSRAM,缓冲区分配很可能失败。
- 选择对应的串口 Port。

在 Tools > Board 中选择与硬件匹配的开发板
打开官方示例
库中的示例已经能够持续输出有效视频帧,因此开发者无需从空白驱动初始化开始。在 Arduino IDE 中打开 File > Examples > ESP_Video,并选择与摄像头接口对应的 Sketch:
- mipi_csi_camera - 用于 ESP32-P4-Function-EV-Board V1.5 的 MIPI-CSI
- dvp_camera - 用于 ESP32-S3-EYE 或 ESP32-P4-Function-EV-Board V1.5 的 DVP

打开文件>示例>ESP_Video,选择与所使用的摄像头接口相匹配的示例程序。
每个示例程序开头定义的引脚均与对应开发板相匹配。如果摄像头采用不同的引脚连接方式,请在上传程序前修改 EXAMPLE_* 宏定义。
在 ESP32-P4 上,MIPI-CSI 示例的 CI 配置使用 16 MB Flash 和较大的分区方案。如果默认分区空间不足以容纳应用程序和帧缓冲区,可在工具>Partition Scheme(分区方案) 中选择更大的分区方案。
上传程序并查看帧数据
- 点击上传 (Upload)。
- 打开工具>串口监视器 (Tools > Serial Monitor),将波特率设置为115200。
- 出现 Arduino camera example started 后,串口监视器将逐帧输出一行信息,包括缓冲区指针、大小、格式名称、宽度和高度。

串口监视器设置为 115200 baud:每取出一帧,输出一行 log
成功运行后,输出示例如下(具体数值取决于传感器和格式):
Arduino camera example started
captured buffer: 0x3c0a0000 size: 614400 format: RGB565 width: 640 height: 480
captured buffer: 0x3c110000 size: 614400 format: RGB565 width: 640 height: 480
具体地址取决于 PSRAM 布局。如果初始化失败,Sketch 会输出 failed to init CSI camera / failed to init DVP camera 或 failed to open capture device,然后在 loop() 中等待。此时应再次检查开发板选择、PSRAM、SCCB 引脚,以及是否连接了受支持的传感器。
重要提示
只有在 CONFIG_ESP_VIDEO_ENABLE_MIPI_CSI_VIDEO_DEVICE 或 CONFIG_ESP_VIDEO_ENABLE_DVP_VIDEO_DEVICE 至少有一项启用时,ESP_Video.h 中的公共 API 才会被编译。在示例使用的默认 SDK 配置中,Arduino Core 已为 ESP32-P4 和 ESP32-S3 启用这些选项。如果将 Arduino 作为 ESP-IDF 组件,并使用自定义 sdkconfig 进行构建,需要启用相应选项。
在 ESP32-P4 上进行 MIPI-CSI 采集
本节以 mipi_csi_camera.ino 为例进行说明。默认接线对应 ESP32-P4-Function-EV-Board V1.5 的 MIPI-CSI 摄像头:SCCB 使用 I2C 端口0,SCL 为 GPIO 8,SDA 为 GPIO 7。
配置 SCCB 和 CSI
ESPVideoCamConfigClass cam_config;
cam_config.begin(EXAMPLE_MIPI_CSI_SCCB_I2C_PORT,
EXAMPLE_MIPI_CSI_SCCB_I2C_SCL_PIN,
EXAMPLE_MIPI_CSI_SCCB_I2C_SDA_PIN);
ESPVideoCSIConfigClass csi_config;
csi_config.begin(cam_config);
if (!video.begin(csi_config)) {
Serial.println("failed to init CSI camera");
return;
}
video.begin (csi_config) 会初始化 MIPI-CSI 和 ISP (ESP_VIDEO_INIT_FLAGS_MIPI_CSI | ESP_VIDEO_INIT_FLAGS_ISP)。调用返回后,/dev/video0 设备节点即存在,传感器驱动也已通过 SCCB 探测摄像头。
打开设备、设置 RGB565 并启动视频流
const size_t kCaptureBufferCount = 2;
if (!capture_dev.begin(ESP_VIDEO_MIPI_CSI_DEVICE_NAME, kCaptureBufferCount)) {
Serial.println("failed to open capture device");
return;
}
if (!capture_dev.setFormat(ESP_VIDEO_FORMAT_RGB565)) {
Serial.println("failed to set format");
return;
}
if (!capture_dev.startCapture()) {
Serial.println("failed to start capture");
return;
}
RGB565 是一种便于预览的格式:每个像素占 2 字节,可方便地输出到 RGB565 LCD。如果传感器或 ISP 无法生成该格式,setFormat() 会返回 false。此时可尝试 ESP_VIDEO_FORMAT_YUV422_YUYV、ESP_VIDEO_FORMAT_JPEG,或者跳过 setFormat(),继续使用驱动默认格式。
在 loop() 中取出视频帧
void loop() {
if (!capture_dev.isOpened() || !capture_dev.isCaptureStarted()) {
delay(1000);
return;
}
ESPVideoBufferClass buffer = capture_dev.captureBuffer();
if (!buffer.valid()) {
Serial.println("failed to capture buffer");
delay(10);
return;
}
Serial.printf(
"captured buffer: %p size: %lu format: %s width: %lu height: %lu\n",
buffer.data(), (unsigned long)buffer.size(), buffer.formatName(),
(unsigned long)buffer.getWidth(), (unsigned long)buffer.getHeight());
}
以上即为应用侧完整的采集路径。开发者可将 Serial.printf 替换为预览显示、编码器或神经网络输入。ESPVideoBufferClass 对象仅应在处理当前这一帧期间保持有效。
完整 MIPI-CSI 示例
#include "Arduino.h"
#include <ESP_Video.h>
#define EXAMPLE_MIPI_CSI_SCCB_I2C_PORT 0
#define EXAMPLE_MIPI_CSI_SCCB_I2C_SCL_PIN 8
#define EXAMPLE_MIPI_CSI_SCCB_I2C_SDA_PIN 7
ESPVideoClass video;
ESPVideoCaptureDevClass capture_dev;
const size_t kCaptureBufferCount = 2;
void setup() {
Serial.begin(115200);
ESPVideoCamConfigClass cam_config;
cam_config.begin(EXAMPLE_MIPI_CSI_SCCB_I2C_PORT,
EXAMPLE_MIPI_CSI_SCCB_I2C_SCL_PIN,
EXAMPLE_MIPI_CSI_SCCB_I2C_SDA_PIN);
ESPVideoCSIConfigClass csi_config;
csi_config.begin(cam_config);
if (!video.begin(csi_config)) {
Serial.println("failed to init CSI camera");
return;
}
if (!capture_dev.begin(ESP_VIDEO_MIPI_CSI_DEVICE_NAME, kCaptureBufferCount)) {
Serial.println("failed to open capture device");
return;
}
if (!capture_dev.setFormat(ESP_VIDEO_FORMAT_RGB565)) {
Serial.println("failed to set format");
return;
}
if (!capture_dev.startCapture()) {
Serial.println("failed to start capture");
return;
}
Serial.println("Arduino camera example started");
}
void loop() {
if (!capture_dev.isOpened() || !capture_dev.isCaptureStarted()) {
delay(1000);
return;
}
ESPVideoBufferClass buffer = capture_dev.captureBuffer();
if (!buffer.valid()) {
Serial.println("failed to capture buffer");
delay(10);
return;
}
Serial.printf(
"captured buffer: %p size: %lu format: %s width: %lu height: %lu\n",
buffer.data(), (unsigned long)buffer.size(), buffer.formatName(),
(unsigned long)buffer.getWidth(), (unsigned long)buffer.getHeight());
}
在 ESP32-S3 或 ESP32-P4 上进行 DVP 采集
dvp_camera.ino 遵循相同的流程。额外步骤是在配置 ESPVideoDVPConfigClass 之前,先填充 ESPVideoDVPPinsConfigClass。
默认引脚映射如下:


配置 SCCB、引脚和 DVP
ESPVideoCamConfigClass cam_config;
cam_config.begin(EXAMPLE_DVP_SCCB_I2C_PORT,
EXAMPLE_DVP_SCCB_I2C_SCL_PIN,
EXAMPLE_DVP_SCCB_I2C_SDA_PIN);
ESPVideoDVPPinsConfigClass dvp_pins;
dvp_pins.begin(
EXAMPLE_DVP_VSYNC_PIN, EXAMPLE_DVP_DE_PIN,
EXAMPLE_DVP_PCLK_PIN, EXAMPLE_DVP_XCLK_PIN,
EXAMPLE_DVP_D0_PIN, EXAMPLE_DVP_D1_PIN, EXAMPLE_DVP_D2_PIN, EXAMPLE_DVP_D3_PIN,
EXAMPLE_DVP_D4_PIN, EXAMPLE_DVP_D5_PIN, EXAMPLE_DVP_D6_PIN, EXAMPLE_DVP_D7_PIN);
ESPVideoDVPConfigClass dvp_config;
dvp_config.begin(cam_config, dvp_pins, EXAMPLE_DVP_XCLK_FREQ);
if (!video.begin(dvp_config)) {
Serial.println("failed to init DVP camera");
return;
}
打开 /dev/video2 并开始采集
if (!capture_dev.begin(ESP_VIDEO_DVP_DEVICE_NAME, kCaptureBufferCount)) {
Serial.println("failed to open capture device");
return;
}
if (!capture_dev.startCapture()) {
Serial.println("failed to start capture");
return;
}
DVP 示例不会调用 setFormat(),而是保留驱动默认格式。如果需要指定 fourcc,仍可在 begin() 之后调用 setFormat()。loop() 与 MIPI-CSI Sketch 相同:取出视频帧、打印元数据并释放缓冲区。
像素格式
在 begin() 之后,可使用 esp_video_format_t 值调用 setFormat()。传感器实际支持的格式取决于具体驱动和当前视频设备。有关枚举、V4L2 fourcc 映射和格式名称字符串,请参阅 Arduino ESP32 文档中的 Pixel format。
传感器控制
采集设备打开后,可以调整增益、曝光、翻转、JPEG 质量等参数。如果驱动接受所设置的值,对应方法会返回 true。具体支持情况取决于传感器和当前格式。完整的 setSensor*() 方法列表及 V4L2 控制项映射,请参阅 Arduino ESP32 文档中的 Sensor controls。
capture.setSensorGain(16);
capture.setSensorExposure(800);
capture.setSensorVFlip(true);
capture.setSensorHFlip(false);
capture.setSensorJPEGQuality(12);
在新开发板调试阶段,测试图案非常有用:如果 setSensorTestPattern (true) 能输出已知图像,说明像素总线工作正常,此时可分别排查 SCCB 或 ISP 配置。
进一步开发
本文示例仅演示到打印视频帧元数据。完成这一阶段后,开发者还可以:
- 将 RGB565 视频帧显示到 LCD 上,实现本地预览
- 将 YUV 或 RGB 缓冲区输入 ESP-WHO 或 ESP-DL,用于目标检测和识别
- 采集 JPEG 静态图像,并通过 HTTP 提供图像服务,整体思路与 CameraWebServer 类似
- 在 ESP32-P4 上构建 Matter 摄像头产品,具体可参阅 Introducing Matter Cameras
完整的类和方法参考:
- ESP Video API(Arduino ESP32 文档)
- ESP_Video 库源码和示例
- ESP-Video-Components:用于了解 IDF 侧架构、受支持的传感器及 ISP 调优
总结
本文介绍了面向 ESP32-P4 和 ESP32-S3 的 Arduino 摄像头栈 ESP_Video,包括带片上 ISP 的 MIPI-CSI、DVP,以及可在 setup() 和 loop() 中使用的 V4L2 风格采集循环。文章首先说明如何在 Arduino IDE 中运行官方示例,以确认能够持续获取有效视频帧;随后进一步介绍这些 Sketch 如何配置 SCCB 和像素总线、打开设备节点,并取出采用 RAII 机制管理的缓冲区。像素格式和传感器控制的完整接口已在 Arduino ESP32 API 文档中提供,因此本文重点聚焦于从成功采集视频帧到将其用于实际应用的完整路径。
该路径从 loop() 开始。示例会输出指针、大小、格式和分辨率;在 ESPVideoBufferClass 对象仍处于作用域内时,同一个对象还可用于其他不同的帧处理方式。
本地预览是最直接的下一步。RGB565 每个像素占 2 字节,可较方便地映射到多种 LCD:将 data() 返回的数据按 getWidth() x getHeight() 的图像尺寸输出,随后由缓冲区析构函数将对应槽位返还驱动。如果显示面板需要不同的格式或方向,可继续使用前文采集流程中已介绍的 setFormat()、setSensorVFlip() / setSensorHFlip()。
计算机视觉也采用相同的数据交接方式。YUV 或 RGB 视频帧可直接输入 ESP-WHO 或 ESP-DL,在设备端完成检测和识别,无需经过 PC。JPEG 静态图像则可由传感器或 ISP 进行编码,再通过 HTTP 提供图像服务,整体思路与 CameraWebServer 类似。在 ESP32-P4 上,同一套摄像头栈也可作为 Matter 摄像头产品的基础,具体可参阅 Introducing Matter Cameras。
当视频帧能够稳定获取后,后续重点就不再是驱动初始化,而是选择合适的格式、尽量缩短缓冲区持有时间,并将像素数据接入预览、推理、Web UI 或智能家居数据链路。
本文介绍ESP32 Arduino Core中ESP_Video库的使用方法,重点涵盖MIPI-CSI与DVP两种摄像头接口的硬件配置、V4L2风格视频采集流程、SCCB传感器控制、RGB565/YUV/JPEG等像素格式支持,以及在ESP32-P4和ESP32-S3平台上的Arduino IDE快速部署与帧处理实践。
1619

被折叠的 条评论
为什么被折叠?



