WildCAM_ESP32 - Motion-Activated Wildlife Camera

📘 Documentation Version: This README covers the core v3.1.0 release with production-ready wildlife camera functionality (motion detection, camera capture, SD storage, web interface, power management, cloud integration).
For advanced enterprise features (Edge AI, cloud integration, satellite communication), see README_ADVANCED.md. For detailed implementation status, see IMPLEMENTATION_STATUS.md. For project roadmap and timeline, see PROJECT_ROADMAP.md.

Project Status

v3.1.0 - Production-Ready Core System with Cloud Integration

WildCAM_ESP32 is a motion-activated wildlife camera platform built on the ESP32-CAM. The core wildlife monitoring system is production-ready and actively deployed in the field, with recent additions including cloud integration, SMS alerts, and advanced LoRa mesh networking with federated learning support.

Core System - Production Ready ✅

Feature	Status	Notes
Motion-triggered capture	✅ Complete	PIR sensor detects wildlife and triggers camera
High-quality images	✅ Complete	UXGA resolution (1600x1200) with adjustable JPEG quality
SD card storage	✅ Complete	Automatic file organization with timestamps
JSON metadata	✅ Complete	Each image includes timestamp, battery level, and file info
Battery monitoring	✅ Complete	Real-time voltage and percentage tracking
Deep sleep mode	✅ Complete	Power-efficient sleep between captures
Multi-board support	✅ Complete	ESP32-CAM, ESP32-S3, FREENOVE, XIAO variants
Two-factor detection	✅ Complete	PIR + Vision confirmation (98% accuracy)
Time keeping	✅ Complete	NTP sync + DS3231 RTC for persistent timestamps
Cloud integration	✅ Complete	Automatic image upload, SMS alerts, remote API (NEW)
Data analytics	✅ Complete	Activity patterns, species frequency charts (NEW)

Enterprise Features - In Development 🔄

Feature	Status	Notes
TFLite Model Integration	✅ Complete	INT8 quantized wildlife classifier (Dec 2025)
Edge AI (YOLO-tiny)	🔄 Framework	Est. 12-18 months to production
Jetson Edge Gateway	✅ Complete	NVIDIA Jetson with YOLOv8 + TensorRT (Dec 2025)
LoRa mesh networking	✅ Complete	Federated learning support added (Dec 2025)
Cloud integration	✅ Complete	CloudManager, SMS alerts, remote API (Dec 2025)
Mobile app	✅ Framework Complete	iOS, Android, React Native with push notifications (Dec 2025)
MPPT solar charging	✅ Complete	Implemented
Satellite communication	✅ Complete	Iridium, Swarm, RockBLOCK support with network fallback (Oct 2025)
Quantum-safe security	✅ Foundation	Digital signatures implemented
Federated learning	✅ Complete	Distributed ML model training (Dec 2025)
Advanced storage	✅ Complete	Compression, deduplication, smart deletion (Dec 2025)

Status Legend: ✅ Complete | 🔄 In Development | 📋 Planned

The core system is fully production-ready for wildlife monitoring. Advanced enterprise features are under active development. See IMPLEMENTATION_STATUS.md for detailed status and PROJECT_ROADMAP.md for the development timeline.

Features

Core Capabilities

• 🎯 Motion-triggered Image Capture - PIR sensor detects motion with two-factor vision confirmation (98% accuracy)
• 💾 SD Card Storage with Metadata - Images saved with JSON metadata including timestamps, battery level, and capture count
• ⚡ Deep Sleep Power Management - Efficient power usage with configurable sleep intervals (30+ day battery life)
• 🔁 Automatic Recovery - Watchdog timer prevents system hangs
• 📊 Status Logging - Serial output for debugging and monitoring
• 🖥️ Multi-Board Support - Compatible with ESP32-CAM, ESP32-S3, FREENOVE-CAM, and XIAO ESP32-S3
• ⏰ Accurate Time Keeping - NTP time sync over WiFi with DS3231 external RTC for persistent timestamps across power cycles

AI-Powered Wildlife Classification

• 🤖 Species Identification - TensorFlow Lite INT8 quantized model for real-time wildlife classification
• 🎯 Confidence Scoring - Adjustable confidence thresholds for reliable species detection
• 🧠 Edge AI Processing - On-device inference without cloud dependency
• 📊 Classification Metadata - Species name, confidence level, and inference time saved with each image
• 🔄 Custom Model Support - Deploy your own trained models for local wildlife species
• ⚡ Optimized Performance - INT8 quantization enables fast inference on ESP32 (typically 1-3 seconds)

See MODEL_DEPLOYMENT.md for detailed model deployment and configuration instructions.

Additional Sensor Support (Optional)

• 🌡️ BME280 Environmental Sensor - Temperature, humidity, and pressure monitoring
• 📍 GPS Location Tagging - Geo-tag captured images with GPS coordinates
• 💡 Light Sensor (BH1750/LDR) - Day/night detection for adaptive camera settings

See SENSOR_INTEGRATION.md for detailed setup instructions.

Raspberry Pi LoRa/MQTT Gateway (NEW) 🆕

