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:

1. Create a camera object with ``esp32.cam(cfg)``.
2. Call ``cam:read()`` whenever you want a frame.
3. 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:

.. code-block:: lua

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

.. code-block:: lua

   -- 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:

.. code-block:: lua

   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.