ESP32 摄像头组件

esp32_camera 组件允许你在 ESPHome 中使用基于 ESP32 的摄像头板，这些摄像头板可通过原生 API 直接集成到 Home Assistant 中。

需要配置 I2C 和 Psram。

# 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): 摄像头的名称。
icon (Optional, icon): 手动设置前端中摄像头使用的图标。
internal (Optional, boolean): 将此组件标记为内部组件。内部组件将不会在前端（如 Home Assistant）中显示。仅指定 id 而不指定 name 将隐式地将其设置为 true。
disabled_by_default (Optional, boolean): 如果为 true，则在用户手动启用（通过 Home Assistant UI）之前，此实体不应被添加到任何客户端的前端（通常是 Home Assistant）。默认为 false。
entity_category (Optional, string): 实体的类别。参见 https://developers.home-assistant.io/docs/core/entity/#generic-properties 获取可用选项的列表。设置为 "" 以移除默认的实体类别。

连接选项：

data_pins (Required, list of pins): 摄像头的数据通道，这必须是 8 个 GPIO 引脚的列表。
vsync_pin (Required, pin): 连接摄像头 VSYNC 线的引脚。
href_pin (Required, pin): 连接摄像头 HREF 线的引脚。
pixel_clock_pin (Required, pin): 连接摄像头像素时钟线的引脚。
external_clock (Required): 驱动摄像头的外部时钟的配置。
- pin (Required, pin): 连接外部时钟线的引脚。
- frequency (Optional, frequency): 外部时钟的频率，必须在 8MHz 到 20MHz 之间。默认为 20MHz。
i2c_id (Optional, ID): 摄像头所连接的 I²C 总线的 ID。
reset_pin (Optional, pin): 连接摄像头复位引脚的 ESP 引脚。如果设置，这将在 ESP 启动前重置摄像头。
power_down_pin (Optional, pin): 用于关闭摄像头的 ESP 引脚。如果设置，这将在摄像头不活动时将其断电。
test_pattern (Optional, boolean): 启用后，摄像头将显示一个可用于调试连接问题的测试图案。

帧设置：

max_framerate (Optional, float): 摄像头生成图像的最大帧率。最高可达 60Hz（使用较小的帧尺寸），但请注意过热问题。默认为 10 fps。
idle_framerate (Optional, float): 当没有客户端请求完整视频流时，捕获图像的帧率。默认为 0.1 fps。
frame_buffer_count (Optional, int): 从摄像头传感器读取时使用的帧缓冲区数量。必须介于 1 和 2 之间。默认为 1。
frame_buffer_location (Optional, enum): 用于存储帧缓冲区的内存区域。默认为 PSRAM。
- PSRAM
- DRAM

图像设置：

resolution (Optional, enum): 摄像头捕获图像的分辨率。更高的分辨率需要更多内存，如果内存不足，你将在启动时看到错误。
- 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): 图像使用的像素格式。默认为 jpeg（JPEG 压缩图像），并非所有摄像头都支持。其他格式需要更多的 CPU 和内存，并且可能不受所有摄像头支持。
- jpeg: JPEG 压缩图像
- rgb565: RGB565 未压缩图像
- yuv422: YUV422 未压缩图像
- yuv420: YUV420 未压缩图像
- grayscale: 灰度未压缩图像
- rgb888: RGB888 未压缩图像
- raw: 原始未压缩图像
- rgb444: RGB444 未压缩图像
- rgb555: RGB555 未压缩图像
jpeg_quality (Optional, int): 摄像头编码图像时应使用的 JPEG 质量。范围从 6（最佳）到 63（最差）。默认为 10。将其设置为 0 以禁用 JPEG 压缩/转换。手动 JPEG 压缩/转换需要启用并配置 psram 组件。
vertical_flip (Optional, boolean): 是否垂直翻转图像。默认为 true。
horizontal_mirror (Optional, boolean): 是否水平镜像图像。默认为 true。
contrast (Optional, int): 应用于画面的对比度，范围从 -2 到 2。默认为 0。
brightness (Optional, int): 应用于画面的亮度，范围从 -2 到 2。默认为 0。
saturation (Optional, int): 应用于画面的饱和度，范围从 -2 到 2。默认为 0。
special_effect (Optional, enum): 应用于画面的特效。默认为 none（无特效）。
- none : 无特效的画面
- negative : 画面颜色反相
- grayscale : 仅保留画面的亮度
- red_tint : 画面呈现红色色调
- green_tint : 画面呈现绿色色调
- blue_tint : 画面呈现蓝色色调
- sepia : 画面应用怀旧（棕褐色）效果