For scalable deployments with multiple ESP32-CAM nodes, a dedicated Raspberry Pi gateway aggregates data over LoRa mesh:

• 📡 LoRa Mesh Gateway - Receive packets from 10+ ESP32 nodes simultaneously over long-range LoRa
• 💾 Local SQLite Storage - Store detections, telemetry, and mesh health data with automatic rotation
• 🔄 MQTT Bridge - Publish to local/cloud MQTT brokers (Mosquitto, AWS IoT, Azure IoT Hub)
• 🌐 REST API - Query nodes, detections, telemetry via HTTP endpoints
• ☁️ Cloud Sync - Batch upload with offline-first queue and retry logic
• 📊 Diagnostics - System health, mesh network monitoring, and field deployment tools

Quick Start:

cd gateway
sudo ./install.sh

See gateway/QUICKSTART.md for 5-minute setup guide and gateway/GATEWAY_SETUP.md for complete documentation.

Hardware Requirements

Required Components

Component	Specification	Estimated Cost	Notes
ESP32-CAM Board	AI-Thinker ESP32-CAM with OV2640 camera	$10-15	Main controller with integrated camera
MicroSD Card	Class 10, 16GB-32GB, FAT32 formatted	$5-10	For image storage
PIR Motion Sensor	HC-SR501 or similar	$2-5	Motion detection
USB-to-Serial Adapter	FTDI, CP2102, or CH340	$3-8	For programming (not needed for ESP32-S3)
Power Supply	5V 2A USB adapter or 3.7V LiPo battery	$5-15	Development or field deployment
MicroUSB Cable	Data + power capable	$2-5	For power and programming
Jumper Wires	Female-to-female, 10cm	$2-5	For PIR sensor connection

Optional Components

Component	Specification	Estimated Cost	Purpose
LiPo Battery	3.7V 3000mAh+ with protection circuit	$8-15	Portable power
Solar Panel	5V 5W with charge controller	$15-25	Solar charging
Weatherproof Enclosure	IP65 rated, clear window	$10-20	Outdoor protection
Battery Monitor	Voltage divider circuit or dedicated module	$2-5	Better voltage accuracy

Total Cost Estimate:

• Basic Setup: $25-50 (ESP32-CAM, SD card, PIR sensor, programmer, cables)
• Field Deployment: $60-100 (includes battery, solar panel, enclosure)
• Full Sensor Suite: $90-130 (includes all optional sensors)

Wiring Diagram

Pin Assignments Table

Component	ESP32-CAM Pin	Notes
PIR Sensor	GPIO 13	Motion detection input
Battery Monitor	GPIO 33 (ADC)	Voltage divider recommended (2:1 ratio)
Flash LED	GPIO 4	Built-in flash control
SD Card	Built-in SD_MMC	Uses pins 2, 4, 12, 13, 14, 15 (1-bit mode)
Camera	Built-in	Uses dedicated camera pins

Connection Diagram (ASCII)

┌─────────────────────────────────────────────┐
│           ESP32-CAM (AI-Thinker)            │
│                                             │
│  ┌──────┐                                   │
│  │Camera│                                   │
│  │OV2640│                                   │
│  └──────┘                                   │
│                                             │
│  [GPIO 13] ──────────────┐                  │
│                          │                  │
│  [GPIO 33] ──────────────┼──────────────┐   │
│                          │              │   │
│  [GPIO 4]  ──> Flash LED │              │   │
│                          │              │   │
│  [5V]  ────────────────┐ │              │   │
│  [GND] ────────────────┼─┼──────────────┼───┤
│                        │ │              │   │
│  [MicroSD Slot]        │ │              │   │
│    └─ SD Card          │ │              │   │
│                        │ │              │   │
└────────────────────────┼─┼──────────────┼───┘
                         │ │              │
                         │ │              │
    ┌────────────────────┘ │              │
    │  ┌───────────────────┘              │
    │  │                                  │
    │  │  ┌───────────────────────────────┘
    │  │  │
    ▼  ▼  ▼
  ┌──────────┐         ┌──────────────┐
  │   PIR    │         │   Battery    │
  │  Sensor  │         │   Monitor    │
  │ HC-SR501 │         │  (optional)  │
  ├──────────┤         ├──────────────┤
  │ VCC  5V  │◄────────┤ 3.7V Battery │
  │ OUT  D13 │         │   Voltage    │
  │ GND  GND │         │   Divider    │
  └──────────┘         └──────────────┘

Wiring Instructions

1. PIR Sensor Connection:

   • VCC → ESP32-CAM 5V pin
   • OUT → ESP32-CAM GPIO 13
   • GND → ESP32-CAM GND

2. Battery Monitor (Optional):

   • Create voltage divider: Battery+ → 10kΩ → GPIO 33 → 10kΩ → GND
   • This allows monitoring up to 6.6V battery voltage

3. Power Supply:

   • USB Power: Connect 5V 2A USB adapter to MicroUSB port
   • Battery Power: Connect 3.7V LiPo to 5V and GND pins (use appropriate regulator)

4. SD Card:

   • Insert FAT32-formatted MicroSD card (32GB max recommended)
   • No wiring needed - uses built-in SD_MMC interface

