Skip to content
Get started

ESP32 Camera Component

The esp32_camera component allows you to use ESP32-based camera boards in ESPHome that directly integrate into Home Assistant through the native API.

Requires an I2C and Psram to be configured.

# Example configuration entry
esp32_camera:
name: My Camera
external_clock:
pin: GPIOXX
frequency: 20MHz
i2c_id: my_i2c_bus
data_pins: [GPIOXX, GPIOXX, GPIOXX, GPIOXX, GPIOXX, GPIOXX, GPIOXX, GPIOXX]
vsync_pin: GPIOXX
href_pin: GPIOXX
pixel_clock_pin: GPIOXX
reset_pin: GPIOXX
resolution: 640x480
jpeg_quality: 10
  • name (Optional, string): The name of the camera.

  • icon (Optional, icon): Manually set the icon to use for the camera in the frontend.

  • internal (Optional, boolean): Mark this component as internal. Internal components will not be exposed to the frontend (like Home Assistant). Only specifying an id without a name will implicitly set this to true.

  • disabled_by_default (Optional, boolean): If true, then this entity should not be added to any client’s frontend, (usually Home Assistant) without the user manually enabling it (via the Home Assistant UI). Defaults to false.

  • entity_category (Optional, string): The category of the entity. See https://developers.home-assistant.io/docs/core/entity/#generic-properties for a list of available options. Set to "" to remove the default entity category.

Connection Options:

  • data_pins (Required, list of pins): The data lanes of the camera, this must be a list of 8 GPIO pins.

  • vsync_pin (Required, pin): The pin the VSYNC line of the camera is connected to.

  • href_pin (Required, pin): The pin the HREF line of the camera is connected to.

  • pixel_clock_pin (Required, pin): The pin the pixel clock line of the camera is connected to.

  • external_clock (Required): The configuration of the external clock to drive the camera.

    • pin (Required, pin): The pin the external clock line is connected to.
    • frequency (Optional, frequency): The frequency of the external clock, must be between 8MHz and 20MHz. Defaults to 20MHz.
  • i2c_id (Optional, ID): The ID of the I²C bus the camera is connected to.

  • reset_pin (Optional, pin): The ESP pin the reset pin of the camera is connected to. If set, this will reset the camera before the ESP boots.

  • power_down_pin (Optional, pin): The ESP pin to power down the camera. If set, this will power down the camera while it is inactive.

  • test_pattern (Optional, boolean): When enabled, the camera will show a test pattern that can be used to debug connection issues.

Frame Settings:

  • max_framerate (Optional, float): The maximum framerate the camera will generate images at. Up to 60Hz is possible (with reduced frame sizes), but beware of overheating. Defaults to 10 fps.

  • idle_framerate (Optional, float): The framerate to capture images at when no client is requesting a full stream. Defaults to 0.1 fps.

  • frame_buffer_count (Optional, int): The number of frame buffers to use when reading from the camera sensor. Must be between 1 and 2. Defaults to 1.

  • frame_buffer_location (Optional, enum): The memory area used for storing the frame buffers. Defaults to PSRAM.

    • PSRAM
    • DRAM

