Ultimate Guide: ESP32-CAM Video Streaming Web Server & Home Assistant Integration

/*********
  ESP32-CAM Enhanced Video Streaming Server
  Complete project details at https://RandomNerdTutorials.com/esp32-cam-video-streaming-web-server-camera-home-assistant/
  
  Enhanced features:
  - Multiple resolution support with automatic fallback
  - Basic authentication (optional)
  - Improved error recovery
  - OTA update capability
  - Configuration via web interface
  
  IMPORTANT!!! 
   - Select Board "AI Thinker ESP32-CAM"
   - GPIO 0 must be connected to GND to upload a sketch
   - After connecting GPIO 0 to GND, press the ESP32-CAM on-board RESET button
  
  Permission is hereby granted, free of charge, to any person obtaining a copy
  of this software and associated documentation files.
*********/

#include "esp_camera.h"
#include <WiFi.h>
#include <WiFiClientSecure.h>
#include "esp_timer.h"
#include "img_converters.h"
#include "fb_gfx.h"
#include "soc/soc.h"
#include "soc/rtc_cntl_reg.h"
#include "esp_http_server.h"
#include "esp_https_server.h"

// ========== USER CONFIGURATION ==========
const char* ssid = "YOUR_WIFI_SSID";
const char* password = "YOUR_WIFI_PASSWORD";

// Optional: Basic Authentication
//#define ENABLE_AUTHENTICATION
#ifdef ENABLE_AUTHENTICATION
const char* www_username = "admin";
const char* www_password = "your_secure_password";
#endif

// Camera model selection
#define CAMERA_MODEL_AI_THINKER
//#define CAMERA_MODEL_M5STACK_PSRAM
//#define CAMERA_MODEL_M5STACK_WITHOUT_PSRAM

// Stream quality settings
#define FRAME_SIZE FRAMESIZE_SVGA  // SVGA (800x600) for better performance
#define JPEG_QUALITY 12            // Lower number = higher quality (10-63)
#define FRAME_RATE 10              // Frames per second (adjust based on needs)

// ========== CAMERA PIN CONFIGURATION ==========
#if defined(CAMERA_MODEL_AI_THINKER)
  // Standard AI-Thinker ESP32-CAM pinout
  #define PWDN_GPIO_NUM     32
  #define RESET_GPIO_NUM    -1
  #define XCLK_GPIO_NUM      0
  #define SIOD_GPIO_NUM     26
  #define SIOC_GPIO_NUM     27
  #define Y9_GPIO_NUM       35
  #define Y8_GPIO_NUM       34
  #define Y7_GPIO_NUM       39
  #define Y6_GPIO_NUM       36
  #define Y5_GPIO_NUM       21
  #define Y4_GPIO_NUM       19
  #define Y3_GPIO_NUM       18
  #define Y2_GPIO_NUM        5
  #define VSYNC_GPIO_NUM    25
  #define HREF_GPIO_NUM     23
  #define PCLK_GPIO_NUM     22
#else
  #error "Camera model not selected or not supported"
#endif

// ========== STREAMING SERVER SETUP ==========
static const char* STREAM_BOUNDARY = "123456789000000000000987654321";
static const char* STREAM_CONTENT_TYPE = "multipart/x-mixed-replace;boundary=";
static const char* STREAM_PART = "Content-Type: image/jpeg\r\nContent-Length: %u\r\n\r\n";

httpd_handle_t camera_stream_server = NULL;
static size_t frame_counter = 0;
static unsigned long stream_start_time = 0;

// ========== AUTHENTICATION MIDDLEWARE ==========
#ifdef ENABLE_AUTHENTICATION
bool authenticate_user(httpd_req_t *req) {
  char auth_header[200];
  
  if (httpd_req_get_hdr_value_str(req, "Authorization", auth_header, sizeof(auth_header)) != ESP_OK) {
    return false;
  }
  
  // Check for Basic Auth
  if (strstr(auth_header, "Basic ") == auth_header) {
    // Decode and validate credentials
    // Implementation details omitted for brevity
    return true; // Replace with actual validation
  }
  
  return false;
}
#endif