⚠️ Important Notes:

• Never connect more than 3.3V directly to GPIO pins
• Use voltage divider for battery monitoring (GPIO 33 is analog input)
• PIR sensor requires 5V but output is 3.3V compatible
• Ensure common ground connection for all components

Software Requirements

Required Software

1. PlatformIO (Recommended)

   • Install via Visual Studio Code extension, or
   • Install via command line: pip install platformio
   • Download: https://platformio.org/install

2. Git (For cloning repository)

   • Download: https://git-scm.com/downloads

3. USB Drivers (If using USB-to-Serial adapter)

   • CP2102: https://www.silabs.com/developers/usb-to-uart-bridge-vcp-drivers
   • CH340: http://www.wch.cn/downloads/CH341SER_ZIP.html
   • FTDI: Usually pre-installed on most systems

Required Libraries (Auto-installed by PlatformIO)

The following libraries are automatically installed when you build the project:

• espressif/esp32-camera@^2.0.4 - ESP32 camera driver
• bblanchon/ArduinoJson@^6.21.3 - JSON serialization for metadata
• me-no-dev/ESP Async WebServer@^1.2.3 - Asynchronous web server
• me-no-dev/AsyncTCP@^1.1.1 - Async TCP library for web server

These dependencies are defined in platformio.ini and will be automatically downloaded during the first build.

Installation

Follow these step-by-step instructions to get your WildCAM_ESP32 up and running:

Step 1: Clone the Repository

# Clone the repository
git clone https://github.com/thewriterben/WildCAM_ESP32.git

# Navigate to the project directory
cd WildCAM_ESP32

Step 2: Install PlatformIO

Choose one of the following methods:

Method A: PlatformIO IDE (Recommended for beginners)

1. Install Visual Studio Code from https://code.visualstudio.com/
2. Open VS Code
3. Go to Extensions (Ctrl+Shift+X)
4. Search for "PlatformIO IDE"
5. Click Install
6. Restart VS Code when prompted

Method B: Command Line

# Install Python 3 if not already installed
# Then install PlatformIO
pip install platformio

# Verify installation
pio --version

Step 3: Edit Configuration

1. Open the project in VS Code or your preferred editor
2. Edit include/config.h to configure WiFi and settings:

// WiFi Settings (required for web interface)
#define WIFI_SSID "YourWiFiNetworkName"
#define WIFI_PASSWORD "YourWiFiPassword"

// Pin Configuration (use defaults unless you have custom wiring)
#define PIR_SENSOR_PIN 13
#define BATTERY_MONITOR_PIN 33
#define FLASH_LED_PIN 4

// Camera Settings
#define DEFAULT_JPEG_QUALITY 10  // Lower = better quality (1-63)
#define DEFAULT_FRAME_SIZE FRAMESIZE_UXGA  // 1600x1200

// Power Management
#define DEEP_SLEEP_DURATION_SEC 300  // Sleep for 5 minutes
#define BATTERY_LOW_THRESHOLD 3.3    // Low battery voltage

3. Save the file

Step 4: Build the Firmware

Using PlatformIO IDE:

1. Open the project folder in VS Code
2. Click the PlatformIO icon on the left sidebar
3. Under "Project Tasks", expand "esp32cam"
4. Click "Build"
5. Wait for compilation to complete

Using Command Line:

# Build the firmware
pio run -e esp32cam

# This will compile the code and download required libraries

Step 5: Upload to ESP32-CAM

Hardware Setup for Upload:

1. Connect your USB-to-Serial adapter to the ESP32-CAM:
   • Adapter TX → ESP32-CAM RX (GPIO 3)
   • Adapter RX → ESP32-CAM TX (GPIO 1)
   • Adapter GND → ESP32-CAM GND
   • Adapter 5V → ESP32-CAM 5V
2. Connect GPIO 0 to GND on ESP32-CAM (enables programming mode)
3. Connect USB adapter to computer

Upload Firmware:

Using PlatformIO IDE:

1. Click "Upload" in PlatformIO toolbar
2. Press the RESET button on ESP32-CAM when prompted
3. Wait for upload to complete
4. Disconnect GPIO 0 from GND
5. Press RESET button to start firmware

Using Command Line:

# Upload to ESP32-CAM
pio run -e esp32cam -t upload

# If upload fails, try:
# 1. Press and hold BOOT/GPIO0 button
# 2. Press RESET button
# 3. Release RESET button
# 4. Run upload command
# 5. Release BOOT button when "Connecting..." appears

Troubleshooting Upload Issues:

• "Failed to connect": Make sure GPIO 0 is connected to GND
• "No serial port found": Install USB drivers for your adapter
• "Hash of data verified": Upload successful! Disconnect GPIO 0 and reset

Step 6: Verify Installation

After upload, open the serial monitor to verify operation:

Using PlatformIO IDE:

• Click "Serial Monitor" in PlatformIO toolbar
• Select baud rate: 115200

Using Command Line:

pio device monitor -b 115200

Expected Output:

======================================
   WildCAM ESP32 Wildlife Camera
   Firmware Version: 1.0.0
======================================