Image Settings:

  • resolution (Optional, enum): The resolution the camera will capture images at. Higher resolutions require more memory, if there’s not enough memory you will see an error during startup.

    • 160x120 (QQVGA, 4:3)
    • 176x144 (QCIF, 11:9)
    • 240x176 (HQVGA, 15:11)
    • 320x240 (QVGA, 4:3)
    • 400x296 (CIF, 50:37)
    • 640x480 (VGA, 4:3, default)
    • 800x600 (SVGA, 4:3)
    • 1024x768 (XGA, 4:3)
    • 1280x1024 (SXGA, 5:4)
    • 1600x1200 (UXGA, 4:3)
    • 1920x1080 (FHD, 16:9)
    • 720x1280 (Portrait HD, 9:16)
    • 864x1536 (Portrait 3MP, 9:16)
    • 2048x1536 (QXGA, 4:3)
    • 2560x1440 (QHD, 16:9)
    • 2560x1600 (WQXGA, 8:5)
    • 1080x1920 (Portrait FHD, 9:16)
    • 2560x1920 (QSXGA, 4:3)
  • pixel_format (Optional, enum): The pixel format to use for the images. Defaults to jpeg (JPEG compressed image) which may not be supported by all cameras. Other formats require more CPU and memory and may not be supported by all cameras.

    • jpeg: JPEG compressed image
    • rgb565: RGB565 uncompressed image
    • yuv422: YUV422 uncompressed image
    • yuv420: YUV420 uncompressed image
    • grayscale: Grayscale uncompressed image
    • rgb888: RGB888 uncompressed image
    • raw: Raw uncompressed image
    • rgb444: RGB444 uncompressed image
    • rgb555: RGB555 uncompressed image
  • jpeg_quality (Optional, int): The JPEG quality that the camera should encode images with. From 6 (best) to 63 (worst). Defaults to 10. Set this to 0 to disable JPEG compression/conversion. Manual JPEG compression/conversion requires psram component to be enabled and configured.

  • vertical_flip (Optional, boolean): Whether to flip the image vertically. Defaults to true.

  • horizontal_mirror (Optional, boolean): Whether to mirror the image horizontally. Defaults to true.

  • contrast (Optional, int): The contrast to apply to the picture, from -2 to 2. Defaults to 0.

  • brightness (Optional, int): The brightness to apply to the picture, from -2 to 2. Defaults to 0.

  • saturation (Optional, int): The saturation to apply to the picture, from -2 to 2. Defaults to 0.

  • special_effect (Optional, enum): The effect to apply to the picture. Defaults to none (picture without effect).

    • none : Picture without effect
    • negative : Colors of picture are inverted
    • grayscale : Only luminance of picture is kept
    • red_tint : Picture appear red-tinted
    • green_tint : Picture appear green-tinted
    • blue_tint : Picture appear blue-tinted
    • sepia : Sepia effect is applied to picture

Exposure Settings:

  • aec_mode (Optional, enum): The mode of exposure module. Defaults to auto (leave camera to automatically adjust exposure).

    • manual : Exposure can be manually set, with aec_value parameter. ae_level has no effect here
    • auto : Camera manage exposure automatically. Compensation can be applied, thanks to ae_level parameter. aec_value has no effect here
  • aec2 (Optional, boolean): Whether to enable Auto Exposure Control 2. Seems to change computation method of automatic exposure. Defaults to false.

  • ae_level (Optional, int): The auto exposure level to apply to the picture (when aec_mode is set to auto ), from -2 to 2. Defaults to 0.

  • aec_value (Optional, int): The Exposure value to apply to the picture (when aec_mode is set to manual ), from 0 to 1200. Defaults to 300.

Sensor Gain Settings:

  • agc_mode (Optional, enum): The mode of gain control module. Defaults to auto (leave camera to automatically adjust sensor gain).

    • manual : Gain can be manually set, with agc_value parameter. agc_gain_ceiling has no effect here
    • auto : Camera manage sensor gain automatically. Maximum gain can be defined, thanks to agc_gain_ceiling parameter. agc_value has no effect here
  • agc_value (Optional, int): The gain value to apply to the picture (when aec_mode is set to manual ), from 0 to 30. Defaults to 0.

  • agc_gain_ceiling (Optional, enum): The maximum gain allowed, when agc_mode is set to auto. This parameter seems act as “ISO” setting. Defaults to 2x.

    • 2x : Camera is less sensitive, picture is clean (without visible noise)
    • 4x
    • 8x
    • 16x
    • 32x
    • 64x
    • 128x : Camera is more sensitive, but picture contain lot of noise