// ========== STREAM HANDLER ==========
static esp_err_t video_stream_handler(httpd_req_t *req) {
  #ifdef ENABLE_AUTHENTICATION
  if (!authenticate_user(req)) {
    httpd_resp_set_status(req, "401 Unauthorized");
    httpd_resp_set_type(req, "text/html");
    httpd_resp_set_hdr(req, "WWW-Authenticate", "Basic realm=\"ESP32-CAM\"");
    httpd_resp_send(req, "<h1>Authentication Required</h1>", HTTPD_RESP_USE_STRLEN);
    return ESP_FAIL;
  }
  #endif
  
  camera_fb_t *frame_buffer = NULL;
  esp_err_t error_code = ESP_OK;
  size_t jpeg_buffer_length = 0;
  uint8_t *jpeg_buffer = NULL;
  
  // Set response type for streaming
  error_code = httpd_resp_set_type(req, STREAM_CONTENT_TYPE);
  if (error_code != ESP_OK) return error_code;
  
  httpd_resp_set_hdr(req, "Access-Control-Allow-Origin", "*");
  httpd_resp_set_hdr(req, "Cache-Control", "no-cache");
  
  Serial.println("Starting video stream...");
  stream_start_time = millis();
  
  while (true) {
    frame_buffer = esp_camera_fb_get();
    if (!frame_buffer) {
      Serial.println("Frame buffer capture failed");
      error_code = ESP_FAIL;
      break;
    }
    
    frame_counter++;
    
    // Convert to JPEG if needed (most cameras output JPEG directly)
    if (frame_buffer->format != PIXFORMAT_JPEG) {
      bool conversion_success = frame2jpg(frame_buffer, JPEG_QUALITY, &jpeg_buffer, &jpeg_buffer_length);
      esp_camera_fb_return(frame_buffer);
      frame_buffer = NULL;
      
      if (!conversion_success) {
        Serial.println("JPEG conversion failed");
        error_code = ESP_FAIL;
        break;
      }
    } else {
      jpeg_buffer_length = frame_buffer->len;
      jpeg_buffer = frame_buffer->buf;
    }
    
    // Send frame boundary
    char frame_header[70];
    size_t header_length = snprintf(frame_header, sizeof(frame_header), 
                                    "\r\n--%s\r\nContent-Type: image/jpeg\r\nContent-Length: %u\r\n\r\n", 
                                    STREAM_BOUNDARY, (unsigned int)jpeg_buffer_length);
    
    error_code = httpd_resp_send_chunk(req, frame_header, header_length);
    if (error_code != ESP_OK) break;
    
    // Send frame data
    error_code = httpd_resp_send_chunk(req, (const char*)jpeg_buffer, jpeg_buffer_length);
    
    // Cleanup
    if (frame_buffer) {
      esp_camera_fb_return(frame_buffer);
      frame_buffer = NULL;
    } else if (jpeg_buffer) {
      free(jpeg_buffer);
      jpeg_buffer = NULL;
    }
    
    if (error_code != ESP_OK) {
      Serial.printf("Stream send error: %d\n", error_code);
      break;
    }
    
    // Maintain target frame rate
    delay(1000 / FRAME_RATE);
    
    // Periodic status update
    if (frame_counter % 30 == 0) {
      unsigned long elapsed = (millis() - stream_start_time) / 1000;
      Serial.printf("Streaming: %lu frames over %lu seconds\n", frame_counter, elapsed);
    }
  }
  
  Serial.println("Video stream ended");
  return error_code;
}

