esp32-camera

ESP32 Camera Driver

General Information

This repository hosts ESP32 series Soc compatible driver for image sensors. Additionally it provides a few tools, which allow converting the captured frame data to the more common BMP and JPEG formats.

Supported Soc

• ESP32
• ESP32-S2
• ESP32-S3

Supported Sensor

model	max resolution	color type	output format	Len Size
OV2640	1600 x 1200	color	YUV(422/420)/YCbCr422 RGB565/555 8-bit compressed data 8/10-bit Raw RGB data	1/4"
OV3660	2048 x 1536	color	raw RGB data RGB565/555/444 CCIR656 YCbCr422 compression	1/5"
OV5640	2592 x 1944	color	RAW RGB RGB565/555/444 CCIR656 YUV422/420 YCbCr422 compression	1/4"
OV7670	640 x 480	color	Raw Bayer RGB Processed Bayer RGB YUV/YCbCr422 GRB422 RGB565/555	1/6"
OV7725	640 x 480	color	Raw RGB GRB 422 RGB565/555/444 YCbCr 422	1/4"
NT99141	1280 x 720	color	YCbCr 422 RGB565/555/444 Raw CCIR656 JPEG compression	1/4"
GC032A	640 x 480	color	YUV/YCbCr422 RAW Bayer RGB565	1/10"
GC0308	640 x 480	color	YUV/YCbCr422 RAW Bayer RGB565 Grayscale	1/6.5"
GC2145	1600 x 1200	color	YUV/YCbCr422 RAW Bayer RGB565	1/5"
BF3005	640 x 480	color	YUV/YCbCr422 RAW Bayer RGB565	1/4"
BF20A6	640 x 480	color	YUV/YCbCr422 RAW Bayer Only Y	1/10"
SC101IOT	1280 x 720	color	YUV/YCbCr422 Raw RGB	1/4.2"
SC030IOT	640 x 480	color	YUV/YCbCr422 RAW Bayer	1/6.5"
SC031GS	640 x 480	monochrome	RAW MONO Grayscale	1/6"
HM0360	656 x 496	monochrome	RAW MONO Grayscale	1/6"
HM1055	1280 x 720	color	8/10-bit Raw YUV/YCbCr422 RGB565/555/444	1/6"

Important to Remember

• Except when using CIF or lower resolution with JPEG, the driver requires PSRAM to be installed and activated.
• Using YUV or RGB puts a lot of strain on the chip because writing to PSRAM is not particularly fast. The result is that image data might be missing. This is particularly true if WiFi is enabled. If you need RGB data, it is recommended that JPEG is captured and then turned into RGB using fmt2rgb888 or fmt2bmp/frame2bmp.
• When 1 frame buffer is used, the driver will wait for the current frame to finish (VSYNC) and start I2S DMA. After the frame is acquired, I2S will be stopped and the frame buffer returned to the application. This approach gives more control over the system, but results in longer time to get the frame.
• When 2 or more frame buffers are used, I2S is running in continuous mode and each frame is pushed to a queue that the application can access. This approach puts more strain on the CPU/Memory, but allows for double the frame rate. Please use only with JPEG.
• The Kconfig option CONFIG_CAMERA_PSRAM_DMA enables PSRAM DMA mode on ESP32-S2 and ESP32-S3 devices. This flag defaults to false.
• You can switch PSRAM DMA mode at runtime using esp_camera_set_psram_mode().

Installation Instructions

Using with ESP-IDF

• Add a dependency on espressif/esp32-camera component:

  idf.py add-dependency "espressif/esp32-camera"
  

  (or add it manually in idf_component.yml of your project)
• Enable PSRAM in menuconfig (also set Flash and PSRAM frequiencies to 80MHz)
• Include esp_camera.h in your code

These instructions also work for PlatformIO, if you are using framework=espidf.

Using with Arduino

Arduino IDE

If you are using the arduino-esp32 core in Arduino IDE, no installation is needed! You can use esp32-camera right away.

PlatformIO

The easy way -- on the env section of platformio.ini, add the following:

[env]
lib_deps =
  esp32-camera

Now the esp_camera.h is available to be included:

#include "esp_camera.h"

Enable PSRAM on menuconfig or type it directly on sdkconfig. Check the official doc for more info.

CONFIG_ESP32_SPIRAM_SUPPORT=y

Examples

This component comes with a basic example illustrating how to get frames from the camera. You can try out the example using the following command:

idf.py create-project-from-example "espressif/esp32-camera:camera_example"

This command will download the example into camera_example directory. It comes already pre-configured with the correct settings in menuconfig.

Initialization

…

JPEG HTTP Capture

…

JPEG HTTP Stream

…

BMP HTTP Capture

…

Autofocus (OV5640)

This component includes an optional autofocus helper for OV5640 modules that have an AF-capable lens.

• Enable it in menuconfig: Component config → Camera configuration → Enable autofocus (OV5640).
• Include the header: #include "esp_camera_af.h".

Basic usage:

#include "esp_camera.h"
#include "esp_camera_af.h"

// After esp_camera_init(...)
sensor_t *s = esp_camera_sensor_get();

esp_camera_af_config_t af_cfg = {
    .mode = ESP_CAMERA_AF_MODE_AUTO,
    .timeout_ms = 2000,
};

ESP_ERROR_CHECK(esp_camera_af_init(s, &af_cfg));

// Optional: trigger a single AF cycle and wait for completion
ESP_ERROR_CHECK(esp_camera_af_trigger(s));

esp_camera_af_status_t st;
ESP_ERROR_CHECK(esp_camera_af_wait(s, 0, &st));

Notes:

• If autofocus is disabled (or the sensor is not OV5640), the AF APIs return ESP_ERR_NOT_SUPPORTED.
• OV5640 autofocus relies on loading an internal firmware blob over SCCB during esp_camera_af_init().