White Balance Setting:

  • wb_mode (Optional, enum): The mode of white balance module. Defaults to auto.

    • auto : Camera choose best white balance setting
    • sunny : White balance sunny mode
    • cloudy : White balance cloudy mode
    • office : White balance office mode
    • home : White balance home mode

Single Image Settings:

  • capture_delay (Optional, Time): Wait this long before a single image and drop frames that started before the wait ended, so a light switched on in on_capture_start and the auto exposure can settle. 0s to 3s, defaults to 0s. With idle_framerate: 0 fps the first frame after an idle period is badly exposed, 500ms to 2s fixes that on an OV2640.

  • on_capture_start (Optional, Automation): Runs when a single image capture begins, for example to switch on a flash LED. Use actions that finish right away.

  • on_capture_end (Optional, Automation): Runs after the image was captured, also when a stream cancels the capture and on shutdown. If no frame that started after the delay arrived 4 seconds after on_capture_start, it runs as well and the next frame is used as is. The 4 seconds include capture_delay, so with 3s about one second is left. A light may stay on after shutdown, an output does not.

Only single images use these: Home Assistant snapshots (picture cards refresh every 10 seconds) and the snapshot mode of esp32_camera_web_server. Streams (the Home Assistant more-info dialog, the web server stream mode, rtsp_server clients) and idle_framerate captures skip them. While a stream runs, single images skip them as well and come straight from the stream. Otherwise each single image runs the whole cycle, so a picture card that refreshes every 10 seconds also switches the light every 10 seconds.

NOTE

With aec_mode: auto the sensor makes up for a weaker light, so the light level hardly changes the image. When the flash is the only light, set aec_mode: manual and tune aec_value and the light level together.

Automations:

Test Setting:

  • test_pattern (Optional, boolean): For tests purposes, it’s possible to replace picture get from sensor by a test color pattern. Defaults to false.

Window Setting:

  • window (Optional): Read out only part of the sensor at startup; see Reading Out a Window. Without it the whole sensor is read out.

    • offset_x (Required, int): Horizontal offset of the window in pixels, 0 or more.
    • offset_y (Required, int): Vertical offset of the window in pixels, 0 or more.
    • width (Required, int): Width of the window in pixels, 1 or more.
    • height (Required, int): Height of the window in pixels, 1 or more.

NOTE

The camera clock uses LEDC timer 0. Set channel: 2 on a ledc output, for example a flash LED. A frequency such as 5kHz avoids dark bands from the default 1 kHz.

A window restricts the readout to a rectangle of the picture, so the camera works as a digital zoom. The offsets count from the top left corner; what they are counted in depends on the sensor, as the table below shows.

esp32_camera:
# ...
window:
offset_x: 100
offset_y: 200
width: 320
height: 240
SensorWindow counted inPublished frameNotes
OV2640Pixels of the resolutionThe size of the windowJPEG output only, rounded to 16x8 blocks
OV3660, OV5640Pixels of the resolutionThe resolutionScaled down to the frame, so it also zooms in
SC101IOT, SC030IOTPixels of the whole sensor, 1280x720 or 640x480The resolutionwidth and height must be the resolution

A window that reaches past the edge is clamped to it. Because the window is counted in pixels of the resolution, set it again when you change the resolution. The OV3660 and OV5640 only scale down: a window that covers fewer sensor pixels than the frame has is rejected, so pick a larger window or a lower resolution. On the SC101IOT and SC030IOT a window whose size is not the resolution is rejected. Other sensors cannot read out a window: setting one fails, and a window in the configuration is skipped with a warning at startup.

A new window replaces the previous one and never nests inside it. Changing the frame size at runtime, from a lambda, clears the window, so set it again afterwards. If a window cannot be applied, the previous one stays in place.

Reads out a window at runtime, with the same options as window above. Each value can be a lambda.

on_...:
then:
- esp32_camera.set_window:
id: my_camera
offset_x: 300
offset_y: 100
width: 320
height: 240
  • id (Required, ID): The camera.
  • offset_x, offset_y, width, height (Required, templatable, int): The window, as for the window option.

