MicroPython Camera API

To build your own MicroPython firmware with the camera API, you need to set up a build environment with the following requirements:

1. ESP-IDF: Version 5.2.3 is recommended.
2. MicroPython Repository: Clone the MicroPython repo (version 1.24 or higher, at least commit 92484d8).
3. Camera Driver: You must add the esp32-camera driver to your build. Add the following to your idf_component.yml file (e.g., in micropython/ports/esp32/main/idf_component.yml):

  espressif/esp32-camera:
    git: https://github.com/cnadler86/esp32-camera.git

4. Build Script: Use the provided ./build.sh script, passing the path to your MicroPython folder and the target board.

./build.sh -m path/to/micropython -b ESP32_GENERIC_S3

The standard API is imported from the camera module. For asynchronous support, use the acamera package.

Standard import:

from camera import Camera, GrabMode, PixelFormat, FrameSize, GainCeiling

Asyncio import:

from acamera import Camera, GrabMode, PixelFormat, FrameSize, GainCeiling

The camera uses the SCCB protocol (I2C) for sensor communication. By default, the camera creates and manages its own I2C bus. To share the I2C bus with other devices, pass an existing machine.I2C object to the Camera constructor.

Note: SoftI2C is not supported; use hardware I2C.

import machine
from camera import Camera

# 1. Create your own I2C object
i2c = machine.I2C(0, scl=22, sda=21, freq=400000)

# 2. Pass it to the camera (do not provide sda_pin/scl_pin)
cam = Camera(i2c=i2c, data_pins=..., pclk_pin=..., ...)

# 3. Use the same I2C object for other devices
devices = i2c.scan()
print(f"I2C devices found: {devices}")

# You can still use camera methods that use I2C
cam.saturation = 1

i2c = machine.I2C(0, scl=22, sda=21, freq=400000)
cam = Camera(i2c=i2c, data_pins=[...], pclk_pin=...)

Use reconfigure() to change camera settings after initialization. Supported optional arguments are:

• frame_size: Frame size as FrameSize
• pixel_format: Pixel format as PixelFormat
• grab_mode: Grab mode as GrabMode
• fb_count: Frame buffer count

cam.reconfigure(pixel_format=PixelFormat.JPEG, frame_size=FrameSize.QVGA, grab_mode=GrabMode.LATEST, fb_count=2)

The camera initializes automatically during construction unless init=False is passed. If initialization was skipped, call the init() method manually. Note that most settings can only be configured after initialization.

cam.init()

You can implement a non-asyncio polling loop to wait for a new frame using frame_available().

Img = bytes(cam.capture())
cam.free_buffer()
while not cam.frame_available():
    # Do other tasks while waiting
    pass
print('The frame is available now.')

To reduce latency (especially when fb_count=1), you can manually free the memoryview buffer. To do this safely, convert the captured memoryview to a bytes object first so the data is preserved before the buffer is deleted.

Img = bytes(cam.capture())  # Copy data to a bytes object
cam.free_buffer()          # Free the original memoryview

You can instantiate a Camera object using defaults (if using non-generic firmware or pre-configured boards) or by providing specific hardware pins and settings.

Using defaults:

cam = Camera()

With specific settings:

cam = Camera(pixel_format=PixelFormat.JPEG, frame_size=FrameSize.QVGA, jpeg_quality=90, fb_count=2, grab_mode=GrabMode.WHEN_EMPTY)

Using generic firmware (requires manual pin definition):

cam = Camera(
    data_pins=[1,2,3,4,5,6,7,8],
    vsync_pin=9,
    href_pin=10,
    sda_pin=11,
    scl_pin=12,
    pclk_pin=13,
    xclk_pin=14,
    xclk_freq=20000000,
    powerdown_pin=-1,
    reset_pin=-1,
)