Camera (camera)

[中文]

Overview

The camera device describes a camera sensor and its data interface. After initialization, it returns a dev_camera_handle_t. This handle stores the video device path, which applications can use to capture image data via the V4L2 path.

This type selects the camera interface via sub_type. The current device template covers dvp, csi, and spi; a usb_uvc placeholder structure is reserved in the header file, but no board-level YAML is provided for USB-UVC in the device template.

Supported Usage Modes

camera is categorized by sub_type:

Minimal Configuration

DVP (sub_type: dvp)

dvp mode uses the LCD_CAM DVP controller with parallel data lines. board_peripherals.yaml requires at least an i2c peripheral that can be referenced by the camera’s SCCB control interface.

board_devices.yaml:

devices:
  - name: camera
    type: camera
    sub_type: dvp
    config:
      dvp_config:
        reset_io: -1                 # [IO]
        pwdn_io: -1                  # [IO]
        vsync_io: 21                 # [IO]
        data_width: "CAM_CTLR_DATA_WIDTH_8"
        de_io: 38                    # [TO_BE_CONFIRMED]
        pclk_io: 11                  # [TO_BE_CONFIRMED]
        xclk_io: 40                  # [TO_BE_CONFIRMED]
        xclk_freq: 10000000          # [TO_BE_CONFIRMED]
        data_io:
          data_io_0: 13              # [IO]
          data_io_1: 47              # [IO]
          data_io_2: 14              # [IO]
          data_io_3: 3               # [IO]
          data_io_4: 12              # [IO]
          data_io_5: 42              # [IO]
          data_io_6: 41              # [IO]
          data_io_7: 39              # [IO]
    peripherals:
      - name: i2c_master
        frequency: 100000

CSI (sub_type: csi)

csi mode uses the MIPI CSI path. board_peripherals.yaml requires at least an i2c peripheral; when dont_init_ldo: true and the MIPI LDO is managed by BMGR, an ldo peripheral must also be configured.

board_devices.yaml:

devices:
  - name: camera
    type: camera
    sub_type: csi
    config:
      csi_config:
        reset_io: 1                  # [IO]
        pwdn_io: 2                   # [IO]
        dont_init_ldo: true          # [TO_BE_CONFIRMED]
        xclk_config:
          xclk_pin: -1               # [IO]
          xclk_freq_hz: 20000000     # [TO_BE_CONFIRMED]
    peripherals:
      - name: i2c_master
        frequency: 100000
      - name: ldo_mipi

SPI Camera (sub_type: spi)

spi mode uses esp_video_init_spi_config_t to describe the connection, and the i2c peripheral provides the SCCB handle during initialization. board_peripherals.yaml requires at least an i2c peripheral that can be referenced by the SCCB control interface; the SPI camera data interface GPIOs are written in the device’s spi_config and do not reference the spi peripheral. Camera initialization looks up the sub-device entry by sub_type; spi mode internally maps to the camera_spi sub-entry to avoid name conflicts with other devices’ spi sub-entries.

board_devices.yaml:

devices:
  - name: camera
    type: camera
    sub_type: spi
    config:
      spi_config:
        intf: ESP_CAM_CTLR_SPI_CAM_INTF_SPI
        io_mode: ESP_CAM_CTLR_SPI_CAM_IO_MODE_1BIT
        spi_port: 1                  # [TO_BE_CONFIRMED]
        spi_cs_pin: 10               # [IO]
        spi_sclk_pin: 11             # [IO]
        spi_data0_io_pin: 12         # [IO]
        spi_data1_io_pin: -1         # [IO]
        reset_pin: -1                # [IO]
        pwdn_pin: -1                 # [IO]
        xclk_source: ESP_CAM_SENSOR_XCLK_LEDC
        xclk_freq: 20000000          # [TO_BE_CONFIRMED]
        xclk_pin: 13                 # [IO]
        xclk_ledc_cfg:
          timer: 0                   # [TO_BE_CONFIRMED]
          clk_cfg: LEDC_AUTO_CLK     # [TO_BE_CONFIRMED]
          channel: 0                 # [TO_BE_CONFIRMED]
    peripherals:
      - name: i2c_master
        frequency: 100000

Full Field Reference

DVP Full Fields

# Example board_devices.yaml configuration for camera device
# This shows how to integrate the camera device into a board configuration
# Please note that multiple cameras are not currently supported on the same board
# All values shown are example values for DVP and CSI interface configuration