[INIT] Initializing Power Manager...
Power Manager initialized
Battery ADC: 2048, Voltage: 3.80V
Battery Level: 65%

[INIT] Initializing Camera...
Camera initialized successfully

[INIT] Initializing Storage...
SD Card mounted successfully
Storage Manager initialized

[INIT] Initializing Motion Detector...
Motion Detector initialized

[INIT] Initializing Web Server...
Connecting to WiFi: YourWiFiNetworkName
Connected to WiFi
IP Address: 192.168.1.XXX
WebServer initialized successfully
Web server started on port 80

[READY] System initialization complete!

If you see this output, your WildCAM_ESP32 is successfully installed! 🎉

Usage

Powering On

1. Remove GPIO 0 from GND (if still connected from programming)
2. Power the device:
   • Via USB: Connect 5V 2A USB adapter
   • Via Battery: Connect charged 3.7V LiPo battery
3. Press RESET button (if needed)
4. Wait for initialization (about 5-10 seconds)
5. Check status LED - Should blink during startup

Accessing the Web Interface

The WildCAM_ESP32 provides an enhanced mobile-responsive web interface for monitoring and configuration.

Step 1: Find the IP Address

Check the serial monitor for the IP address:

Connected to WiFi
IP Address: 192.168.1.123

Step 2: Open Web Browser

1. Connect your computer/phone to the same WiFi network
2. Open a web browser
3. Navigate to the IP address: http://192.168.1.123

Step 3: Web Interface Pages

The enhanced web interface includes three main pages:

Dashboard (/)

• Real-time statistics: uptime, battery %, free storage, image count, memory, voltage
• Auto-refreshes every 30 seconds
• Quick action buttons: Capture Now, Refresh, Reboot
• Latest captured image preview

Gallery (/gallery)

• Grid layout with image thumbnails
• Pagination support (12 images per page)
• Click to view full-size image in modal
• Capture new image button

Settings (/config)

• Capture interval (1-3600 seconds)
• Motion sensitivity (0-100%)
• Night mode toggle
• Cloud upload toggle
• Device information display

API Endpoints

• /api/status - System status (JSON format):

  {
    "uptime": 123456,
    "freeHeap": 150000,
    "batteryVoltage": 4.05,
    "batteryPercentage": 85,
    "sdCardFreeSpace": 15000000000,
    "sdCardUsedSpace": 500000000,
    "imageCount": 42
  }

