ESP32-S3 AI Camera Module - Home Assistant Setup that really works

# ======================
# ESP32-S3 Camera Configuration
# For DFRobot AI Camera Board
# ======================

# Core Device Configuration
esphome:
 name: dfrobot_cam                   # Device identifier (used in API/mDNS)
 friendly_name: "DFRobot AI Cam"     # Human-readable name
 platformio_options:
   build_flags: "-DBOARD_HAS_PSRAM"  # Essential for camera operations
   board_build.arduino.memory_type: qio_opi  # Memory optimization

# Hardware Configuration
esp32:
 board: esp32-s3-devkitc-1           # Specific board model
 framework:
   type: arduino                     # Using Arduino framework
   version: latest                   # Recommended for compatibility
 flash_size: 16MB                    # Required for OTA updates

# PSRAM Configuration (Critical for camera)
psram:
 mode: octal                         # Optimal performance mode
 speed: 80MHz                        # Recommended speed

# System Services
logger:                               # Enable system logging
 level: DEBUG                        # Helpful for troubleshooting

# Home Assistant Integration
api:
 encryption:
   key: "************************"   # Replace with your encryption key

# Over-The-Air Updates
ota:
 password: "****************"        # Secure OTA update password

# Network Configuration
wifi:
 ssid: !secret wifi_ssid             # From secrets.yaml
 password: !secret wifi_password     # From secrets.yaml
 
 # Fallback Access Point
 ap:
   ssid: "DFRobot-Cam-AP"            # AP name when WiFi fails
   password: "****************"      # AP password

captive_portal:                       # Web-based configuration

# ======================
# Camera Configuration
# ======================
esp32_camera:
 id: Camera                          # Internal reference
 name: Camera                        # Entity name in HA
 
 # Hardware Pin Mapping
 external_clock:
   pin: GPIO5
   frequency: 20MHz                  # Critical for camera sync
 i2c_pins:
   sda: GPIO8                        # I2C data
   scl: GPIO9                        # I2C clock
 data_pins: [GPIO16, GPIO18, GPIO21, GPIO17, GPIO14, GPIO7, GPIO6, GPIO4]  # Camera data bus
 vsync_pin: GPIO1                    # Vertical sync
 href_pin: GPIO2                     # Horizontal reference
 pixel_clock_pin: GPIO15             # Pixel clock
 
 # Image Settings
 max_framerate: 25 fps               # Smooth video streaming
 idle_framerate: 0.2 fps             # Reduced power when idle
 resolution: 640x480                 # VGA resolution
 jpeg_quality: 12                    # Balance quality/bandwidth (1-63)
 vertical_flip: True                 # Correct orientation
 contrast: 0                         # Range: -2 to 2
 brightness: 0                       # Range: -2 to 2
 saturation: 0                       # Range: -2 to 2
 aec_mode: AUTO                      # Auto exposure control

# Web Streaming Services
esp32_camera_web_server:
 - port: 8080                        # Main video stream
   mode: stream
 - port: 8081                        # Snapshot endpoint
   mode: snapshot

# ======================
# Peripheral Components
# ======================

# Time Synchronization
time:
 - platform: homeassistant           # Sync with HA server time
   id: homeassistant_time

# Output Controls
output:
 - platform: gpio
   pin: GPIO41                       # Speaker gain control
   id: speaker_gain
 - platform: gpio
   pin: GPIO40                       # Speaker mode
   id: speaker_mode
 - id: led_status                    # Status LED
   platform: gpio
   pin: GPIO3
 - id: ir_led                        # IR illumination
   platform: gpio
   pin: GPIO47

# Lighting Controls
light:
 - platform: binary
   name: "LED Status"                # Visible status indicator
   output: led_status
 - platform: binary
   name: "IR Night Vision"           # Infrared lighting
   output: ir_led
   restore_mode: RESTORE_DEFAULT_OFF # Default to off after restart

# System Controls
switch:      
 - platform: restart
   name: $friendly_name restart      # Remote reboot capability

# Audio Configuration
i2s_audio:
 i2s_lrclk_pin: GPIO46              # Audio clock
 i2s_bclk_pin: GPIO45               # Bit clock

# Microphone Setup
microphone:
 - platform: i2s_audio
   adc_type: external
   i2s_din_pin: GPIO39               # Data input
   pdm: true                         # Pulse-density modulation

# Speaker Configuration (MAX98357)
media_player:
 - platform: i2s_audio
   name: "Speaker"
   mode: mono                        # Single-channel audio
   i2s_dout_pin: GPIO42              # Audio output
   dac_type: external

# ======================
# Camera Adjustment Controls
# ======================
number:

  - platform: template

    name: "Camera Brightness"

    id: camera_brightness

    min_value: -2

    max_value: 2

    step: 0.1

    initial_value: 0

    restore_value: true

    optimistic: true

    on_value:

      then:

        - lambda: |-

            id(Camera).set_brightness(x);

            ESP_LOGD("camera", "Brightness set to: %.1f", x);

  - platform: template

    name: "Camera Contrast"

    id: camera_contrast

    min_value: -2

    max_value: 2

    step: 0.1

    initial_value: 0

    restore_value: true

    optimistic: true

    on_value:

      then:

        - lambda: |-

            id(Camera).set_contrast(x);

            ESP_LOGD("camera", "Contrast set to: %.1f", x);

  - platform: template

    name: "Camera Saturation"

    id: camera_saturation

    min_value: -2

    max_value: 2

    step: 0.1

    initial_value: 0

    restore_value: true

    optimistic: true

    on_value:

      then:

        - lambda: |-

            id(Camera).set_saturation(x);

            ESP_LOGD("camera", "Saturation set to: %.1f", x);

  - platform: template

    name: "Camera JPEG Quality"

    id: camera_jpeg_quality

    min_value: 1

    max_value: 63

    step: 1

    initial_value: 12

    restore_value: true

    optimistic: true

    on_value:

      then:

        - lambda: |-

            id(Camera).set_jpeg_quality(x);

            ESP_LOGD("camera", "JPEG Quality set to: %d", (int)x);