Reads out the whole sensor again.

on_...:
then:
- esp32_camera.reset_window: my_camera
  • id (Required, ID): The camera.

Ai-Thinker Camera:

WARNING

GPIO16 on this board (and possibly other boards below) is connected to onboard PSRAM. Using this GPIO for other purposes (eg as a button) will trigger the watchdog. Further information on pin notes can be found here: https://github.com/raphaelbs/esp32-cam-ai-thinker/blob/master/docs/esp32cam-pin-notes.md

# Example configuration entry
i2c:
- id: camera_i2c
sda: GPIO26
scl: GPIO27
esp32_camera:
external_clock:
pin: GPIO0
frequency: 20MHz
i2c_id: camera_i2c
data_pins: [GPIO5, GPIO18, GPIO19, GPIO21, GPIO36, GPIO39, GPIO34, GPIO35]
vsync_pin: GPIO25
href_pin: GPIO23
pixel_clock_pin: GPIO22
power_down_pin: GPIO32
# Image settings
name: My Camera
# ...

Ai-Thinker Camera with flash LED:

The flash LED of this board sits on GPIO4. Any other GPIO works the same way through the pin of the output. The LED gets hot and draws a lot of current, so keep the level below full power.

# Example configuration entry
output:
- platform: ledc
id: flash_led
pin: GPIO4
channel: 2
frequency: 5kHz
esp32_camera:
# Pins as in the Ai-Thinker example above
# ...
name: Meter Camera
resolution: 1600x1200
jpeg_quality: 10
idle_framerate: 0 fps
aec_mode: manual
aec_value: 300
capture_delay: 2s
on_capture_start:
- output.set_level:
id: flash_led
level: 50%
on_capture_end:
- output.turn_off: flash_led

Camera with an LED ring:

# Example configuration entry
light:
- platform: esp32_rmt_led_strip
id: led_ring
# ...
esp32_camera:
# ...
capture_delay: 1s
on_capture_start:
- light.turn_on:
id: led_ring
brightness: 60%
transition_length: 0s
on_capture_end:
- light.turn_off:
id: led_ring
transition_length: 0s

M5Stack Camera:

WARNING

This camera board has insufficient cooling and will overheat over time, ESPHome does only activate the camera when Home Assistant requests an image, but the camera unit can still heat up considerably for some boards.

If the camera is not recognized after a reboot and the unit feels warm, try waiting for it to cool down and check again - if that still doesn’t work try enabling the test pattern.

# Example configuration entry
i2c:
- id: camera_i2c
sda: GPIO25
scl: GPIO23
esp32_camera:
external_clock:
pin: GPIO27
frequency: 20MHz
i2c_id: camera_i2c
data_pins: [GPIO17, GPIO35, GPIO34, GPIO5, GPIO39, GPIO18, GPIO36, GPIO19]
vsync_pin: GPIO22
href_pin: GPIO26
pixel_clock_pin: GPIO21
reset_pin: GPIO15
# Image settings
name: My Camera
# ...

M5Stack Timer Camera X/F:

# Example configuration entry
i2c:
- id: camera_i2c
sda: GPIO25
scl: GPIO23
esp32_camera:
external_clock:
pin: GPIO27
frequency: 20MHz
i2c_id: camera_i2c
data_pins: [GPIO32, GPIO35, GPIO34, GPIO5, GPIO39, GPIO18, GPIO36, GPIO19]
vsync_pin: GPIO22
href_pin: GPIO26
pixel_clock_pin: GPIO21
reset_pin: GPIO15
# Image settings
name: My Camera
# ...

M5Stack M5CameraF New:

# Example configuration entry as per https://docs.m5stack.com/en/unit/m5camera_f_new
i2c:
- id: camera_i2c
sda: GPIO22
scl: GPIO23
esp32_camera:
external_clock:
pin: GPIO27
frequency: 20MHz
i2c_id: camera_i2c
data_pins: [GPIO32, GPIO35, GPIO34, GPIO5, GPIO39, GPIO18, GPIO36, GPIO19]
vsync_pin: GPIO25
href_pin: GPIO26
pixel_clock_pin: GPIO21
reset_pin: GPIO15

M5Stack AtomS3R-CAM:

# Example configuration entry
psram: # required for JPEG compression/conversion
mode: octal
speed: 80MHz
switch: # required to initialize the camera
- platform: gpio
name: Activate My Camera
pin:
number: GPIO18
inverted: true
restore_mode: ALWAYS_ON
i2c:
- id: camera_i2c
sda: GPIO12 # CAM_SDA
scl: GPIO9 # CAM_SCL
esp32_camera:
setup_priority: -200 # delay after GPIO18 was set to low
i2c_id: camera_i2c
vsync_pin: GPIO10 # VSYNC
href_pin: GPIO14 # HREF
external_clock: # XCLK
pin: GPIO21
frequency: 20MHz
pixel_clock_pin: GPIO40 # PCLK
data_pins: [GPIO3, GPIO42, GPIO46, GPIO48, GPIO4, GPIO17, GPIO11, GPIO13] # Y2-9
# Image settings
name: My Camera
max_framerate: 15.0 fps
resolution: 320x240
frame_buffer_count: 1
frame_buffer_location: DRAM
pixel_format: YUV422
jpeg_quality: 6
agc_mode: manual
vertical_flip: true
horizontal_mirror: false
# ...

Wrover Kit Boards:

# Example configuration entry
i2c:
- id: camera_i2c
sda: GPIO26
scl: GPIO27
esp32_camera:
external_clock:
pin: GPIO21
frequency: 20MHz
i2c_id: camera_i2c
data_pins: [GPIO4, GPIO5, GPIO18, GPIO19, GPIO36, GPIO39, GPIO34, GPIO35]
vsync_pin: GPIO25
href_pin: GPIO23
pixel_clock_pin: GPIO22
# Image settings
name: My Camera
# ...

TTGO T-Camera V05:

# Example configuration entry
i2c:
- id: camera_i2c
sda: GPIO13
scl: GPIO12
esp32_camera:
external_clock:
pin: GPIO32
frequency: 20MHz
i2c_id: camera_i2c
data_pins: [GPIO5, GPIO14, GPIO4, GPIO15, GPIO18, GPIO23, GPIO36, GPIO39]
vsync_pin: GPIO27
href_pin: GPIO25
pixel_clock_pin: GPIO19
power_down_pin: GPIO26
# Image settings
name: My Camera
# ...

TTGO T-Camera V162:

# Example configuration entry
i2c:
- id: camera_i2c
sda: GPIO18
scl: GPIO23
esp32_camera:
external_clock:
pin: GPIO4
frequency: 20MHz
i2c_id: camera_i2c
data_pins: [GPIO34, GPIO13, GPIO14, GPIO35, GPIO39, GPIO38, GPIO37, GPIO36]
vsync_pin: GPIO5
href_pin: GPIO27
pixel_clock_pin: GPIO25
jpeg_quality: 10
vertical_flip: true
horizontal_mirror: false
# Image settings
name: My Camera
# ...

TTGO T-Camera V17:

# Example configuration entry
i2c:
- id: camera_i2c
sda: GPIO13
scl: GPIO12
esp32_camera:
external_clock:
pin: GPIO32
frequency: 20MHz
i2c_id: camera_i2c
data_pins: [GPIO5, GPIO14, GPIO4, GPIO15, GPIO18, GPIO23, GPIO36, GPIO39]
vsync_pin: GPIO27
href_pin: GPIO25
pixel_clock_pin: GPIO19
# power_down_pin: GPIO26
vertical_flip: true
horizontal_mirror: true
# Image settings
name: My Camera
# ...

TTGO T-Journal:

