ESPHome 2026.11.0b6
Loading...
Searching...
No Matches
esp32_camera.h
Go to the documentation of this file.
1#pragma once
2
3#ifdef USE_ESP32
4
5#include <atomic>
6#include <esp_camera.h>
7#include <freertos/FreeRTOS.h>
8#include <freertos/queue.h>
13
14#ifdef USE_I2C
16#endif // USE_I2C
17
18namespace esphome::esp32_camera {
19
20class ESP32Camera;
21
42
54
56 ESP32_GAINCEILING_2X = GAINCEILING_2X,
57 ESP32_GAINCEILING_4X = GAINCEILING_4X,
58 ESP32_GAINCEILING_8X = GAINCEILING_8X,
59 ESP32_GAINCEILING_16X = GAINCEILING_16X,
60 ESP32_GAINCEILING_32X = GAINCEILING_32X,
61 ESP32_GAINCEILING_64X = GAINCEILING_64X,
62 ESP32_GAINCEILING_128X = GAINCEILING_128X,
63};
64
69
77
87
88#ifdef USE_ESP32_CAMERA_CAPTURE
89enum class CaptureState : uint8_t {
90 CAPTURE_STATE_IDLE, // no single image capture running
91 CAPTURE_STATE_WAITING, // on_capture_start fired, waiting for capture_delay
92 CAPTURE_STATE_CAPTURING, // waiting for the first frame started after the delay
93 CAPTURE_STATE_ENDED, // on_capture_end fired, the next frame is delivered as is
94};
95#endif // USE_ESP32_CAMERA_CAPTURE
96
97/* ---------------- CameraImage class ---------------- */
99 public:
100 ESP32CameraImage(camera_fb_t *buffer, uint8_t requester);
101 camera_fb_t *get_raw_buffer();
102 uint8_t *get_data_buffer() override;
103 size_t get_data_length() override;
104 bool was_requested_by(camera::CameraRequester requester) const override;
105
106 protected:
107 camera_fb_t *buffer_;
108 uint8_t requesters_;
109};
110
112 uint8_t *data;
113 size_t length;
114};
115
116/* ---------------- CameraImageReader class ---------------- */
118 public:
119 void set_image(std::shared_ptr<camera::CameraImage> image) override;
120 size_t available() const override;
121 uint8_t *peek_data_buffer() override;
122 void consume_data(size_t consumed) override;
123 void return_image() override;
124
125 protected:
126 std::shared_ptr<ESP32CameraImage> image_;
127 size_t offset_{0};
128};
129
130/* ---------------- ESP32Camera class ---------------- */
131class ESP32Camera final : public camera::Camera {
132 public:
133 ESP32Camera();
134
135 /* setters */
136 /* -- pin assignment */
137 void set_data_pins(std::array<uint8_t, 8> pins);
138 void set_vsync_pin(uint8_t pin);
139 void set_href_pin(uint8_t pin);
140 void set_pixel_clock_pin(uint8_t pin);
141 void set_external_clock(uint8_t pin, uint32_t frequency);
142 void set_i2c_pins(uint8_t sda, uint8_t scl);
143#ifdef USE_I2C
144 void set_i2c_id(i2c::InternalI2CBus *i2c_bus);
145#endif // USE_I2C
146 void set_reset_pin(uint8_t pin);
147 void set_power_down_pin(uint8_t pin);
148 /* -- image */
151 void set_jpeg_quality(uint8_t quality);
152 void set_vertical_flip(bool vertical_flip) { this->vertical_flip_ = vertical_flip; }
153 void set_horizontal_mirror(bool horizontal_mirror) { this->horizontal_mirror_ = horizontal_mirror; }
154 void set_contrast(int contrast) { this->contrast_ = contrast; }
155 void set_brightness(int brightness) { this->brightness_ = brightness; }
156 void set_saturation(int saturation) { this->saturation_ = saturation; }
158 /* -- exposure */
160 void set_aec2(bool aec2) { this->aec2_ = aec2; }
161 void set_ae_level(int ae_level) { this->ae_level_ = ae_level; }
162 void set_aec_value(uint32_t aec_value) { this->aec_value_ = aec_value; }
163 /* -- gains */
165 void set_agc_value(uint8_t agc_value) { this->agc_value_ = agc_value; }
166 void set_agc_gain_ceiling(ESP32AgcGainCeiling gain_ceiling) { this->agc_gain_ceiling_ = gain_ceiling; }
167 /* -- white balance */
169 /* -- test */
170 void set_test_pattern(bool test_pattern) { this->test_pattern_ = test_pattern; }
171 /* -- framerates */
172 void set_max_update_interval(uint32_t max_update_interval);
173 void set_idle_update_interval(uint32_t idle_update_interval);
174 /* -- frame buffer */
175 void set_frame_buffer_mode(camera_grab_mode_t mode);
176 void set_frame_buffer_count(uint8_t fb_count);
177 void set_frame_buffer_location(camera_fb_location_t fb_location);
178#ifdef USE_ESP32_CAMERA_CAPTURE
179 /* -- single image capture */
180 void set_capture_delay(uint16_t capture_delay) { this->capture_delay_ = capture_delay; }
182 template<typename F> void add_on_capture_callback(F &&callback) {
183 this->capture_callback_.add(std::forward<F>(callback));
184 }
185#endif // USE_ESP32_CAMERA_CAPTURE
186
187 /* public API (derivated) */
188 void setup() override;
189 void loop() override;
190 void dump_config() override;
191#ifdef USE_ESP32_CAMERA_CAPTURE
192 void on_shutdown() override;
193#endif
194 /* public API (specific) */
195 void start_stream(camera::CameraRequester requester) override;
196 void stop_stream(camera::CameraRequester requester) override;
197 void request_image(camera::CameraRequester requester) override;
199
200#ifdef USE_ESP32_CAMERA_WINDOW
202 struct Window {
203 int offset_x{0};
204 int offset_y{0};
205 int width{0};
206 int height{0};
207 };
208
213 bool set_window(int offset_x, int offset_y, int width, int height);
214
216 bool reset_window();
217
219 bool supports_window() const;
220
222 void set_initial_window(int offset_x, int offset_y, int width, int height) {
223 this->window_ = {offset_x, offset_y, width, height};
224 }
225#endif // USE_ESP32_CAMERA_WINDOW
226
228 void add_listener(camera::CameraListener *listener) override { this->listeners_.push_back(listener); }
230
231 protected:
232 /* internal methods */
233 bool has_requested_image_() const;
234 bool can_return_image_() const;
235#ifdef USE_ESP32_CAMERA_CAPTURE
236 void cancel_capture_();
237 bool advance_capture_(uint32_t now, uint8_t requesters);
238 bool advance_capture_with_frame_(const camera_fb_t *fb);
239 void end_capture_();
241#endif // USE_ESP32_CAMERA_CAPTURE
242
243 static void framebuffer_task(void *pv);
244
245#ifdef USE_ESP32_CAMERA_WINDOW
246 void apply_window_();
247 void dump_window_config_(sensor_t *sensor);
248 sensor_t *window_sensor_() const;
249
250 // The window in effect (before setup() the configured one); a width of 0 means none
252#endif // USE_ESP32_CAMERA_WINDOW
253
254 /* attributes */
255 /* camera configuration */
256 camera_config_t config_{};
257 /* -- image */
258 bool vertical_flip_{true};
260 int contrast_{0};
264 /* -- exposure */
266 bool aec2_{false};
267 int ae_level_{0};
269 /* -- gains */
271 uint8_t agc_value_{0};
273 /* -- white balance */
275 /* -- Test */
276 bool test_pattern_{false};
277 /* -- framerates */
280
281 esp_err_t init_error_{ESP_OK};
282 std::shared_ptr<ESP32CameraImage> current_image_;
283 std::atomic<uint8_t> single_requesters_{0};
284 std::atomic<uint8_t> stream_requesters_{0};
287 std::vector<camera::CameraListener *> listeners_;
288
291#if ESPHOME_LOG_LEVEL < ESPHOME_LOG_LEVEL_VERBOSE
293 uint16_t frame_count_{0};
294#endif
295#ifdef USE_I2C
297#endif // USE_I2C
298#ifdef USE_ESP32_CAMERA_CAPTURE
300 uint32_t capture_started_{0}; // loop time of on_capture_start
301 uint32_t capture_ready_ms_{0}; // esp_timer time in ms when the delay ended, the clock of fb->timestamp
302 uint16_t capture_delay_{0};
304#endif // USE_ESP32_CAMERA_CAPTURE
306};
307
308class ESP32CameraImageTrigger final : public Trigger<CameraImageData>, public camera::CameraListener {
309 public:
310 explicit ESP32CameraImageTrigger(ESP32Camera *parent) { parent->add_listener(this); }
311 void on_camera_image(const std::shared_ptr<camera::CameraImage> &image) override {
312 CameraImageData camera_image_data{};
313 camera_image_data.length = image->get_data_length();
314 camera_image_data.data = image->get_data_buffer();
315 this->trigger(camera_image_data);
316 }
317};
318
320 public:
321 explicit ESP32CameraStreamStartTrigger(ESP32Camera *parent) { parent->add_listener(this); }
322 void on_stream_start() override { this->trigger(); }
323};
324
326 public:
327 explicit ESP32CameraStreamStopTrigger(ESP32Camera *parent) { parent->add_listener(this); }
328 void on_stream_stop() override { this->trigger(); }
329};
330
331} // namespace esphome::esp32_camera
332
333#endif
BedjetMode mode
BedJet operating mode.
uint16_le_t frequency
Definition bl0942.h:6
An STL allocator that uses SPI or internal RAM.
Definition helpers.h:2396
void trigger(const Ts &...x) ESPHOME_ALWAYS_INLINE
Definition automation.h:557
Abstract camera base class.
Definition camera.h:116
Abstract camera image base class.
Definition camera.h:57
Abstract image reader base class.
Definition camera.h:71
Listener interface for camera events.
Definition camera.h:46
void set_i2c_pins(uint8_t sda, uint8_t scl)
void set_agc_value(uint8_t agc_value)
void set_test_pattern(bool test_pattern)
void set_jpeg_quality(uint8_t quality)
void set_wb_mode(ESP32WhiteBalanceMode mode)
ESP32AgcGainCeiling agc_gain_ceiling_
void set_vertical_flip(bool vertical_flip)
void set_aec_value(uint32_t aec_value)
void set_special_effect(ESP32SpecialEffect effect)
void set_aec_mode(ESP32GainControlMode mode)
LazyCallbackManager< void(bool)> capture_callback_
bool set_window(int offset_x, int offset_y, int width, int height)
Read out the given rectangle of the frame, replacing any previous window.
void set_data_pins(std::array< uint8_t, 8 > pins)
void stop_stream(camera::CameraRequester requester) override
std::vector< camera::CameraListener * > listeners_
void set_i2c_id(i2c::InternalI2CBus *i2c_bus)
void set_pixel_format(ESP32CameraPixelFormat format)
void set_frame_size(ESP32CameraFrameSize size)
void set_brightness(int brightness)
void add_on_capture_callback(F &&callback)
Called with true on capture start and false on capture end.
void set_external_clock(uint8_t pin, uint32_t frequency)
bool reset_window()
Read out the whole sensor again; changing the frame size does the same.
void set_max_update_interval(uint32_t max_update_interval)
std::shared_ptr< ESP32CameraImage > current_image_
std::atomic< uint8_t > single_requesters_
void set_initial_window(int offset_x, int offset_y, int width, int height)
Window to apply at the end of setup(), in frame pixels.
void set_horizontal_mirror(bool horizontal_mirror)
void set_capture_delay(uint16_t capture_delay)
bool supports_window() const
True when the sensor takes a window in the configured pixel format; meant for lambdas.
camera::CameraImageReader * create_image_reader() override
bool advance_capture_(uint32_t now, uint8_t requesters)
void set_frame_buffer_count(uint8_t fb_count)
void set_agc_gain_ceiling(ESP32AgcGainCeiling gain_ceiling)
void set_saturation(int saturation)
void set_agc_mode(ESP32GainControlMode mode)
bool advance_capture_with_frame_(const camera_fb_t *fb)
void set_frame_buffer_location(camera_fb_location_t fb_location)
void set_frame_buffer_mode(camera_grab_mode_t mode)
void set_idle_update_interval(uint32_t idle_update_interval)
void start_stream(camera::CameraRequester requester) override
void request_image(camera::CameraRequester requester) override
void add_listener(camera::CameraListener *listener) override
Add a listener to receive camera events.
std::atomic< uint8_t > stream_requesters_
static void framebuffer_task(void *pv)
RAMAllocator< camera_fb_t > fb_allocator_
bool was_requested_by(camera::CameraRequester requester) const override
ESP32CameraImage(camera_fb_t *buffer, uint8_t requester)
void set_image(std::shared_ptr< camera::CameraImage > image) override
std::shared_ptr< ESP32CameraImage > image_
void consume_data(size_t consumed) override
void on_camera_image(const std::shared_ptr< camera::CameraImage > &image) override
uint32_t buffer
Definition gif.cpp:50
const char * format
CameraRequester
Different sources for filtering.
Definition camera.h:16
uint16_t size
Definition helpers.cpp:34
static void uint32_t
A rectangle, with (0, 0) at the top left, in the pixels of whatever it is measured against.