Camera API

Xedge32 includes the ESP32 camera driver together with a Lua interface for capturing images from supported camera modules. This API is typically used on boards such as ESP32-CAM and ESP32-S3 camera variants where the camera wiring is fixed by the board design.

The basic workflow is:

Create a camera object with esp32.cam(cfg).
Call cam:read() whenever you want a frame.
Call cam:close() when you are finished.

Note

The camera API is still evolving, so this page focuses on the currently documented setup and configuration model.

There are two camera paths in the firmware:

classic ESP32/ESP32-S3 camera support using the ESP-IDF camera driver and a parallel camera pin map, and
ESP32-P4 camera support using the V4L2/PPA pipeline.

Use the section that matches your target board.

Creating a Camera Object

Function signature:

cam, err = esp32.cam(cfg)

Parameters

cfg: Configuration table describing the camera pin mapping and runtime options.

Return Values

On success, returns a camera object.
On failure, returns nil, error message.

Camera Object Methods

`cam:read()`

Captures and returns a new image from the camera.

`cam:close()`

Closes the camera object and releases the associated hardware resources.

Configuration Table

The configuration table maps the camera’s parallel data bus and control signals to GPIO pins on the ESP32. In most cases, you copy the mapping used by your specific board design and only adjust optional settings when needed.

Required fields

d0 to d7: Pixel data pins.
xclk: Camera master clock output.
pclk: Pixel clock input.
vsync: Vertical synchronization signal.
href: Horizontal reference signal.
sda: SCCB data line.
scl: SCCB clock line.
reset: Camera reset pin.
freq: XCLK frequency, typically between 10 MHz and 20 MHz.

Optional fields

pwdn: Camera power-down pin.
frame: Frame size, for example "HD".
format: Pixel format such as "RGB565", "YUV422", "GRAYSCALE", or "JPEG".
vflip: Boolean that flips the image vertically.
hmirror: Boolean that mirrors the image horizontally.

Configuration Examples

-- Seeed Studio XIAO ESP32S3 Sense
local cfg = {
   d0 = 15, d1 = 17, d2 = 18, d3 = 16, d4 = 14, d5 = 12, d6 = 11, d7 = 48,
   xclk = 10, pclk = 13, vsync = 38, href = 47, sda = 40, scl = 39, pwdn = -1,
   reset = -1, freq = 20000000, frame = "HD"
}

-- Aideepen ESP32-CAM
local cfg = {
   d0 = 5, d1 = 18, d2 = 19, d3 = 21, d4 = 36, d5 = 39, d6 = 34, d7 = 35,
   xclk = 0, pclk = 22, vsync = 25, href = 23, sda = 26, scl = 27, pwdn = 32,
   reset = -1, freq = 20000000, frame = "HD"
}

-- FREENOVE ESP32-S3 WROOM
local cfg = {
   d0 = 11, d1 = 9, d2 = 8, d3 = 10, d4 = 12, d5 = 18, d6 = 17, d7 = 16,
   xclk = 15, pclk = 13, vsync = 6, href = 7, sda = 4, scl = 5, pwdn = -1,
   reset = -1, freq = 20000000, frame = "HD"
}

ESP32-P4 Configuration

On ESP32-P4 builds, esp32.cam(cfg) uses a V4L2/PPA camera pipeline. The configuration is shorter because the driver negotiates the video pipeline and uses width/height settings instead of the full classic parallel pin map.

Common ESP32-P4 fields:

scl: SCCB/I2C clock pin. Default is 8.
sda: SCCB/I2C data pin. Default is 7.
xclk: Camera master clock pin. Default is 22.
format: "JPEG", "YUV422", or "RGB565".
width and height: Requested frame size in pixels.
frame: Convenience size when width/height are not supplied. Supported values include "QVGA", "VGA", "SVGA", and "HD".
quality: JPEG quality from 1 to 100 when JPEG output is used.
vflip and hmirror: Flip or mirror the final image.

Example:

local cam, err = esp32.cam{
   format = "JPEG",
   frame = "VGA",
   quality = 80,
   sda = 7,
   scl = 8,
   xclk = 22
}

if cam then
   local jpg = cam:read()
   trace("JPEG bytes:", #jpg)
   cam:close()
else
   trace(err)
end

Practical Guidance

Start with a known-good pin map for your exact board.
If camera initialization fails, the first thing to verify is the board’s pin mapping.
If the image orientation is wrong, try vflip and hmirror before changing anything else.
Lower clock rates can sometimes improve stability during bring-up.
Camera support depends on the firmware build. If esp32.cam is not available, the current firmware was built without camera support.