曝光设置：

aec_mode (Optional, enum): 曝光模块的模式。默认为 auto（让摄像头自动调整曝光）。
- manual : 曝光可以手动设置，通过 aec_value 参数。ae_level 在此模式下无效
- auto : 摄像头自动管理曝光。可通过 ae_level 参数应用补偿。aec_value 在此模式下无效
aec2 (Optional, boolean): 是否启用自动曝光控制 2。似乎会改变自动曝光的计算方法。默认为 false。
ae_level (Optional, int): 应用于画面的自动曝光级别（当 aec_mode 设置为 auto 时），范围从 -2 到 2。默认为 0。
aec_value (Optional, int): 应用于画面的曝光值（当 aec_mode 设置为 manual 时），范围从 0 到 1200。默认为 300。

传感器增益设置：

agc_mode (Optional, enum): 增益控制模块的模式。默认为 auto（让摄像头自动调整传感器增益）。
- manual : 增益可以手动设置，通过 agc_value 参数。agc_gain_ceiling 在此模式下无效
- auto : 摄像头自动管理传感器增益。可通过 agc_gain_ceiling 参数定义最大增益。agc_value 在此模式下无效
agc_value (Optional, int): 应用于画面的增益值（当 aec_mode 设置为 manual 时），范围从 0 到 30。默认为 0。
agc_gain_ceiling (Optional, enum): 当 agc_mode 设置为 auto 时允许的最大增益。此参数似乎充当“ISO”设置。默认为 2x。
- 2x : 摄像头灵敏度较低，画面干净（无明显噪点）
- 4x
- 8x
- 16x
- 32x
- 64x
- 128x : 摄像头灵敏度更高，但画面包含大量噪点

白平衡设置：

wb_mode (Optional, enum): 白平衡模块的模式。默认为 auto。
- auto : 摄像头选择最佳的白平衡设置
- sunny : 白平衡晴天模式
- cloudy : 白平衡多云模式
- office : 白平衡办公模式
- home : 白平衡室内模式

自动化：

on_stream_start (Optional, Automation): 在视频流开始时执行的自动化。
on_stream_stop (Optional, Automation): 在视频流停止时执行的自动化。
on_image (Optional, Automation): 在拍摄图像时调用的自动化。图像可作为类型为 API 参考：esp32_camera::CameraImageData 的 image 变量使用。

测试设置：

test_pattern (Optional, boolean): 出于测试目的，可以用彩色测试图案替换从传感器获取的图像。默认为 false。

NOTE

摄像头使用 PWM 定时器 #1。如果你需要 PWM（通过 ledc 平台），需要在其中手动指定一个通道（使用 channel: 2 参数）

配置示例

Ai-Thinker 摄像头：

WARNING

此开发板（可能还包括下面的其他开发板）上的 GPIO16 连接了板载 PSRAM。将此 GPIO 用于其他用途（例如作为按钮）将触发看门狗。有关引脚说明的更多信息可在此查看：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
  # ...

M5Stack 摄像头：

WARNING

此摄像头板散热不足，长时间使用会过热， ESPHome 仅在 Home Assistant 请求图像时才会激活摄像头，但某些开发板上的摄像头模组仍可能明显发热。

如果重启后摄像头仍然无法识别且设备发热，请尝试等待其冷却后再检查——如果仍然不行，请尝试启用测试图案。

# 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 定时器摄像头 X/F（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 新款：

# 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 开发板：

# 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，运行在 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
  # ...

另请参见

API 参考：esp32_camera.h