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.

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"
}

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.