New feature: Added OV5640 Auto-Focus 🎉 (#831)

* New feature: Adeed OV5640 Auto-Focus 🎉

* refactor: make autofocus driver sensor-agnostic

* fix: move TAG definition inside CONFIG_CAMERA_AF_SUPPORT and guard with log level check

---------

Co-authored-by: Me No Dev <me-no-dev@users.noreply.github.com>

Author: AntonioBerna

CMakeLists.txt

@@ -24,11 +24,13 @@ set(include_dirs
 if(IDF_TARGET STREQUAL "esp32" OR IDF_TARGET STREQUAL "esp32s2" OR IDF_TARGET STREQUAL "esp32s3")
   list(APPEND srcs
     driver/esp_camera.c
+    driver/esp_camera_af.c
     driver/cam_hal.c
     driver/sensor.c
     sensors/ov2640.c
     sensors/ov3660.c
     sensors/ov5640.c
+    sensors/ov5640_af.c
     sensors/ov7725.c
     sensors/ov7670.c
     sensors/nt99141.c

Kconfig

@@ -42,6 +42,22 @@ menu "Camera configuration"
             Enable this option if you want to use the OV5640.
             Disable this option to save memory.
 
+    config CAMERA_AF_SUPPORT
+        bool "Enable autofocus (OV5640)"
+        depends on OV5640_SUPPORT
+        default n
+        help
+            Enable OV5640 autofocus support via the esp_camera_af API.
+            If disabled, the AF API will return ESP_ERR_NOT_SUPPORTED.
+
+    config CAMERA_AF_DEFAULT_TIMEOUT_MS
+        int "Autofocus default timeout (ms)"
+        depends on CAMERA_AF_SUPPORT
+        range 100 20000
+        default 2000
+        help
+            Default timeout used for autofocus operations (firmware load, trigger/wait).
+
     config GC2145_SUPPORT
         bool "Support GC2145 2MP"
         default y

README.md

@@ -1,6 +1,7 @@
 # ESP32 Camera Driver
 
 [![Build examples](https://github.com/espressif/esp32-camera/actions/workflows/build.yml/badge.svg)](https://github.com/espressif/esp32-camera/actions/workflows/build.yml) [![Component Registry](https://components.espressif.com/components/espressif/esp32-camera/badge.svg)](https://components.espressif.com/components/espressif/esp32-camera)
+
 ## General Information
 
 This repository hosts ESP32 series Soc compatible driver for image sensors. Additionally it provides a few tools, which allow converting the captured frame data to the more common BMP and JPEG formats.
@@ -43,7 +44,6 @@ This repository hosts ESP32 series Soc compatible driver for image sensors. Addi
 
 ## Installation Instructions
 
-
 ### Using with ESP-IDF
 
 - Add a dependency on `espressif/esp32-camera` component:
@@ -366,5 +366,37 @@ esp_err_t bmp_httpd_handler(httpd_req_t *req){
 }
 ```
 
+### Autofocus (OV5640)
+
+This component includes an optional autofocus helper for OV5640 modules that have an AF-capable lens.
+
+- Enable it in `menuconfig`: `Component config` → `Camera configuration` → `Enable autofocus (OV5640)`.
+- Include the header: `#include "esp_camera_af.h"`.
+
+Basic usage:
+
+```c
+#include "esp_camera.h"
+#include "esp_camera_af.h"
+
+// After esp_camera_init(...)
+sensor_t *s = esp_camera_sensor_get();
+
+esp_camera_af_config_t af_cfg = {
+    .mode = ESP_CAMERA_AF_MODE_AUTO,
+    .timeout_ms = 2000,
+};
+
+ESP_ERROR_CHECK(esp_camera_af_init(s, &af_cfg));
+
+// Optional: trigger a single AF cycle and wait for completion
+ESP_ERROR_CHECK(esp_camera_af_trigger(s));
+
+esp_camera_af_status_t st;
+ESP_ERROR_CHECK(esp_camera_af_wait(s, 0, &st));
+```
 
+Notes:
 
+- If autofocus is disabled (or the sensor is not OV5640), the AF APIs return `ESP_ERR_NOT_SUPPORTED`.
+- OV5640 autofocus relies on loading an internal firmware blob over SCCB during `esp_camera_af_init()`.

driver/esp_camera_af.c

@@ -0,0 +1,215 @@
+#include "sdkconfig.h"
+
+#include "esp_camera_af.h"
+
+#include <string.h>
+
+#include "freertos/FreeRTOS.h"
+#include "freertos/task.h"
+#include "esp_timer.h"
+
+#ifndef CONFIG_CAMERA_AF_DEFAULT_TIMEOUT_MS
+#define CONFIG_CAMERA_AF_DEFAULT_TIMEOUT_MS 2000
+#endif
+
+#if defined(CONFIG_CAMERA_AF_SUPPORT) && CONFIG_CAMERA_AF_SUPPORT
+
+#if defined(ARDUINO_ARCH_ESP32) && defined(CONFIG_ARDUHAL_ESP_LOG)
+#include "esp32-hal-log.h"
+#define TAG ""
+#else
+#include "esp_log.h"
+#if CONFIG_LOG_DEFAULT_LEVEL > 0
+static const char *TAG = "camera_af";
+#endif
+#endif
+
+static uint32_t s_default_timeout_ms = CONFIG_CAMERA_AF_DEFAULT_TIMEOUT_MS;
+
+bool esp_camera_af_is_supported(const sensor_t *sensor)
+{
+    if (!sensor || !sensor->af_is_supported) {
+        return false;
+    }
+    return sensor->af_is_supported((sensor_t *)sensor) != 0;
+}
+
+esp_err_t esp_camera_af_init(sensor_t *sensor, const esp_camera_af_config_t *config)
+{
+    if (!sensor || !config) {
+        return ESP_ERR_INVALID_ARG;
+    }
+
+    if (config->timeout_ms) {
+        s_default_timeout_ms = config->timeout_ms;
+    }
+
+    if (!esp_camera_af_is_supported(sensor)) {
+        return ESP_ERR_NOT_SUPPORTED;
+    }
+
+    if (!sensor->af_init) {
+        return ESP_ERR_NOT_SUPPORTED;
+    }
+
+    int ret = sensor->af_init(sensor, s_default_timeout_ms);
+    if (ret < 0) {
+        ESP_LOGE(TAG, "AF init failed");
+        return ESP_FAIL;
+    }
+
+    return esp_camera_af_set_mode(sensor, config->mode);
+}
+
+esp_err_t esp_camera_af_set_mode(sensor_t *sensor, esp_camera_af_mode_t mode)
+{
+    if (!sensor) {
+        return ESP_ERR_INVALID_ARG;
+    }
+    if (!esp_camera_af_is_supported(sensor)) {
+        return ESP_ERR_NOT_SUPPORTED;
+    }
+
+    if (!sensor->af_set_mode) {
+        return ESP_ERR_NOT_SUPPORTED;
+    }
+
+    int ret = sensor->af_set_mode(sensor, (int)mode);
+    return (ret == 0) ? ESP_OK : ESP_FAIL;
+}
+
+esp_err_t esp_camera_af_trigger(sensor_t *sensor)
+{
+    if (!sensor) {
+        return ESP_ERR_INVALID_ARG;
+    }
+    if (!esp_camera_af_is_supported(sensor)) {
+        return ESP_ERR_NOT_SUPPORTED;
+    }
+
+    if (!sensor->af_trigger) {
+        return ESP_ERR_NOT_SUPPORTED;
+    }
+
+    int ret = sensor->af_trigger(sensor);
+    return (ret == 0) ? ESP_OK : ESP_FAIL;
+}
+
+esp_err_t esp_camera_af_get_status(sensor_t *sensor, esp_camera_af_status_t *out_status)
+{
+    if (!sensor || !out_status) {
+        return ESP_ERR_INVALID_ARG;
+    }
+    if (!esp_camera_af_is_supported(sensor)) {
+        return ESP_ERR_NOT_SUPPORTED;
+    }
+
+    if (!sensor->af_get_status) {
+        return ESP_ERR_NOT_SUPPORTED;
+    }
+
+    memset(out_status, 0, sizeof(*out_status));
+    int ret = sensor->af_get_status(sensor, &out_status->raw, &out_status->focused, &out_status->busy);
+    return (ret == 0) ? ESP_OK : ESP_FAIL;
+}
+
+esp_err_t esp_camera_af_wait(sensor_t *sensor, uint32_t timeout_ms, esp_camera_af_status_t *out_status)
+{
+    if (!sensor || !out_status) {
+        return ESP_ERR_INVALID_ARG;
+    }
+    if (!esp_camera_af_is_supported(sensor)) {
+        return ESP_ERR_NOT_SUPPORTED;
+    }
+
+    if (!timeout_ms) {
+        timeout_ms = s_default_timeout_ms;
+    }
+
+    const uint64_t start = esp_timer_get_time();
+    while (true) {
+        esp_err_t ret = esp_camera_af_get_status(sensor, out_status);
+        if (ret != ESP_OK) {
+            return ret;
+        }
+
+        if (!out_status->busy) {
+            return ESP_OK;
+        }
+
+        if (timeout_ms && ((esp_timer_get_time() - start) / 1000ULL) > timeout_ms) {
+            return ESP_ERR_TIMEOUT;
+        }
+
+        vTaskDelay(pdMS_TO_TICKS(5));
+    }
+}
+
+esp_err_t esp_camera_af_set_manual_position(sensor_t *sensor, uint16_t position)
+{
+    if (!sensor) {
+        return ESP_ERR_INVALID_ARG;
+    }
+    if (!esp_camera_af_is_supported(sensor)) {
+        return ESP_ERR_NOT_SUPPORTED;
+    }
+
+    if (!sensor->af_set_manual_position) {
+        return ESP_ERR_NOT_SUPPORTED;
+    }
+
+    int ret = sensor->af_set_manual_position(sensor, position);
+    return (ret == 0) ? ESP_OK : ESP_FAIL;
+}
+
+#else // CONFIG_CAMERA_AF_SUPPORT
+
+bool esp_camera_af_is_supported(const sensor_t *sensor)
+{
+    (void)sensor;
+    return false;
+}
+
+esp_err_t esp_camera_af_init(sensor_t *sensor, const esp_camera_af_config_t *config)
+{
+    (void)sensor;
+    (void)config;
+    return ESP_ERR_NOT_SUPPORTED;
+}
+
+esp_err_t esp_camera_af_set_mode(sensor_t *sensor, esp_camera_af_mode_t mode)
+{
+    (void)sensor;
+    (void)mode;
+    return ESP_ERR_NOT_SUPPORTED;
+}
+
+esp_err_t esp_camera_af_trigger(sensor_t *sensor)
+{
+    (void)sensor;
+    return ESP_ERR_NOT_SUPPORTED;
+}
+
+esp_err_t esp_camera_af_get_status(sensor_t *sensor, esp_camera_af_status_t *out_status)
+{
+    (void)sensor;
+    (void)out_status;
+    return ESP_ERR_NOT_SUPPORTED;
+}
+
+esp_err_t esp_camera_af_wait(sensor_t *sensor, uint32_t timeout_ms, esp_camera_af_status_t *out_status)
+{
+    (void)sensor;
+    (void)timeout_ms;
+    (void)out_status;
+    return ESP_ERR_NOT_SUPPORTED;
+}
+
+esp_err_t esp_camera_af_set_manual_position(sensor_t *sensor, uint16_t position)
+{
+    (void)sensor;
+    (void)position;
+    return ESP_ERR_NOT_SUPPORTED;
+}
+
+#endif // CONFIG_CAMERA_AF_SUPPORT