# Example camera device configuration
- name: camera         # The name of the device, must be unique
  type: camera         # The type of the camera, must be equal to "camera"
  sub_type: dvp        # The bus type: dvp
  config:
    # DVP interface configuration (used when sub_type is "dvp")
    dvp_config:
      reset_io: -1        # [IO] GPIO pin for reset signal (default: -1, not connected)
      pwdn_io: -1         # [IO] GPIO pin for power down signal (default: -1, not connected)
      vsync_io: 21        # [IO] GPIO pin for vertical sync signal (default: depends on implementation)
      data_width: "CAM_CTLR_DATA_WIDTH_8"  # [TO_BE_CONFIRMED] Data width configuration:
                                           # CAM_CTLR_DATA_WIDTH_8
                                           # CAM_CTLR_DATA_WIDTH_10
                                           # CAM_CTLR_DATA_WIDTH_12
                                           # CAM_CTLR_DATA_WIDTH_16
      de_io: 38            # [TO_BE_CONFIRMED] GPIO pin for data enable signal (default: depends on implementation)
      pclk_io: 11          # [TO_BE_CONFIRMED] GPIO pin for pixel clock signal (default: depends on implementation)
      xclk_io: 40          # [TO_BE_CONFIRMED] GPIO pin for external clock output (default: depends on implementation)
      xclk_freq: 10000000  # [TO_BE_CONFIRMED] External clock frequency in Hz (default: 10MHz)
      data_io:
        data_io_0: 13      # [IO] GPIO pin for data bit 0 (default: depends on implementation)
        data_io_1: 47      # [IO] GPIO pin for data bit 1 (default: depends on implementation)
        data_io_2: 14      # [IO] GPIO pin for data bit 2 (default: depends on implementation)
        data_io_3: 3       # [IO] GPIO pin for data bit 3 (default: depends on implementation)
        data_io_4: 12      # [IO] GPIO pin for data bit 4 (default: depends on implementation)
        data_io_5: 42      # [IO] GPIO pin for data bit 5 (default: depends on implementation)
        data_io_6: 41      # [IO] GPIO pin for data bit 6 (default: depends on implementation)
        data_io_7: 39      # [IO] GPIO pin for data bit 7 (default: depends on implementation)
        data_io_8: -1      # [IO] GPIO pin for data bit 8 (default: -1, not used in 8-bit mode)
        data_io_9: -1      # [IO] GPIO pin for data bit 9 (default: -1, not used in 8-bit mode)
        data_io_10: -1     # [IO] GPIO pin for data bit 10 (default: -1, not used in 8-bit mode)
        data_io_11: -1     # [IO] GPIO pin for data bit 11 (default: -1, not used in 8-bit mode)
        data_io_12: -1     # [IO] GPIO pin for data bit 12 (default: -1, not used in 8-bit mode)
        data_io_13: -1     # [IO] GPIO pin for data bit 13 (default: -1, not used in 8-bit mode)
        data_io_14: -1     # [IO] GPIO pin for data bit 14 (default: -1, not used in 8-bit mode)
        data_io_15: -1     # [IO] GPIO pin for data bit 15 (default: -1, not used in 8-bit mode)

  # I2C configuration for camera control (For the USB-UVC camera, this configuration is not required)
  peripherals:
    - name: i2c_master     # [TO_BE_CONFIRMED] I2C bus name for camera control (default: depends on implementation)
      frequency: 100000    # I2C frequency in Hz (default: 400kHz)

CSI Full Fields

# Example CSI camera configuration
- name: camera             # The name of the device, must be unique
  type: camera             # The type of the camera, must be equal to "camera"
  sub_type: "csi"          # The bus type: csi
  config:
    # CSI interface configuration (used when sub_type is "csi")
    csi_config:
      reset_io: 1           # [IO] GPIO pin for reset signal (example value)
      pwdn_io: 2            # [IO] GPIO pin for power down signal (example value)
      dont_init_ldo: true   # [TO_BE_CONFIRMED] If true, MIPI-CSI video device will not initialize the LDO (default: true)
                            # If using the periph_ldo in esp_board_manager to manage the ldo peripheral, it needs to be set to true
      xclk_config:
        xclk_pin: -1        # [IO] GPIO pin for camera XCLK signal (default: -1, not connected)
        xclk_freq_hz: 20000000 # [TO_BE_CONFIRMED] XCLK frequency in Hz (default: 20MHz)

  # I2C configuration for camera control
  peripherals:
    - name: i2c_master      # [TO_BE_CONFIRMED] I2C bus name for camera control
      frequency: 100000     # I2C frequency in Hz
    - name: ldo_mipi        # [TO_BE_CONFIRMED] LDO peripheral for csi power management

SPI Camera Full Fields

