ESP32 摄像头组件

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

需要配置 I2C 和 Psram。

# 示例配置条目
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 (必需, string): 摄像头的名称。
icon (可选, icon): 手动设置前端用于摄像头的图标。
internal (可选, boolean): 将此组件标记为内部。内部组件不会暴露给前端（如 Home Assistant）。仅指定 id 而不指定 name 将隐式将其设置为 true。
disabled_by_default (可选, boolean): 如果为 true，则此实体不应添加到任何客户端的前端（通常是 Home Assistant），除非用户手动启用（通过 Home Assistant UI）。默认为 false。
entity_category (可选, string): 实体的类别。有关可用选项列表，请参阅 https://developers.home-assistant.io/docs/core/entity/#generic-properties。设置为 "" 可删除默认的实体类别。

连接选项：

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

帧设置：

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

图像设置：

resolution (可选, 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, 默认)
- 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)
jpeg_quality (可选, int): 摄像头编码图像的 JPEG 质量。从 10（最佳）到 63（最差）。默认为 10。
vertical_flip (可选, boolean): 是否垂直翻转图像。默认为 true。
horizontal_mirror (可选, boolean): 是否水平镜像图像。默认为 true。
contrast (可选, int): 应用于图像的对比度，从 -2 到 2。默认为 0。
brightness (可选, int): 应用于图像的亮度，从 -2 到 2。默认为 0。
saturation (可选, int): 应用于图像的饱和度，从 -2 到 2。默认为 0。
special_effect (可选, enum): 应用于图像的效果。默认为 none（无效果图像）。
- none : 无效果图像
- negative : 图像颜色反转
- grayscale : 仅保留图像亮度
- red_tint : 图像呈现红色调
- green_tint : 图像呈现绿色调
- blue_tint : 图像呈现蓝色调
- sepia : 图像应用怀旧效果

曝光设置：

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

传感器增益设置：

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

白平衡设置：

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

自动化：

on_stream_start (可选, 自动化): 流开始时要执行的自动化。
on_stream_stop (可选, 自动化): 流停止时要执行的自动化。
on_image (可选, 自动化): 拍摄图像时调用的自动化。图像可作为 image 变量使用，类型为 API Reference: esp32_camera::CameraImageData。

测试设置：

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

NOTE

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

配置示例

Ai-Thinker Camera:

WARNING

此开发板（以及可能下面的其他开发板）上的 GPIO16 连接到板载 PSRAM。将此 GPIO 用于其他目的（例如作为按钮）将触发看门狗。有关引脚注释的更多信息，请参见：https://github.com/raphaelbs/esp32-cam-ai-thinker/blob/master/docs/esp32cam-pin-notes.md

# 示例配置条目
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

  # 图像设置
  name: My Camera
  # ...

M5Stack Camera:

WARNING

此摄像头开发板散热不足，会随时间过热，ESPHome 仅在 Home Assistant 请求图像时激活摄像头，但对于某些开发板，摄像头单元仍可能显著发热。

如果重启后无法识别摄像头且单元感觉温暖，请等待其冷却后再次检查 - 如果仍然无法工作，请尝试启用测试图案。

# 示例配置条目
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

  # 图像设置
  name: My Camera
  # ...

M5Stack Timer Camera X/F:

# 示例配置条目
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

  # 图像设置
  name: My Camera
  # ...

M5Stack M5CameraF New:

# 示例配置条目，根据 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

Wrover Kit Boards:

# 示例配置条目
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

  # 图像设置
  name: My Camera
  # ...

TTGO T-Camera V05:

# 示例配置条目
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

  # 图像设置
  name: My Camera
  # ...

TTGO T-Camera V162:

# 示例配置条目
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

  # 图像设置
  name: My Camera
  # ...

TTGO T-Camera V17:

# 示例配置条目
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

  # 图像设置
  name: My Camera
  # ...

TTGO T-Journal:

# 示例配置条目
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

  # 图像设置
  name: My Camera
  # ...

TTGO-Camera Plus:

# 示例配置条目
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

  # 图像设置
  name: My Camera
  # ...

TTGO-Camera Mini:

# 示例配置条目
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

  # 图像设置
  name: My Camera
  # ...

ESP-EYE:

# 示例配置条目
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

  # 图像设置
  name: My Camera
  # ...

ESP32S3_EYE 在 Freenove ESP32-S3-DevKitC-1 上:

# 示例配置条目
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

  # 图像设置
  name: My Camera
  # ...

Seeed Studio XIAO ESP32S3 Sense:

# 示例配置条目
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

  # 图像设置
  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

  # 图像设置
  name: My Camera
  # ...

另请参阅

API Reference: esp32_camera.h