# Example configuration entry
i2c:
- id: camera_i2c
sda: GPIO25
scl: GPIO23
esp32_camera:
external_clock:
pin: GPIO27
frequency: 20MHz
i2c_id: camera_i2c
data_pins: [GPIO17, GPIO35, GPIO34, GPIO5, GPIO39, GPIO18, GPIO36, GPIO19]
vsync_pin: GPIO22
href_pin: GPIO26
pixel_clock_pin: GPIO21
# Image settings
name: My Camera
# ...

TTGO-Camera Plus:

# Example configuration entry
i2c:
- id: camera_i2c
sda: GPIO18
scl: GPIO23
esp32_camera:
external_clock:
pin: GPIO4
frequency: 20MHz
i2c_id: camera_i2c
data_pins: [GPIO34, GPIO13, GPIO26, GPIO35, GPIO39, GPIO38, GPIO37, GPIO36]
vsync_pin: GPIO5
href_pin: GPIO27
pixel_clock_pin: GPIO25
vertical_flip: false
horizontal_mirror: false
# Image settings
name: My Camera
# ...

TTGO-Camera Mini:

# Example configuration entry
i2c:
- id: camera_i2c
sda: GPIO13
scl: GPIO12
esp32_camera:
external_clock:
pin: GPIO32
frequency: 20MHz
i2c_id: camera_i2c
data_pins: [GPIO5, GPIO14, GPIO4, GPIO15, GPIO37, GPIO38, GPIO36, GPIO39]
vsync_pin: GPIO27
href_pin: GPIO25
pixel_clock_pin: GPIO19
# Image settings
name: My Camera
# ...

ESP-EYE:

# Example configuration entry
i2c:
- id: camera_i2c
sda: GPIO18
scl: GPIO23
esp32_camera:
external_clock:
pin: GPIO4
frequency: 20MHz
i2c_id: camera_i2c
data_pins: [GPIO34, GPIO13, GPIO14, GPIO35, GPIO39, GPIO38, GPIO37, GPIO36]
vsync_pin: GPIO5
href_pin: GPIO27
pixel_clock_pin: GPIO25
# Image settings
name: My Camera
# ...

ESP32S3_EYE on Freenove ESP32-S3-DevKitC-1:

# Example configuration entry
i2c:
- id: camera_i2c
sda: GPIO4
scl: GPIO5
esp32_camera:
external_clock:
pin: GPIO15
frequency: 20MHz
i2c_id: camera_i2c
data_pins: [GPIO11, GPIO9, GPIO8, GPIO10, GPIO12, GPIO18, GPIO17, GPIO16]
vsync_pin: GPIO6
href_pin: GPIO7
pixel_clock_pin: GPIO13
frame_buffer_location: DRAM
# Image settings
name: My Camera
# ...

Seeed Studio XIAO ESP32S3 Sense:

# Example configuration entry
i2c:
- id: camera_i2c
sda: GPIO40
scl: GPIO39
esp32_camera:
external_clock:
pin: GPIO10
frequency: 20MHz
i2c_id: camera_i2c
data_pins: [GPIO15, GPIO17, GPIO18, GPIO16, GPIO14, GPIO12, GPIO11, GPIO48]
vsync_pin: GPIO38
href_pin: GPIO47
pixel_clock_pin: GPIO13
# Image settings
name: My Camera
# ...

Waveshare ESP32-S3 ETH + OV2640 camera:

i2c:
- id: camera_i2c
sda: GPIO48
scl: GPIO47
esp32_camera:
external_clock:
pin: GPIO3
frequency: 20MHz
i2c_id: camera_i2c
data_pins: [GPIO41, GPIO45, GPIO46, GPIO42, GPIO40, GPIO38, GPIO15, GPIO18]
vsync_pin: GPIO1
href_pin: GPIO2
pixel_clock_pin: GPIO39
power_down_pin: GPIO8
# Image settings
name: My Camera
# ...