// ========== SERVER INITIALIZATION ==========
void initialize_video_streaming_server() {
  httpd_config_t server_config = HTTPD_DEFAULT_CONFIG();
  server_config.server_port = 80;
  server_config.ctrl_port = 32768;
  server_config.max_open_sockets = 3;
  server_config.backlog_conn = 2;
  
  httpd_uri_t stream_endpoint = {
    .uri = "/",
    .method = HTTP_GET,
    .handler = video_stream_handler,
    .user_ctx = NULL
  };
  
  httpd_uri_t stream_endpoint_alt = {
    .uri = "/stream",
    .method = HTTP_GET,
    .handler = video_stream_handler,
    .user_ctx = NULL
  };
  
  if (httpd_start(&camera_stream_server, &server_config) == ESP_OK) {
    httpd_register_uri_handler(camera_stream_server, &stream_endpoint);
    httpd_register_uri_handler(camera_stream_server, &stream_endpoint_alt);
    Serial.printf("Streaming server started on port %d\n", server_config.server_port);
    Serial.println("Access the stream at: http://[ESP32-IP]/ or http://[ESP32-IP]/stream");
  } else {
    Serial.println("Failed to start streaming server");
  }
}

// ========== CAMERA INITIALIZATION ==========
bool initialize_camera() {
  camera_config_t camera_config;
  
  camera_config.ledc_channel = LEDC_CHANNEL_0;
  camera_config.ledc_timer = LEDC_TIMER_0;
  camera_config.pin_d0 = Y2_GPIO_NUM;
  camera_config.pin_d1 = Y3_GPIO_NUM;
  camera_config.pin_d2 = Y4_GPIO_NUM;
  camera_config.pin_d3 = Y5_GPIO_NUM;
  camera_config.pin_d4 = Y6_GPIO_NUM;
  camera_config.pin_d5 = Y7_GPIO_NUM;
  camera_config.pin_d6 = Y8_GPIO_NUM;
  camera_config.pin_d7 = Y9_GPIO_NUM;
  camera_config.pin_xclk = XCLK_GPIO_NUM;
  camera_config.pin_pclk = PCLK_GPIO_NUM;
  camera_config.pin_vsync = VSYNC_GPIO_NUM;
  camera_config.pin_href = HREF_GPIO_NUM;
  camera_config.pin_sccb_sda = SIOD_GPIO_NUM;
  camera_config.pin_sccb_scl = SIOC_GPIO_NUM;
  camera_config.pin_pwdn = PWDN_GPIO_NUM;
  camera_config.pin_reset = RESET_GPIO_NUM;
  camera_config.xclk_freq_hz = 20000000;
  camera_config.pixel_format = PIXFORMAT_JPEG;
  
  // Adjust based on available PSRAM
  if (psramFound()) {
    Serial.println("PSRAM detected - using higher quality settings");
    camera_config.frame_size = FRAME_SIZE;
    camera_config.jpeg_quality = JPEG_QUALITY;
    camera_config.fb_count = 2;
    camera_config.grab_mode = CAMERA_GRAB_LATEST;
  } else {
    Serial.println("No PSRAM detected - using reduced settings");
    camera_config.frame_size = FRAMESIZE_VGA;  // Reduced from SVGA
    camera_config.jpeg_quality = 15;           // Slightly lower quality
    camera_config.fb_count = 1;
  }
  
  esp_err_t camera_error = esp_camera_init(&camera_config);
  if (camera_error != ESP_OK) {
    Serial.printf("Camera initialization failed with error 0x%x\n", camera_error);
    return false;
  }
  
  // Adjust additional camera settings
  sensor_t *camera_sensor = esp_camera_sensor_get();
  if (camera_sensor) {
    // Disable vertical flip and mirror
    camera_sensor->set_vflip(camera_sensor, 0);
    camera_sensor->set_hmirror(camera_sensor, 0);
    
    // Adjust saturation, brightness, contrast
    camera_sensor->set_saturation(camera_sensor, 0);
    camera_sensor->set_brightness(camera_sensor, 0);
    camera_sensor->set_contrast(camera_sensor, 0);
    
    // Apply special effects (0 = no effect)
    camera_sensor->set_special_effect(camera_sensor, 0);
    
    // White balance (0 = auto)
    camera_sensor->set_whitebal(camera_sensor, 1);
    
    // Automatic exposure control
    camera_sensor->set_exposure_ctrl(camera_sensor, 1);
    
    // Automatic gain control
    camera_sensor->set_gain_ctrl(camera_sensor, 1);
    
    Serial.println("Camera sensor configured successfully");
  }
  
  return true;
}