# Example SPI camera configuration
# CONFIG_CAMERA_XCLK_USE_LEDC: required when xclk_source is ESP_CAM_SENSOR_XCLK_LEDC (xclk_ledc_cfg used).
- name: camera
  type: camera
  sub_type: spi
  config:
    spi_config:
      # esp_video_init_spi_config_t (esp_video_init.h), excluding sccb_config (filled at init from periph_i2c).
      # SPI CAM interface type: ESP_CAM_CTLR_SPI_CAM_INTF_SPI or ESP_CAM_CTLR_SPI_CAM_INTF_PARLIO
      intf: ESP_CAM_CTLR_SPI_CAM_INTF_SPI
      # SPI CAM data I/O mode (SPI interface only supports 1-bit): ESP_CAM_CTLR_SPI_CAM_IO_MODE_1BIT / _2BIT
      io_mode: ESP_CAM_CTLR_SPI_CAM_IO_MODE_1BIT
      spi_port: 1                         # [TO_BE_CONFIRMED] SPI port
      spi_cs_pin: 10                      # [IO] SPI CS pin
      spi_sclk_pin: 11                    # [IO] SPI SCLK pin
      spi_data0_io_pin: 12                # [IO] SPI data0 I/O pin
      # SPI data1 I/O pin (only required when io_mode is ESP_CAM_CTLR_SPI_CAM_IO_MODE_2BIT, set to -1 if not used)
      spi_data1_io_pin: -1                # [IO] SPI data1 I/O pin
      # SPI interface camera sensor reset pin, if hardware has no reset pin, set reset_pin to be -1
      reset_pin: -1                       # [IO] SPI interface camera sensor reset pin
      # SPI interface camera sensor power down pin, if hardware has no power down pin, set pwdn_pin to be -1
      pwdn_pin: -1                       # [IO] SPI interface camera sensor power down pin
      # Output clock resource / frequency / pin for SPI interface camera sensor
      xclk_source: ESP_CAM_SENSOR_XCLK_LEDC
      xclk_freq: 20000000                # [TO_BE_CONFIRMED] XCLK frequency in Hz (default: 20MHz)
      xclk_pin: 13                       # [IO] XCLK pin
      # Used when xclk_source is ESP_CAM_SENSOR_XCLK_LEDC (ledc_timer_t / ledc_clk_cfg_t / ledc_channel_t)
      xclk_ledc_cfg:
        timer: 0                          # [TO_BE_CONFIRMED] The timer source of channel
        clk_cfg: LEDC_AUTO_CLK            # [TO_BE_CONFIRMED] LEDC source clock from ledc_clk_cfg_t
        channel: 0                        # [TO_BE_CONFIRMED] LEDC channel used for XCLK
  peripherals:
    - name: i2c_master                   # Must match a periph_i2c name; provides SCCB i2c_handle to esp_video
      frequency: 100000                   # SCCB I2C frequency (Hz)

Component Dependencies

dev_camera.yaml does not declare dependencies in the device entry. Camera sub-types depend on header files, drivers, and target-chip capabilities related to ESP-IDF and esp_video; boards do not need to add non-existent dependency fields in this device YAML.

Required Peripherals

peripheral type

role / format

Required

Purpose

i2c

master

Required for dvp, csi, and spi modes

Camera SCCB control interface

ldo

N/A

Required for csi when BMGR manages the MIPI LDO

MIPI CSI power management

Code Reference

  • esp_board_manager/test_apps/main/test_dev_camera.c: Obtains the camera device handle and captures images via the V4L2 device path.

  • esp_board_manager/devices/dev_camera/dev_camera_sub_dvp.c: DVP sub-type initialization implementation.

  • esp_board_manager/devices/dev_camera/dev_camera_sub_csi.c: CSI sub-type initialization implementation.

  • esp_board_manager/devices/dev_camera/dev_camera_sub_spi.c: SPI sub-type initialization implementation.

Board-level Reference

  • esp_board_manager/boards/esp_sparkbot/board_devices.yaml: dvp camera configuration.

  • esp_board_manager/boards/esp32_s3_korvo2_v3/board_devices.yaml: dvp camera configuration.

  • esp_board_manager/boards/esp32_p4_function_ev/board_devices.yaml: csi camera configuration.

  • esp_board_manager/boards/esp32_p4_function_ev/board_peripherals.yaml: i2c and ldo peripherals used by the csi camera.

  • esp_board_manager/boards/esp_sensair_halo/board_devices.yaml: spi camera configuration.

  • esp_board_manager/boards/m5stack_tab5/board_devices.yaml: Camera configuration.

Notes

  • The current device template comment states that configuring multiple cameras on the same board is not yet supported.

  • The i2c peripheral only provides the SCCB control handle; DVP, CSI, or SPI data lines are declared in the camera device configuration.

  • When spi mode uses ESP_CAM_SENSOR_XCLK_LEDC, the template requires enabling CONFIG_CAMERA_XCLK_USE_LEDC.

  • After modifying the camera device, I2C peripheral, or LDO peripheral configuration, re-run idf.py bmgr -b <board>.

Debugging Tips

API Reference

Use esp_board_manager_get_device_handle() to obtain the device handle. The handle type is dev_camera_handle_t:

typedef struct {
    const char *dev_path;   /*!< Camera device path or identifier */
    const char *meta_path;  /*!< Camera metadata path or identifier (if applicable) */
                            /*!< For CSI camera, meta_path is ISP path */
} dev_camera_handle_t;

dev_path and meta_path are device paths registered by the esp_video framework (e.g., /dev/video0), accessed via POSIX interfaces such as open().

Related declarations are in esp_board_manager/devices/dev_camera/dev_camera.h.

Was this page helpful?