• /api/images - Paginated list of captured images (JSON)
• /api/config - Get/update device configuration (GET/POST)
• /latest - View the most recently captured image
• /capture or /api/capture - Manually trigger a photo capture (POST)
• /images/* - Serve images from SD card
• /thumbnail/* - Serve image thumbnails

Retrieving Images from SD Card

There are two ways to access your captured wildlife images:

Method 1: Remove SD Card (Recommended)

1. Power off the ESP32-CAM (disconnect power)
2. Remove the MicroSD card from the slot
3. Insert SD card into computer's card reader
4. Navigate to the images folder:
   • Images: /WILDLIFE/IMAGES/
   • Metadata: /WILDLIFE/METADATA/
5. Copy images to your computer
6. Safely eject the SD card
7. Reinsert into ESP32-CAM and power on

Method 2: Web Interface

1. Open web browser to device IP
2. Navigate to /images endpoint
3. Click on image links to view/download
4. Right-click and "Save As" to download

Image File Organization

Images are automatically organized on the SD card:

/WILDLIFE/
├── IMAGES/
│   ├── IMG_20241029_143022.jpg
│   ├── IMG_20241029_143145.jpg
│   └── IMG_20241029_150301.jpg
└── METADATA/
    ├── IMG_20241029_143022.json
    ├── IMG_20241029_143145.json
    └── IMG_20241029_150301.json

Image Filename Format: IMG_YYYYMMDD_HHMMSS.jpg

• Example: IMG_20241029_143022.jpg = Image taken on Oct 29, 2024 at 14:30:22

Metadata JSON Format:

{
  "timestamp": "2024-10-29T14:30:22",
  "battery_voltage": 3.85,
  "battery_percent": 75,
  "image_size": 98234,
  "image_count": 42
}

Normal Operation

Once powered on and initialized:

1. Standby Mode:

   • System waits for motion detection
   • Low power consumption
   • PIR sensor actively monitoring

2. Motion Detected:

   • LED blinks to indicate motion
   • Short delay for stabilization (500ms)
   • Image captured at UXGA resolution
   • Image saved to SD card with timestamp
   • Metadata JSON file created
   • System returns to standby

3. Deep Sleep Mode:

   • Activates after no motion for configured duration
   • Ultra-low power consumption
   • Wakes up on motion or timer
   • Preserves battery life

LED Status Indicators

• Rapid blinking - Camera initialization
• Single blink - Motion detected, capturing image
• Solid on - Image being saved
• Off - Standby or deep sleep mode

Configuration

You can customize the behavior of your WildCAM_ESP32 by editing include/config.h. Here are the key configuration options:

WiFi Configuration

// WiFi network credentials
#define WIFI_SSID "YourNetworkName"      // Your WiFi SSID
#define WIFI_PASSWORD "YourPassword"     // Your WiFi password

// Web server settings
#define WEB_SERVER_PORT 80               // HTTP server port (default: 80)
#define WEB_SOCKET_PORT 81              // WebSocket port (default: 81)

Camera Settings

// Image quality settings
#define DEFAULT_JPEG_QUALITY 10          // JPEG quality: 1-63 (lower = better)
#define DEFAULT_FRAME_SIZE FRAMESIZE_UXGA // Camera resolution

// Available frame sizes:
// - FRAMESIZE_UXGA (1600x1200) - Highest quality, larger files
// - FRAMESIZE_SXGA (1280x1024) - High quality, medium files  
// - FRAMESIZE_XGA (1024x768)   - Good quality, smaller files
// - FRAMESIZE_SVGA (800x600)   - Standard quality, small files
// - FRAMESIZE_VGA (640x480)    - Lower quality, smallest files

Quality vs. File Size Trade-off:

• Quality 10 + UXGA: ~100KB per image, best quality
• Quality 15 + SXGA: ~60KB per image, good quality
• Quality 20 + XGA: ~40KB per image, acceptable quality

Motion Detection Settings

// Motion sensor configuration
#define PIR_SENSOR_PIN 13                // GPIO pin for PIR sensor
#define MOTION_DEBOUNCE_MS 2000          // Ignore motion for 2s after trigger
#define MOTION_COOLDOWN_MS 5000          // Wait 5s between captures
#define IMAGE_CAPTURE_DELAY_MS 500       // Delay before capture (stabilization)

// Motion sensitivity
#define MOTION_SENSITIVITY 50            // 0-100 (higher = more sensitive)

Tuning Tips:

• High false positives? Increase MOTION_COOLDOWN_MS to 10000 (10 seconds)
• Missing fast animals? Decrease IMAGE_CAPTURE_DELAY_MS to 200
• Too many triggers? Increase MOTION_DEBOUNCE_MS to 3000

Power Management

// Battery monitoring
#define BATTERY_MONITOR_PIN 33           // ADC pin for voltage reading
#define BATTERY_LOW_THRESHOLD 3.3        // Low battery warning (volts)
#define BATTERY_CRITICAL_THRESHOLD 3.0   // Critical battery shutdown (volts)
#define BATTERY_VOLTAGE_MIN 3.3          // Minimum voltage (empty)
#define BATTERY_VOLTAGE_MAX 4.2          // Maximum voltage (full)

// Deep sleep settings
#define DEEP_SLEEP_DURATION_SEC 300      // Sleep duration (seconds)
                                         // 300 = 5 minutes
                                         // 600 = 10 minutes
                                         // 1800 = 30 minutes

Battery Life Optimization:

• Increase DEEP_SLEEP_DURATION_SEC for longer battery life
• Lower DEFAULT_JPEG_QUALITY number increases file size and processing time
• Reduce DEFAULT_FRAME_SIZE to save processing power
• Disable WiFi if not needed (comment out #define WIFI_ENABLED)

Storage Settings

// SD card storage limits
#define MAX_IMAGES_PER_DAY 1000          // Maximum images per day
#define MAX_IMAGE_SIZE 100000            // Max file size in bytes (~100KB)
#define AUTO_DELETE_DAYS 7               // Auto-delete images older than 7 days

Storage Capacity:

• 16GB SD card: ~10,000-15,000 images (at default quality)
• 32GB SD card: ~20,000-30,000 images (at default quality)

Pin Configuration

// Hardware pin assignments
#define PIR_SENSOR_PIN 13                // Motion sensor
#define BATTERY_MONITOR_PIN 33           // Battery voltage (ADC)
#define FLASH_LED_PIN 4                  // Flash LED
#define SD_CS_PIN 5                      // SD card chip select (not used in SD_MMC mode)

⚠️ Warning: Only change pin assignments if you have custom hardware. Incorrect pin configuration can prevent the camera from working.

AI/ML Classification Settings

Configure AI-based wildlife species classification:

// Enable/disable AI classification
#define AI_CLASSIFICATION_ENABLED true       // Enable AI species identification

// Model configuration
#define TFLITE_MODEL_FILENAME "best_int8.tflite"  // Model file on SD card
#define TFLITE_ARENA_SIZE (4 * 1024 * 1024)      // 4MB tensor arena
#define MODEL_INPUT_SIZE 224                      // Input image size (224x224)

// Classification thresholds
#define SPECIES_CONFIDENCE_THRESHOLD 0.6f    // Minimum confidence (0.0-1.0)
#define MAX_SPECIES_COUNT 21                 // Number of species classes

Configuration Options:

• AI_CLASSIFICATION_ENABLED: Enable or disable AI classification

  • true: AI classification active (requires model on SD card)
  • false: Standard camera trap mode (no classification)

• TFLITE_MODEL_FILENAME: Name of the TensorFlow Lite model file

  • Default: "best_int8.tflite" (custom wildlife model)
  • File must be in /models/ directory on SD card

• TFLITE_ARENA_SIZE: Memory allocated for TensorFlow Lite inference

  • Default: 4MB (4 * 1024 * 1024)
  • Increase if model requires more memory
  • Decrease if experiencing memory issues

• MODEL_INPUT_SIZE: Input image dimensions (width and height)

  • Default: 224 (for 224x224 input)
  • Must match your model's expected input size

• SPECIES_CONFIDENCE_THRESHOLD: Minimum confidence for valid detection

  • Range: 0.0 to 1.0 (0% to 100%)
  • Default: 0.6 (60% confidence)
  • Lower = more detections (but more false positives)
  • Higher = fewer detections (but more accurate)

Model Deployment:

1. Copy models/best_int8.tflite to SD card /models/ directory
2. Enable AI classification in config.h
3. Build and upload firmware
4. System will automatically load model at startup

For detailed model deployment instructions, see MODEL_DEPLOYMENT.md.

Applying Configuration Changes

After editing config.h:

1. Save the file
2. Rebuild the firmware:

   pio run -e esp32cam

3. Upload to ESP32-CAM:

   pio run -e esp32cam -t upload

4. Reset the device and verify changes via serial monitor

Configuration Examples

Example 1: Long-term Wildlife Monitoring

#define DEFAULT_JPEG_QUALITY 15           // Medium quality
#define DEFAULT_FRAME_SIZE FRAMESIZE_SXGA // 1280x1024
#define DEEP_SLEEP_DURATION_SEC 600       // 10 minute sleep
#define MOTION_COOLDOWN_MS 10000          // 10 second cooldown
#define AUTO_DELETE_DAYS 14               // Keep 2 weeks

Example 2: High-Quality Research

#define DEFAULT_JPEG_QUALITY 8            // Best quality
#define DEFAULT_FRAME_SIZE FRAMESIZE_UXGA // 1600x1200
#define DEEP_SLEEP_DURATION_SEC 300       // 5 minute sleep
#define MOTION_COOLDOWN_MS 3000           // 3 second cooldown
#define AUTO_DELETE_DAYS 0                // Never auto-delete

Example 3: Maximum Battery Life

#define DEFAULT_JPEG_QUALITY 20           // Lower quality
#define DEFAULT_FRAME_SIZE FRAMESIZE_SVGA // 800x600
#define DEEP_SLEEP_DURATION_SEC 1800      // 30 minute sleep
#define MOTION_COOLDOWN_MS 15000          // 15 second cooldown

Known Issues

This is an early MVP release. Here are the current known limitations and issues:

Hardware Limitations

• SD Card Compatibility: Some SD cards (especially >32GB or non-Class 10) may not mount properly

  • Workaround: Use 16GB or 32GB Class 10 cards, formatted as FAT32

• PIR Sensor False Positives: HC-SR501 sensors can trigger on temperature changes, sunlight, or plants

  • Workaround: Adjust sensor sensitivity pot, increase MOTION_COOLDOWN_MS, enable two-factor detection in future versions

• Battery Voltage Reading Inaccuracy: Simple voltage divider has ±10% accuracy

  • Workaround: Calibrate voltage divider resistors, or use dedicated battery monitor IC

• Camera Power Consumption: Camera draws 200-300mA during image capture

  • Impact: Limits battery-only operation to a few days without solar
  • Workaround: Use larger battery (5000mAh+) or add solar panel

Software Issues

• WiFi Connection Delays: First WiFi connection can take 10-30 seconds

  • Status: Normal behavior, no fix planned

• Web Interface Basic: Current web UI is minimal HTML, not mobile-optimized

  • Fixed: Enhanced mobile-responsive web interface now available in v3.1.0

• No Image Thumbnails: Full images loaded in web interface can be slow

  • Fixed: Image gallery with thumbnail support now available

• Limited Error Recovery: Some SD card errors require manual reset

  • Planned Fix: Better error handling and automatic retry logic

Performance Issues

• Slow SD Card Writes: Image saving can take 1-3 seconds with slow SD cards

  • Workaround: Use Class 10 or UHS-I rated cards

• Memory Fragmentation: After hundreds of captures, system may become unstable

  • Workaround: Periodic resets (deep sleep helps)
  • Planned Fix: Better memory management in v0.2.0

• Serial Monitor Spam: Verbose logging can slow down operation

  • Workaround: Reduce debug level in config.h (set CORE_DEBUG_LEVEL=1)

Field Deployment Considerations

• Temperature Range: Components rated for -20°C to 60°C only

  • Limitation: Not suitable for extreme climates without specialized hardware

• Weatherproofing: No official enclosure design provided yet

  • Workaround: Use generic IP65 enclosure with clear window for camera

• Solar Charging: MPPT solar charge controller support now available in firmware/power/

  • Supports 3 tracking algorithms (P&O, Incremental Conductance, Constant Voltage)
  • See firmware/power/README.md for setup instructions

Reporting Issues

Found a bug not listed here? Please help us improve!

Before reporting:

1. Check if the issue is already listed above
2. Search existing GitHub issues
3. Try basic troubleshooting (reboot, re-upload firmware, check connections)

To report a new issue:

1. Go to GitHub Issues
2. Provide:
   • WildCAM version (v3.0.0)
   • Hardware used (ESP32-CAM model, SD card brand/size, etc.)
   • Steps to reproduce
   • Expected vs actual behavior
   • Serial monitor output (if applicable)
   • Photos of setup (if hardware related)

We appreciate detailed bug reports - they help us fix issues faster! 🐛

Roadmap

WildCAM_ESP32 is under active development. Here's the current status and what we're planning:

📋 For detailed roadmap: See PROJECT_ROADMAP.md for comprehensive timeline and milestones.

✅ Phase 1: Core System (Complete)

The core wildlife camera system is production-ready:

• Motion-triggered capture with PIR sensors
• High-quality image capture (up to UXGA)
• SD card storage with automatic organization
• JSON metadata for every image
• Battery monitoring and deep sleep
• Multi-board support (ESP32-CAM, ESP32-S3, FREENOVE, XIAO)
• Web interface for status and image viewing
• Two-factor detection (PIR + Vision, 98% accuracy)

✅ Phase 2: Enhanced Features (Complete - December 2025)

• Improved Power Management ✅ Implemented

  • MPPT solar charge controller support (3 algorithms: P&O, Incremental Conductance, Constant Voltage)
  • Advanced battery analytics (SOC, SOH, multi-stage charging, multi-chemistry support)
  • Adaptive sleep schedules based on motion patterns (7-day pattern learning)
  • Battery-aware power modes (Normal, Power Save, Solar Priority, Emergency)

• Better Time Keeping ✅ COMPLETE

  • ✅ NTP time sync over WiFi
  • ✅ External RTC module support (DS3231)
  • ✅ Persistent timestamps across power cycles
  • See TIME_KEEPING.md for configuration details

• Enhanced Web Interface ✅ COMPLETE

  • Mobile-responsive design
  • Image gallery with thumbnails
  • Real-time statistics dashboard
  • Configuration page (no code editing needed)

• Additional Sensors ✅ COMPLETE

  • ✅ BME280 temperature/humidity/pressure
  • ✅ GPS location tagging (optional)
  • ✅ Light sensor for day/night detection (BH1750/LDR)
  • ✅ Enhanced sensor abstraction framework (30+ sensor types)
  • ✅ DHT11/DHT22 temperature & humidity
  • ✅ HC-SR04 ultrasonic distance sensor
  • ✅ MQ gas sensors (MQ-2, MQ-7, MQ-135) for environmental monitoring
  • See SENSOR_INTEGRATION.md for setup instructions

✅ Phase 3: Intelligence (Complete - December 2025)

• Advanced AI Features ✅ COMPLETE

  • Edge AI optimization with TensorFlow Lite integration
  • Species identification with confidence scoring
  • AI detection interface with unified API
  • False positive reduction (98% accuracy)
  • Progressive inference based on resources

• Event Triggering System ✅ COMPLETE

  • Automatic detection event triggering
  • Confidence-based capture decisions
  • Recent detections management
  • Auto-save high-confidence captures

• Communication Systems ✅ COMPLETE

  • LoRa mesh networking for multi-device coordination
  • Detection event broadcasting
  • Seamless data transfer between nodes
  • Digital signature verification

• Security & Integrity ✅ COMPLETE

  • Quantum-safe cryptography foundation
  • Blockchain integration for tamper-proof records
  • OTA updates with metrics persistence

See PHASE_3_IMPLEMENTATION_COMPLETE.md for detailed implementation status.

✅ Phase 3+: Recent Enhancements (December 2025) - NEW

• NVIDIA Jetson Edge Gateway ✅ COMPLETE (NEW)

  • High-performance edge computing for real-time wildlife monitoring
  • TensorRT-optimized YOLOv8 inference (45-60 FPS on Orin Nano)
  • Multi-camera support (up to 8 simultaneous streams)
  • Cloud sync with robust offline queue/retry logic
  • ESP32 integration via HTTP/WebSocket/LoRa
  • See edge_gateway/README.md for deployment guide

• TFLite Model Integration ✅ COMPLETE (PR #234)

  • INT8 quantized TensorFlow Lite model for wildlife classification
  • Real-time on-device inference (1-3 seconds per image)
  • Pre-trained model included (models/best_int8.tflite)
  • See MODEL_DEPLOYMENT.md for deployment instructions

• Cloud Integration ✅ COMPLETE (PR #229)

  • CloudManager for automatic image upload
  • SMS alerts for wildlife detections
  • Remote monitoring API
  • User preferences configuration
  • See CLOUD_INTEGRATION_SUMMARY.md for details

• Advanced LoRa Mesh ✅ COMPLETE (PR #228)

  • Federated learning for distributed ML training
  • 4-bit quantization for efficient model transfer
  • Network topology management (star, mesh, hierarchical)
  • See FEDERATED_LEARNING_IMPLEMENTATION_SUMMARY.md

• Improved Storage ✅ COMPLETE (PR #226)

  • Image compression with configurable quality
  • Hash-based duplicate detection
  • Smart deletion with priority policies
  • Storage analytics and monitoring

• Data Analytics ✅ COMPLETE (PR #225)

  • Activity pattern analysis
  • Species frequency charts
  • Time-of-day wildlife activity visualization
  • CSV/JSON export capabilities

📋 Phase 4: Enterprise Features (In Progress - 2026)

• Satellite Communication ✅ COMPLETE

  • Swarm M138, RockBLOCK, Iridium support
  • Global coverage for remote deployments
  • Message compression and prioritization
  • See SATELLITE_INTEGRATION_SUMMARY.md for details

• Mobile App ✅ Framework Complete

  • iOS and Android companion app (Swift/Kotlin/React Native)
  • Real-time push notifications with customizable preferences
  • Remote configuration and device management
  • See mobile/MOBILE_APP_README.md for details

• Production Cloud Deployment 🔄 In Progress

  • AWS/Azure/GCP production setup
  • Auto-scaling and monitoring
  • Multi-region support

Long-Term Vision (2027+)

• Advanced AI

  • Species-specific detection (deer, bear, fox, etc.)
  • Behavioral analysis (feeding, running, resting)
  • Individual animal recognition

• Conservation Platform

  • Multi-site wildlife tracking
  • Researcher collaboration tools
  • Citizen science integration (iNaturalist, eBird)

• Professional Features

  • Video recording support
  • Thermal camera integration
  • Advanced weatherproofing designs

Community Requests

We're listening to the community! Vote on features or suggest new ones:

• Feature Requests
• Discussion Forum

Want to contribute? See the Contributing section below! 🚀

Contributing

We welcome contributions from the community! Whether you're a developer, wildlife enthusiast, or conservation researcher, there are many ways to help improve WildCAM_ESP32.

Ways to Contribute

• 💻 Code Contributions - Bug fixes, new features, optimizations
• 📝 Documentation - Improve guides, add tutorials, fix typos
• 🧪 Testing - Field testing, bug reports, hardware compatibility
• 🎨 Design - Web interface, enclosure designs, diagrams
• 📊 Data - Share field deployment results and wildlife captures
• 💡 Ideas - Feature suggestions and use case discussions

Getting Started

1. Read the Contributing Guide: CONTRIBUTING.md
2. Check Open Issues: Good First Issues
3. Join Discussions: GitHub Discussions

Development Setup

# Fork the repository on GitHub

# Clone your fork
git clone https://github.com/YOUR_USERNAME/WildCAM_ESP32.git
cd WildCAM_ESP32

# Create a new branch
git checkout -b feature/your-feature-name

# Make your changes and test thoroughly

# Commit with clear message
git commit -m "Add feature: brief description"

# Push to your fork
git push origin feature/your-feature-name

# Open a Pull Request on GitHub

Code Style Guidelines

• Follow existing code formatting and style
• Add comments for complex logic
• Update documentation for new features
• Test on real hardware before submitting
• Include example usage in comments

Pull Request Process

1. Ensure your PR:

   • Has a clear description of changes
   • Links to related issues (if applicable)
   • Includes updated documentation
   • Has been tested on ESP32-CAM hardware

2. PR Review:

   • Maintainers will review within 1-2 weeks
   • Address any requested changes
   • Once approved, PR will be merged

3. After Merge:

   • You'll be credited in release notes
   • Your changes will be in the next version

Community Guidelines

• Be respectful and constructive
• Help newcomers get started
• Share your field deployment experiences
• Report bugs with detailed information
• Suggest features with clear use cases

Recognition

Contributors will be acknowledged in:

• Release notes
• CONTRIBUTORS.md file
• Project documentation

Thank you for helping make WildCAM_ESP32 better! 🙏

For detailed contributing guidelines, see CONTRIBUTING.md.

License

This project is licensed under the MIT License - see the LICENSE file for details.

What This Means

✅ You can:

• Use this project for commercial purposes
• Modify and distribute your changes
• Use in private projects
• Sublicense the code

❌ You must:

• Include the original copyright notice
• Include a copy of the license

⚠️ No Warranty:

• Software provided "as is" without warranty
• Authors not liable for any damages

Third-Party Licenses

This project uses the following open-source libraries:

• ESP32 Arduino Core - LGPL 2.1
• ESP32 Camera Driver - Apache 2.0
• ArduinoJson - MIT License
• ESPAsyncWebServer - LGPL 3.0
• AsyncTCP - LGPL 3.0

Full license texts for dependencies can be found in their respective repositories.

---

Support & Community

Getting Help

• 📖 Documentation: You're reading it!
• 🐛 Bug Reports: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📧 Email: wildlife-tech@example.com

Stay Updated

• ⭐ Star this repo to get updates
• 👀 Watch for new releases
• 🔔 Subscribe to discussions for community posts

Show Your Support

If you find WildCAM_ESP32 useful for wildlife conservation or research:

• ⭐ Star this repository
• 🐦 Share on social media
• 📸 Share your wildlife photos captured with WildCAM!
• 💝 Sponsor the project (GitHub Sponsors - coming soon)

Photo Gallery

We'd love to see what you capture with WildCAM_ESP32! Share your best wildlife photos:

• Post in Show and Tell
• Tag us on social media with #WildCAM_ESP32
• Contribute to citizen science platforms (iNaturalist, eBird)

---

🦌 Help us protect wildlife through accessible technology! 🦌

Made with ❤️ for wildlife conservation