mirror of
https://github.com/esphome/esphome-docs.git
synced 2024-11-05 09:20:08 +01:00
43d22a4c81
Co-authored-by: H. Árkosi Róbert <robreg@zsurob.hu> Co-authored-by: Jesse Hills <3060199+jesserockz@users.noreply.github.com>
498 lines
16 KiB
ReStructuredText
498 lines
16 KiB
ReStructuredText
ESP32 Camera Component
|
|
======================
|
|
|
|
.. seo::
|
|
:description: Instructions for setting up the ESP32 Cameras in ESPHome
|
|
:image: camera.svg
|
|
|
|
The ``esp32_camera`` component allows you to use ESP32-based camera boards in ESPHome that
|
|
directly integrate into Home Assistant through the native API.
|
|
|
|
.. code-block:: yaml
|
|
|
|
# Example configuration entry
|
|
esp32_camera:
|
|
name: My Camera
|
|
external_clock:
|
|
pin: GPIO27
|
|
frequency: 20MHz
|
|
i2c_pins:
|
|
sda: GPIO25
|
|
scl: GPIO23
|
|
data_pins: [GPIO17, GPIO35, GPIO34, GPIO5, GPIO39, GPIO18, GPIO36, GPIO19]
|
|
vsync_pin: GPIO22
|
|
href_pin: GPIO26
|
|
pixel_clock_pin: GPIO21
|
|
reset_pin: GPIO15
|
|
resolution: 640x480
|
|
jpeg_quality: 10
|
|
|
|
Configuration variables:
|
|
------------------------
|
|
|
|
- **name** (**Required**, 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).
|
|
Requires Home Assistant 2021.9 or newer. 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. Requires Home Assistant 2021.11 or newer.
|
|
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*, float): The frequency of the external clock, must be between 10
|
|
and 20MHz. Defaults to ``20MHz``.
|
|
|
|
- **i2c_pins** (**Required**): The I²C control pins of the camera.
|
|
|
|
- **sda** (**Required**, pin): The SDA pin of the I²C interface. Also called ``SIOD``.
|
|
- **scl** (**Required**, pin): The SCL pin of the I²C interface. Also called ``SIOC``.
|
|
|
|
- **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``.
|
|
|
|
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)
|
|
- ``176x144`` (QCIF)
|
|
- ``240x176`` (HQVGA)
|
|
- ``320x240`` (QVGA)
|
|
- ``400x296`` (CIF)
|
|
- ``640x480`` (VGA, default)
|
|
- ``800x600`` (SVGA)
|
|
- ``1024x768`` (XGA)
|
|
- ``1280x1024`` (SXGA)
|
|
- ``1600x1200`` (UXGA)
|
|
- ``1920x1080`` (FHD)
|
|
- ``720x1280`` (Portrait HD)
|
|
- ``864x1536`` (Portrait 3MP)
|
|
- ``2048x1536`` (QXGA)
|
|
- ``2560x1440`` (QHD)
|
|
- ``2560x1600`` (WQXGA)
|
|
- ``1080x1920`` (Portrait FHD)
|
|
- ``2560x1920`` (QSXGA)
|
|
|
|
|
|
- **jpeg_quality** (*Optional*, int): The JPEG quality that the camera should encode images with.
|
|
From 10 (best) to 63 (worst). Defaults to ``10``.
|
|
- **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 balace 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
|
|
|
|
Automations:
|
|
|
|
- **on_stream_start** (*Optional*, :ref:`Automation <automation>`): An automation to perform
|
|
when a stream starts.
|
|
- **on_stream_stop** (*Optional*, :ref:`Automation <automation>`): An automation to perform
|
|
when a stream stops.
|
|
- **on_image** (*Optional*, :ref:`Automation <automation>`): An automation called when image taken. Image is available as ``image`` variable of type :apistruct:`esp32_camera::CameraImageData`.
|
|
|
|
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``.
|
|
|
|
|
|
.. note::
|
|
|
|
Camera uses PWM timer #1. If you need PWM (via the ``ledc`` platform) you need to manually specify
|
|
a channel there (with the ``channel: 2`` parameter)
|
|
|
|
Configuration for 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
|
|
|
|
.. code-block:: yaml
|
|
|
|
# Example configuration entry
|
|
esp32_camera:
|
|
external_clock:
|
|
pin: GPIO0
|
|
frequency: 20MHz
|
|
i2c_pins:
|
|
sda: GPIO26
|
|
scl: GPIO27
|
|
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
|
|
# ...
|
|
|
|
Configuration for 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.
|
|
|
|
.. code-block:: yaml
|
|
|
|
# Example configuration entry
|
|
esp32_camera:
|
|
external_clock:
|
|
pin: GPIO27
|
|
frequency: 20MHz
|
|
i2c_pins:
|
|
sda: GPIO25
|
|
scl: GPIO23
|
|
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
|
|
# ...
|
|
|
|
Configuration for M5Stack Timer Camera X/F
|
|
------------------------------------------
|
|
|
|
.. code-block:: yaml
|
|
|
|
# Example configuration entry
|
|
esp32_camera:
|
|
external_clock:
|
|
pin: GPIO27
|
|
frequency: 20MHz
|
|
i2c_pins:
|
|
sda: GPIO25
|
|
scl: GPIO23
|
|
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
|
|
# ...
|
|
|
|
Confguration for M5Stack M5CameraF New
|
|
--------------------------------------
|
|
|
|
.. code-block:: yaml
|
|
|
|
# Example configuration entry as per https://docs.m5stack.com/en/unit/m5camera_f_new
|
|
esp32_camera:
|
|
external_clock:
|
|
pin: GPIO27
|
|
frequency: 20MHz
|
|
i2c_pins:
|
|
sda: GPIO22
|
|
scl: GPIO23
|
|
data_pins: [GPIO32, GPIO35, GPIO34, GPIO5, GPIO39, GPIO18, GPIO36, GPIO19]
|
|
vsync_pin: GPIO25
|
|
href_pin: GPIO26
|
|
pixel_clock_pin: GPIO21
|
|
reset_pin: GPIO15
|
|
|
|
Configuration for Wrover Kit Boards
|
|
-----------------------------------
|
|
|
|
.. code-block:: yaml
|
|
|
|
# Example configuration entry
|
|
esp32_camera:
|
|
external_clock:
|
|
pin: GPIO21
|
|
frequency: 20MHz
|
|
i2c_pins:
|
|
sda: GPIO26
|
|
scl: GPIO27
|
|
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
|
|
# ...
|
|
|
|
Configuration for TTGO T-Camera V05
|
|
-----------------------------------
|
|
|
|
.. code-block:: yaml
|
|
|
|
# Example configuration entry
|
|
esp32_camera:
|
|
external_clock:
|
|
pin: GPIO32
|
|
frequency: 20MHz
|
|
i2c_pins:
|
|
sda: GPIO13
|
|
scl: GPIO12
|
|
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
|
|
# ...
|
|
|
|
Configuration for TTGO T-Camera V162
|
|
------------------------------------
|
|
|
|
.. code-block:: yaml
|
|
|
|
esp32_camera:
|
|
external_clock:
|
|
pin: GPIO4
|
|
frequency: 20MHz
|
|
i2c_pins:
|
|
sda: GPIO18
|
|
scl: GPIO23
|
|
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
|
|
# ...
|
|
|
|
Configuration for TTGO T-Camera V17
|
|
-----------------------------------
|
|
|
|
.. code-block:: yaml
|
|
|
|
# Example configuration entry
|
|
esp32_camera:
|
|
external_clock:
|
|
pin: GPIO32
|
|
frequency: 20MHz
|
|
i2c_pins:
|
|
sda: GPIO13
|
|
scl: GPIO12
|
|
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
|
|
# ...
|
|
|
|
Configuration for TTGO T-Journal
|
|
--------------------------------
|
|
|
|
.. code-block:: yaml
|
|
|
|
# Example configuration entry
|
|
esp32_camera:
|
|
external_clock:
|
|
pin: GPIO27
|
|
frequency: 20MHz
|
|
i2c_pins:
|
|
sda: GPIO25
|
|
scl: GPIO23
|
|
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
|
|
# ...
|
|
|
|
|
|
Configuration for TTGO-Camera Plus
|
|
----------------------------------
|
|
|
|
.. code-block:: yaml
|
|
|
|
# Example configuration entry
|
|
esp32_camera:
|
|
external_clock:
|
|
pin: GPIO4
|
|
frequency: 20MHz
|
|
i2c_pins:
|
|
sda: GPIO18
|
|
scl: GPIO23
|
|
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
|
|
# ...
|
|
|
|
Configuration for TTGO-Camera Mini
|
|
----------------------------------
|
|
|
|
.. code-block:: yaml
|
|
|
|
# Example configuration entry
|
|
esp32_camera:
|
|
external_clock:
|
|
pin: GPIO32
|
|
frequency: 20MHz
|
|
i2c_pins:
|
|
sda: GPIO13
|
|
scl: GPIO12
|
|
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
|
|
# ...
|
|
|
|
Configuration for ESP-EYE
|
|
----------------------------------
|
|
|
|
.. code-block:: yaml
|
|
|
|
# Example configuration entry
|
|
esp32_camera:
|
|
external_clock:
|
|
pin: GPIO4
|
|
frequency: 20MHz
|
|
i2c_pins:
|
|
sda: GPIO18
|
|
scl: GPIO23
|
|
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
|
|
# ...
|
|
|
|
Configuration for ESP32S3_EYE on `Freenove ESP32-S3-DevKitC-1 <https://github.com/Freenove/Freenove_ESP32_S3_WROOM_Board>`_
|
|
---------------------------------------------------------------------------------------------------------------------------
|
|
|
|
.. code-block:: yaml
|
|
|
|
# Example configuration entry
|
|
external_components:
|
|
- source:
|
|
type: git
|
|
url: https://github.com/MichaKersloot/esphome_custom_components
|
|
components: [ esp32_camera ]
|
|
|
|
esp32_camera:
|
|
external_clock:
|
|
pin: GPIO15
|
|
frequency: 20MHz
|
|
i2c_pins:
|
|
sda: GPIO4
|
|
scl: GPIO5
|
|
data_pins: [GPIO11, GPIO9, GPIO8, GPIO10, GPIO12, GPIO18, GPIO17, GPIO16]
|
|
vsync_pin: GPIO6
|
|
href_pin: GPIO7
|
|
pixel_clock_pin: GPIO13
|
|
|
|
# Image settings
|
|
name: My Camera
|
|
# ...
|
|
|
|
See Also
|
|
--------
|
|
|
|
- :apiref:`esp32_camera/esp32_camera.h`
|
|
- :ghedit:`Edit`
|