From de304dba61fee4a6060eeec17324d1154af7679d Mon Sep 17 00:00:00 2001 From: Dieter Tschanz Date: Thu, 3 Jul 2025 22:17:46 +0200 Subject: [PATCH 01/11] Add initial documentation for new camera platform This is the first step in documenting the modernized camera framework. It introduces the new base Camera class, which serves as an abstraction layer between the API and concrete implementations like esp32_camera. More documentation updates will follow as additional parts of the framework are migrated or enhanced. --- components/camera.rst | 31 +++++++++++++++++++++++++++++++ components/index.rst | 1 + 2 files changed, 32 insertions(+) create mode 100644 components/camera.rst diff --git a/components/camera.rst b/components/camera.rst new file mode 100644 index 0000000000..0a674b6d63 --- /dev/null +++ b/components/camera.rst @@ -0,0 +1,31 @@ +Camera Component +================ + +.. seo:: + :description: Modular camera framework. + :image: camera.svg + +The ``camera`` component is a modular framework. + +Captured images can be rendered directly in Home Assisant, or displayed locally using the ``esp32_camera_web_server`` +running on the ESP32. + +Common use cases include: + +- Capturing and encoding images from thermal cameras or generating synthetic images programmatically +- Displaying images via Home Assistant or local web servers + +Extending the Camera Framework +------------------------------ + +This component is designed to be extended: + +- For physical camera integrations, see the ``esp32_camera`` component as an example implementation using this framework. + +See Also +-------- + +- :doc:`esp32_camera` +- :doc:`esp32_camera_web_server` +- :apiref:`camera/camera.h` +- :ghedit:`Edit` diff --git a/components/index.rst b/components/index.rst index 02d5fe2a6c..398cf0d568 100644 --- a/components/index.rst +++ b/components/index.rst @@ -1076,6 +1076,7 @@ Miscellaneous Components .. imgtable:: + Camera, components/camera, camera.svg, dark-invert ESP32 Camera, components/esp32_camera, camera.svg, dark-invert Exposure Notifications, components/exposure_notifications, exposure_notifications.png GPS, components/gps, crosshairs-gps.svg, dark-invert From 4285c677fdc50eb470ce925d7f85e87b1cbc93cf Mon Sep 17 00:00:00 2001 From: DT-art1 <81360462+DT-art1@users.noreply.github.com> Date: Thu, 3 Jul 2025 22:29:49 +0200 Subject: [PATCH 02/11] Update components/camera.rst Co-authored-by: J. Nick Koston --- components/camera.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/camera.rst b/components/camera.rst index 0a674b6d63..6ded866746 100644 --- a/components/camera.rst +++ b/components/camera.rst @@ -7,7 +7,7 @@ Camera Component The ``camera`` component is a modular framework. -Captured images can be rendered directly in Home Assisant, or displayed locally using the ``esp32_camera_web_server`` +Captured images can be rendered directly in Home Assistant, or displayed locally using the ``esp32_camera_web_server`` running on the ESP32. Common use cases include: From c76f44f5d25474a3ad6d07c91105fa73adee2c88 Mon Sep 17 00:00:00 2001 From: "J. Nick Koston" Date: Thu, 3 Jul 2025 15:37:48 -0500 Subject: [PATCH 03/11] tweaks --- components/camera.rst | 31 ---------------------------- components/camera/index.rst | 40 +++++++++++++++++++++++++++++++++++++ components/index.rst | 13 +++++++++--- 3 files changed, 50 insertions(+), 34 deletions(-) delete mode 100644 components/camera.rst create mode 100644 components/camera/index.rst diff --git a/components/camera.rst b/components/camera.rst deleted file mode 100644 index 0a674b6d63..0000000000 --- a/components/camera.rst +++ /dev/null @@ -1,31 +0,0 @@ -Camera Component -================ - -.. seo:: - :description: Modular camera framework. - :image: camera.svg - -The ``camera`` component is a modular framework. - -Captured images can be rendered directly in Home Assisant, or displayed locally using the ``esp32_camera_web_server`` -running on the ESP32. - -Common use cases include: - -- Capturing and encoding images from thermal cameras or generating synthetic images programmatically -- Displaying images via Home Assistant or local web servers - -Extending the Camera Framework ------------------------------- - -This component is designed to be extended: - -- For physical camera integrations, see the ``esp32_camera`` component as an example implementation using this framework. - -See Also --------- - -- :doc:`esp32_camera` -- :doc:`esp32_camera_web_server` -- :apiref:`camera/camera.h` -- :ghedit:`Edit` diff --git a/components/camera/index.rst b/components/camera/index.rst new file mode 100644 index 0000000000..c793d39f02 --- /dev/null +++ b/components/camera/index.rst @@ -0,0 +1,40 @@ +Camera Component +================ + +.. seo:: + :description: Instructions for setting up cameras in ESPHome. + :image: camera.svg + +The ``camera`` component is the base abstraction layer for camera implementations in ESPHome. It provides a +standardized interface between camera hardware/software implementations and the ESPHome API layer. + +.. note:: + + This component cannot be used directly. It serves as the base platform that specific camera + implementations (like :doc:`esp32_camera`) build upon. + +Overview +-------- + +The camera component acts as a foundation for camera integrations, with :doc:`esp32_camera` being the +first implementation using this framework. + +All camera implementations in ESPHome inherit from this base component, ensuring a consistent API +for image capture and transmission to Home Assistant or other consumers. + +Camera Platforms +---------------- + +.. toctree:: + :maxdepth: 1 + :glob: + + * + +See Also +-------- + +- :doc:`esp32_camera` +- :doc:`esp32_camera_web_server` +- :apiref:`camera/camera.h` +- :ghedit:`Edit` \ No newline at end of file diff --git a/components/index.rst b/components/index.rst index 398cf0d568..a119f77bdd 100644 --- a/components/index.rst +++ b/components/index.rst @@ -130,7 +130,6 @@ Management and Monitoring StatsD, components/statsd, connection.svg, dark-invert Safe Mode, components/safe_mode, restart-alert.svg, dark-invert Web Server, components/web_server, http.svg - ESP32 Camera Web Server, components/esp32_camera_web_server, camera.svg, dark-invert Update Installation ------------------- @@ -674,6 +673,15 @@ Button Components UART Button, components/button/uart, uart.svg Wake-on-LAN, components/button/wake_on_lan, power_settings.svg, dark-invert +Camera Components +----------------- + +.. imgtable:: + + Camera Core, components/camera/index, folder-open.svg, dark-invert + ESP32 Camera, components/esp32_camera, camera.svg, dark-invert + ESP32 Camera Web Server, components/esp32_camera_web_server, camera.svg, dark-invert + Climate Components ------------------ @@ -1076,8 +1084,6 @@ Miscellaneous Components .. imgtable:: - Camera, components/camera, camera.svg, dark-invert - ESP32 Camera, components/esp32_camera, camera.svg, dark-invert Exposure Notifications, components/exposure_notifications, exposure_notifications.png GPS, components/gps, crosshairs-gps.svg, dark-invert Grow Fingerprint Reader, components/fingerprint_grow, fingerprint.svg, dark-invert @@ -1117,6 +1123,7 @@ ESPHome depends on and welcomes contributions from our community. If you'd like :hidden: binary_sensor/index + camera/index canbus/index climate/index cover/index From 833ac2512d33be64547a805033b491d9097ad0f8 Mon Sep 17 00:00:00 2001 From: "J. Nick Koston" Date: Thu, 3 Jul 2025 15:40:32 -0500 Subject: [PATCH 04/11] lint --- components/camera/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/camera/index.rst b/components/camera/index.rst index c793d39f02..e4d78d18be 100644 --- a/components/camera/index.rst +++ b/components/camera/index.rst @@ -37,4 +37,4 @@ See Also - :doc:`esp32_camera` - :doc:`esp32_camera_web_server` - :apiref:`camera/camera.h` -- :ghedit:`Edit` \ No newline at end of file +- :ghedit:`Edit` From 3fab4a9e95940d52e5c542a9e03baea912c5135b Mon Sep 17 00:00:00 2001 From: "J. Nick Koston" Date: Thu, 3 Jul 2025 15:42:19 -0500 Subject: [PATCH 05/11] lint --- components/camera/index.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/components/camera/index.rst b/components/camera/index.rst index e4d78d18be..858671c35a 100644 --- a/components/camera/index.rst +++ b/components/camera/index.rst @@ -11,12 +11,12 @@ standardized interface between camera hardware/software implementations and the .. note:: This component cannot be used directly. It serves as the base platform that specific camera - implementations (like :doc:`esp32_camera`) build upon. + implementations (like :doc:`/components/esp32_camera`) build upon. Overview -------- -The camera component acts as a foundation for camera integrations, with :doc:`esp32_camera` being the +The camera component acts as a foundation for camera integrations, with :doc:`/components/esp32_camera` being the first implementation using this framework. All camera implementations in ESPHome inherit from this base component, ensuring a consistent API @@ -34,7 +34,7 @@ Camera Platforms See Also -------- -- :doc:`esp32_camera` -- :doc:`esp32_camera_web_server` +- :doc:`/components/esp32_camera` +- :doc:`/components/esp32_camera_web_server` - :apiref:`camera/camera.h` - :ghedit:`Edit` From abf46cb1d6d0bb030e5728674b56fe40fd1205f8 Mon Sep 17 00:00:00 2001 From: "J. Nick Koston" Date: Thu, 3 Jul 2025 15:47:32 -0500 Subject: [PATCH 06/11] lint --- components/{ => camera}/esp32_camera.rst | 0 components/{ => camera}/esp32_camera_web_server.rst | 0 components/camera/index.rst | 8 ++++---- components/index.rst | 4 ++-- 4 files changed, 6 insertions(+), 6 deletions(-) rename components/{ => camera}/esp32_camera.rst (100%) rename components/{ => camera}/esp32_camera_web_server.rst (100%) diff --git a/components/esp32_camera.rst b/components/camera/esp32_camera.rst similarity index 100% rename from components/esp32_camera.rst rename to components/camera/esp32_camera.rst diff --git a/components/esp32_camera_web_server.rst b/components/camera/esp32_camera_web_server.rst similarity index 100% rename from components/esp32_camera_web_server.rst rename to components/camera/esp32_camera_web_server.rst diff --git a/components/camera/index.rst b/components/camera/index.rst index 858671c35a..e4d78d18be 100644 --- a/components/camera/index.rst +++ b/components/camera/index.rst @@ -11,12 +11,12 @@ standardized interface between camera hardware/software implementations and the .. note:: This component cannot be used directly. It serves as the base platform that specific camera - implementations (like :doc:`/components/esp32_camera`) build upon. + implementations (like :doc:`esp32_camera`) build upon. Overview -------- -The camera component acts as a foundation for camera integrations, with :doc:`/components/esp32_camera` being the +The camera component acts as a foundation for camera integrations, with :doc:`esp32_camera` being the first implementation using this framework. All camera implementations in ESPHome inherit from this base component, ensuring a consistent API @@ -34,7 +34,7 @@ Camera Platforms See Also -------- -- :doc:`/components/esp32_camera` -- :doc:`/components/esp32_camera_web_server` +- :doc:`esp32_camera` +- :doc:`esp32_camera_web_server` - :apiref:`camera/camera.h` - :ghedit:`Edit` diff --git a/components/index.rst b/components/index.rst index e52dfcc2a2..29f7679252 100644 --- a/components/index.rst +++ b/components/index.rst @@ -682,8 +682,8 @@ Camera Components .. imgtable:: Camera Core, components/camera/index, folder-open.svg, dark-invert - ESP32 Camera, components/esp32_camera, camera.svg, dark-invert - ESP32 Camera Web Server, components/esp32_camera_web_server, camera.svg, dark-invert + ESP32 Camera, components/camera/esp32_camera, camera.svg, dark-invert + ESP32 Camera Web Server, components/camera/esp32_camera_web_server, camera.svg, dark-invert Climate Components ------------------ From ceca4cdaec2bd8816bfd0569cd2ef5f010c0759b Mon Sep 17 00:00:00 2001 From: "J. Nick Koston" Date: Thu, 3 Jul 2025 15:48:56 -0500 Subject: [PATCH 07/11] lint --- changelog/v1.12.0.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changelog/v1.12.0.rst b/changelog/v1.12.0.rst index 1b85b6d3d8..06b743853f 100644 --- a/changelog/v1.12.0.rst +++ b/changelog/v1.12.0.rst @@ -27,7 +27,7 @@ Before 1.12, it was only possible to transfer data from ESPHome to Home Assistan just define a service in your ESPHome file and call it like any other service from HA. All the rest (like variables, data validation, etc) are handled automatically! -:doc:`ESP32 Camera Support `: This is huge. When integrating cameras +:doc:`ESP32 Camera Support `: This is huge. When integrating cameras into your smart home you'd always have to weigh between security and price; cheap cameras often are very insecure (and sometimes even exposed on the web). And even the pricier ones would sometimes phone back to the manufacturer and upload your data. With ESPHome, everything's 100% From 846440eaaa17048040a414cf6e3278b6cfece4ee Mon Sep 17 00:00:00 2001 From: "J. Nick Koston" Date: Thu, 3 Jul 2025 15:49:24 -0500 Subject: [PATCH 08/11] lint --- changelog/v1.12.0.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changelog/v1.12.0.rst b/changelog/v1.12.0.rst index 06b743853f..52a699990a 100644 --- a/changelog/v1.12.0.rst +++ b/changelog/v1.12.0.rst @@ -10,7 +10,7 @@ Changelog - Version 1.12.0 .. imgtable:: User-Defined Services, components/api.html#user-defined-services, home-assistant.svg, dark-invert - ESP32 Camera, components/esp32_camera, camera.svg, dark-invert + ESP32 Camera, components/camera/esp32_camera, camera.svg, dark-invert MPR121, components/binary_sensor/mpr121, mpr121.jpg SDS011, components/sensor/sds011, sds011.jpg From f11d0585f4058ef25f9653f336bcbd170f83aa38 Mon Sep 17 00:00:00 2001 From: "J. Nick Koston" Date: Thu, 3 Jul 2025 15:49:35 -0500 Subject: [PATCH 09/11] lint --- changelog/2021.11.0.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changelog/2021.11.0.rst b/changelog/2021.11.0.rst index 53d5ae6fbb..bf45c73239 100644 --- a/changelog/2021.11.0.rst +++ b/changelog/2021.11.0.rst @@ -12,7 +12,7 @@ ESPHome 2021.11.0 - 17th November 2021 CSE7761, components/sensor/cse7761, cse7761.svg CAP1188 Capacitive Touch Sensor, components/binary_sensor/cap1188, cap1188.jpg - ESP32 Camera Web Server, components/esp32_camera_web_server, camera.svg, dark-invert + ESP32 Camera Web Server, components/camera/esp32_camera_web_server, camera.svg, dark-invert Improv via Serial, components/improv_serial, improv.svg, dark-invert From 146ae49f18a6b181a8ca302e49c7e71bc0c031bc Mon Sep 17 00:00:00 2001 From: "J. Nick Koston" Date: Thu, 3 Jul 2025 15:49:54 -0500 Subject: [PATCH 10/11] lint --- _redirects | 2 ++ 1 file changed, 2 insertions(+) diff --git a/_redirects b/_redirects index 49d20ae4f5..0196ebd9f8 100644 --- a/_redirects +++ b/_redirects @@ -10,6 +10,8 @@ # e.g: /components/sensors/abc.html /components/sensors/xyz.html 301 /components/sensor/sgp40.html /components/sensor/sgp4x.html 301 /components/binary_sensor/xpt2046.html /components/touchscreen/xpt2046.html 301 +/components/esp32_camera.html /components/camera/esp32_camera.html 301 +/components/esp32_camera_web_server.html /components/camera/esp32_camera_web_server.html 301 /devices/esp8266.html /components/esp8266.html /devices/esp32.html /components/esp32.html From 31f62af1f418713ed1eb33752407ddb66876ae2e Mon Sep 17 00:00:00 2001 From: "J. Nick Koston" Date: Sun, 6 Jul 2025 22:38:18 -0500 Subject: [PATCH 11/11] revert --- _redirects | 2 -- changelog/2021.11.0.rst | 2 +- changelog/v1.12.0.rst | 4 ++-- components/camera/index.rst | 10 ++++------ components/{camera => }/esp32_camera.rst | 0 components/{camera => }/esp32_camera_web_server.rst | 0 components/index.rst | 11 ++--------- 7 files changed, 9 insertions(+), 20 deletions(-) rename components/{camera => }/esp32_camera.rst (100%) rename components/{camera => }/esp32_camera_web_server.rst (100%) diff --git a/_redirects b/_redirects index 0196ebd9f8..49d20ae4f5 100644 --- a/_redirects +++ b/_redirects @@ -10,8 +10,6 @@ # e.g: /components/sensors/abc.html /components/sensors/xyz.html 301 /components/sensor/sgp40.html /components/sensor/sgp4x.html 301 /components/binary_sensor/xpt2046.html /components/touchscreen/xpt2046.html 301 -/components/esp32_camera.html /components/camera/esp32_camera.html 301 -/components/esp32_camera_web_server.html /components/camera/esp32_camera_web_server.html 301 /devices/esp8266.html /components/esp8266.html /devices/esp32.html /components/esp32.html diff --git a/changelog/2021.11.0.rst b/changelog/2021.11.0.rst index bf45c73239..53d5ae6fbb 100644 --- a/changelog/2021.11.0.rst +++ b/changelog/2021.11.0.rst @@ -12,7 +12,7 @@ ESPHome 2021.11.0 - 17th November 2021 CSE7761, components/sensor/cse7761, cse7761.svg CAP1188 Capacitive Touch Sensor, components/binary_sensor/cap1188, cap1188.jpg - ESP32 Camera Web Server, components/camera/esp32_camera_web_server, camera.svg, dark-invert + ESP32 Camera Web Server, components/esp32_camera_web_server, camera.svg, dark-invert Improv via Serial, components/improv_serial, improv.svg, dark-invert diff --git a/changelog/v1.12.0.rst b/changelog/v1.12.0.rst index 52a699990a..1b85b6d3d8 100644 --- a/changelog/v1.12.0.rst +++ b/changelog/v1.12.0.rst @@ -10,7 +10,7 @@ Changelog - Version 1.12.0 .. imgtable:: User-Defined Services, components/api.html#user-defined-services, home-assistant.svg, dark-invert - ESP32 Camera, components/camera/esp32_camera, camera.svg, dark-invert + ESP32 Camera, components/esp32_camera, camera.svg, dark-invert MPR121, components/binary_sensor/mpr121, mpr121.jpg SDS011, components/sensor/sds011, sds011.jpg @@ -27,7 +27,7 @@ Before 1.12, it was only possible to transfer data from ESPHome to Home Assistan just define a service in your ESPHome file and call it like any other service from HA. All the rest (like variables, data validation, etc) are handled automatically! -:doc:`ESP32 Camera Support `: This is huge. When integrating cameras +:doc:`ESP32 Camera Support `: This is huge. When integrating cameras into your smart home you'd always have to weigh between security and price; cheap cameras often are very insecure (and sometimes even exposed on the web). And even the pricier ones would sometimes phone back to the manufacturer and upload your data. With ESPHome, everything's 100% diff --git a/components/camera/index.rst b/components/camera/index.rst index e4d78d18be..0098a6fd89 100644 --- a/components/camera/index.rst +++ b/components/camera/index.rst @@ -11,12 +11,12 @@ standardized interface between camera hardware/software implementations and the .. note:: This component cannot be used directly. It serves as the base platform that specific camera - implementations (like :doc:`esp32_camera`) build upon. + implementations (like :doc:`/components/esp32_camera`) build upon. Overview -------- -The camera component acts as a foundation for camera integrations, with :doc:`esp32_camera` being the +The camera component acts as a foundation for camera integrations, with :doc:`/components/esp32_camera` being the first implementation using this framework. All camera implementations in ESPHome inherit from this base component, ensuring a consistent API @@ -29,12 +29,10 @@ Camera Platforms :maxdepth: 1 :glob: - * - See Also -------- -- :doc:`esp32_camera` -- :doc:`esp32_camera_web_server` +- :doc:`/components/esp32_camera` +- :doc:`/components/esp32_camera_web_server` - :apiref:`camera/camera.h` - :ghedit:`Edit` diff --git a/components/camera/esp32_camera.rst b/components/esp32_camera.rst similarity index 100% rename from components/camera/esp32_camera.rst rename to components/esp32_camera.rst diff --git a/components/camera/esp32_camera_web_server.rst b/components/esp32_camera_web_server.rst similarity index 100% rename from components/camera/esp32_camera_web_server.rst rename to components/esp32_camera_web_server.rst diff --git a/components/index.rst b/components/index.rst index 29f7679252..48ca6342e1 100644 --- a/components/index.rst +++ b/components/index.rst @@ -132,6 +132,7 @@ Management and Monitoring StatsD, components/statsd, connection.svg, dark-invert Safe Mode, components/safe_mode, restart-alert.svg, dark-invert Web Server, components/web_server, http.svg + ESP32 Camera Web Server, components/esp32_camera_web_server, camera.svg, dark-invert Update Installation ------------------- @@ -676,15 +677,6 @@ Button Components UART Button, components/button/uart, uart.svg Wake-on-LAN, components/button/wake_on_lan, power_settings.svg, dark-invert -Camera Components ------------------ - -.. imgtable:: - - Camera Core, components/camera/index, folder-open.svg, dark-invert - ESP32 Camera, components/camera/esp32_camera, camera.svg, dark-invert - ESP32 Camera Web Server, components/camera/esp32_camera_web_server, camera.svg, dark-invert - Climate Components ------------------ @@ -1088,6 +1080,7 @@ Miscellaneous Components .. imgtable:: + ESP32 Camera, components/esp32_camera, camera.svg, dark-invert Exposure Notifications, components/exposure_notifications, exposure_notifications.png GPS, components/gps, crosshairs-gps.svg, dark-invert Grow Fingerprint Reader, components/fingerprint_grow, fingerprint.svg, dark-invert