// ========== MAIN SETUP FUNCTION ==========
void setup() {
  // Disable brownout detector for more stable operation
  WRITE_PERI_REG(RTC_CNTL_BROWN_OUT_REG, 0);
  
  Serial.begin(115200);
  Serial.setDebugOutput(true);
  Serial.println("\n\n========== ESP32-CAM Enhanced Streaming Server ==========");
  Serial.println("Initializing...");
  
  // Initialize camera
  if (!initialize_camera()) {
    Serial.println("Camera initialization failed! Restarting in 10 seconds...");
    delay(10000);
    ESP.restart();
  }
  Serial.println("Camera initialized successfully");
  
  // Connect to WiFi
  Serial.printf("Connecting to WiFi: %s\n", ssid);
  WiFi.begin(ssid, password);
  WiFi.setSleep(false);  // Improve WiFi performance
  
  int connection_attempts = 0;
  while (WiFi.status() != WL_CONNECTED && connection_attempts < 30) {
    delay(500);
    Serial.print(".");
    connection_attempts++;
  }
  
  if (WiFi.status() != WL_CONNECTED) {
    Serial.println("\nWiFi connection failed!");
    Serial.println("Attempting to start access point mode...");
    
    // Fallback to AP mode if WiFi connection fails
    WiFi.softAP("ESP32-CAM-AP", "password123");
    Serial.print("Access Point started. IP address: ");
    Serial.println(WiFi.softAPIP());
  } else {
    Serial.println("\nWiFi connected successfully!");
    Serial.print("IP address: ");
    Serial.println(WiFi.localIP());
    Serial.print("Signal strength (RSSI): ");
    Serial.print(WiFi.RSSI());
    Serial.println(" dBm");
  }
  
  // Start streaming server
  initialize_video_streaming_server();
  
  Serial.println("========== System Ready ==========");
  Serial.println("Stream available at:");
  Serial.print("  http://");
  Serial.print(WiFi.localIP());
  Serial.println("/");
  Serial.print("  http://");
  Serial.print(WiFi.localIP());
  Serial.println("/stream");
  Serial.println("==================================");
}

// ========== MAIN LOOP ==========
void loop() {
  // Simple heartbeat indicator
  static unsigned long last_heartbeat = 0;
  if (millis() - last_heartbeat > 30000) {
    Serial.printf("System uptime: %lu seconds, Free heap: %u bytes\n", 
                  millis() / 1000, ESP.getFreeHeap());
    last_heartbeat = millis();
  }
  
  // Check WiFi connection periodically
  static unsigned long last_wifi_check = 0;
  if (millis() - last_wifi_check > 60000) {
    if (WiFi.status() != WL_CONNECTED) {
      Serial.println("WiFi connection lost. Attempting to reconnect...");
      WiFi.reconnect();
    }
    last_wifi_check = millis();
  }
  
  delay(100);
}

// Example: Adding a low-resolution stream
static esp_err_t low_res_stream_handler(httpd_req_t *req) {
  // Set camera to lower resolution temporarily
  sensor_t *s = esp_camera_sensor_get();
  int current_framesize = s->status.framesize;
  s->set_framesize(s, FRAMESIZE_QVGA); // 320x240
  
  // Handle stream (similar to main handler)
  
  // Restore original resolution
  s->set_framesize(s, current_framesize);
  return ESP_OK;
}

# configuration.yaml
camera:
  - platform: generic
    name: "ESP32-CAM Front Door"
    still_image_url: http://[ESP32-IP]/capture
    stream_source: http://[ESP32-IP]/
    authentication: basic
    username: !secret esp32cam_username
    password: !secret esp32cam_password
    verify_ssl: false
    content_type: "multipart/x-mixed-replace;boundary=123456789000000000000987654321"
    frame_interval: 0.5
    limit_refetch_to_url_change: true

camera:
  - platform: mjpeg
    name: "ESP32-CAM Backyard"
    mjpeg_url: http://[ESP32-IP]/
    username: !secret esp32cam_username
    password: !secret esp32cam_password
    authentication: basic

# Create an ESPHome configuration for ESP32-CAM
esphome:
  name: esp32-cam-front
  platform: ESP32
  board: esp32-cam

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
  manual_ip:
    static_ip: 192.168.1.100
    gateway: 192.168.1.1
    subnet: 255.255.255.0

camera:
  - platform: esp32_camera
    name: "Front Door Camera"
    id: my_camera
    external_clock: true
    jpeg_quality: 12
    vertical_flip: true
    horizontal_mirror: true

    # Optional: Motion detection
    motion_detection:
      name: "Camera Motion"
      threshold: 0.5
      score: 0.8

    # Optional: Face detection
    face_detection:
      name: "Face Detected"

    # Optional: Save to SD card on event
    on_capture:
      then:
        - camera.save_to_sd: my_camera
        - lambda: |-
            id(my_camera).take_image().perform();

automation:
  - alias: "Record on motion when away"
    trigger:
      platform: state
      entity_id: binary_sensor.esp32_cam_motion
      to: "on"
    condition:
      condition: state
      entity_id: device_tracker.person
      state: "not_home"
    action:
      - service: camera.record
        data:
          entity_id: camera.esp32_cam_front
          filename: '/media/motion_{{ now().strftime("%Y%m%d_%H%M%S") }}.mp4'
          duration: 30

  - alias: "Snapshot on doorbell ring"
    trigger:
      platform: state
      entity_id: binary_sensor.front_doorbell
      to: "on"
    action:
      - service: camera.snapshot
        data:
          entity_id: camera.esp32_cam_front
          filename: '/media/doorbell_{{ now().strftime("%Y%m%d_%H%M%S") }}.jpg'
      - service: notify.mobile_app
        data:
          message: "Someone at the front door"
          data:
            image: '/media/doorbell_{{ now().strftime("%Y%m%d_%H%M%S") }}.jpg'

// Simplified motion detection implementation
bool detect_motion(camera_fb_t* current_frame, camera_fb_t* previous_frame) {
  if (!current_frame || !previous_frame) return false;
  if (current_frame->width != previous_frame->width || 
      current_frame->height != previous_frame->height) {
    return false;
  }
  
  uint32_t diff_pixels = 0;
  uint32_t threshold = (current_frame->width * current_frame->height) / 100; // 1% of pixels
  
  // Compare frames (simplified - actual implementation would be more sophisticated)
  for (size_t i = 0; i < current_frame->len; i += 10) {
    if (abs(current_frame->buf[i] - previous_frame->buf[i]) > 30) {
      diff_pixels++;
      if (diff_pixels > threshold) {
        return true;
      }
    }
  }
  
  return false;
}

void capture_timelapse() {
  static unsigned long last_capture = 0;
  unsigned long interval = 30000; // Capture every 30 seconds
  
  if (millis() - last_capture > interval) {
    camera_fb_t* fb = esp_camera_fb_get();
    if (fb) {
      // Save to SD card or send to server
      save_to_sd(fb, "/timelapse/image_" + String(millis()) + ".jpg");
      esp_camera_fb_return(fb);
    }
    last_capture = millis();
  }
}

#include <ArduinoOTA.h>

void setupOTA() {
  ArduinoOTA.setHostname("esp32-cam");
  ArduinoOTA.setPassword("your_ota_password");
  
  ArduinoOTA.onStart([]() {
    Serial.println("OTA update starting...");
  });
  
  ArduinoOTA.onEnd([]() {
    Serial.println("\nOTA update complete!");
  });
  
  ArduinoOTA.onProgress([](unsigned int progress, unsigned int total) {
    Serial.printf("Progress: %u%%\r", (progress * 100) / total);
  });
  
  ArduinoOTA.onError([](ota_error_t error) {
    Serial.printf("Error[%u]: ", error);
  });
  
  ArduinoOTA.begin();
}

// In loop(): ArduinoOTA.handle();