ESP32 Cam EZB Firmware

• FreeRTOS task separation for stability and performance

  • EZB (ARC protocol) processing now runs in its own high-priority task.
  • Camera streaming runs in a dedicated task to prevent video stalls during heavy EZB traffic.
  • EZ-B scan UDP broadcast runs in its own low-priority task for consistent discovery without impacting control or video.

• Configurable UART pin mapping for EZB UART Expansion

  • UART RX/TX pins can now be explicitly assigned using the defines in the configuration section.

• Servo outputs mapped to UART RX/TX pins are automatically detached to avoid PWM/UART contention.

• Improved EZB TCP receive handling

  • Socket RX is aggressively drained into a ring buffer to prevent TCP window shrink and ARC command throttling.
  • Non-blocking RX pump using available() to avoid rare stalls or watchdog resets under heavy traffic.

Fixed

• WiFiClient initialization bugs

  • Removed invalid WiFiClient = NULL usage that could cause undefined behavior or crashes.
  • Added proper connection validation before RX/TX operations.

• Camera framebuffer lifetime handling

  • Ensures esp_camera_fb_return() is always called to prevent memory exhaustion and camera lockups.

• Camera + PWM timer conflicts

  • Reserved LEDC timer for camera XCLK and restricted ESP32Servo to safe timers to prevent camera clock corruption.

• UDP broadcast reliability

  • Uses subnet-directed broadcast instead of limited broadcast to improve EZB discovery on segmented networks and APs.

Performance Improvements

• Reduced protocol parsing stalls by bounding EZB command processing per tick.
• Lowered contention between camera streaming and EZB command bursts via task prioritization.
• Improved camera compression stability using frame-window averaging to reduce visible flicker.

Internal / Refactoring

• Centralized EZB protocol handling into a dedicated task.
• Added task handles for debugging and runtime inspection.
• Hardened WiFi reconnect behavior in client mode.
• Added missing helpers for camera client lifecycle handling.

Notes

• UART RX/TX pins must not overlap camera GPIOs for the selected camera model.
• ESP32-WROVER users should prefer Serial2 for UART Expansion to avoid flash/PSRAM pin conflicts.
• For best stability, keep EZB task priority higher than camera and broadcast tasks.

Camera capture pipeline

• Removed OV2640 wrapper dependency

  • uses the native ESP-IDF camera API directly: esp_camera_init(), esp_camera_fb_get(), and esp_camera_fb_return().

• Fixed/strengthened frame buffer lifecycle

  • always returns the framebuffer (esp_camera_fb_return(fb)) even on warnings/edge cases to prevent leaks/stalls.

• More robust init error handling

  • checks the return value of esp_camera_init() and prints a helpful diagnostics block (wrong model define, ribbon cable, power, lowering clock, etc.) before halting.

• JPEG quality bounds / alignment

  • clamps compression to 1..63 (ESP32 camera semantics)

• PSRAM-aware framebuffer count

  • sets fb_count = 2 only if psramFound(), otherwise fb_count = 1 to reduce memory pressure.

Auto compression (ACOMP)

• Refactored ACOMP logic into a dedicated function

  • introduces performAutoCompression(uint32_t imgSize) and calls it per frame.

• Uses the same averaging approach, but is cleaner/less error-prone

  • accumulate _acomImgSizeSum/_acomImgSizeCount, compute average over ACOMPFRAMECNT, then adjust _compression by ACOMPSTEP within bounds.

GPIO / servo / pin-mode management

• New pin-mode cache by GPIO number (0..254)

  • replaces the old _PIN_MODES[24] "GPIO index" cache with _GpioModeCache[255] keyed by actual GPIO number.
  • This avoids the incorrect assumption that GPIO numbers are always < 24.

• Servo storage changed to per-ARC-port (instead of per-GPIO index)

  • Servo _ServosByArcPort[24];

• Removed invalid "GPIO validity" model

  • removes that and instead:
    • detaches servos by ARC port
    • caches pinMode by actual GPIO value

• Safer detach behavior when repurposing pins

  • adds detachServoByARCPort() and uses it before setting pins for GPIO/PWM reads/writes.

Camera pin conflict detection

• Kept feature, improved positioning and clarity
  • include anyPinMatch() + verifyNoCameraPinConflict() to halt with a clear message if ARC mapping overlaps camera-required GPIOs.
  • places the comment block above verifyNoCameraPinConflict() explaining why it exists and what users should do.

WiFi / connectivity / streaming

• More explicit camera warning case
  • warns when esp_camera_fb_get() returns null/empty, with more direct wording.

• Added a verification in the Setup() to check if there's a conflict between any camera pins and ARC_ESP32 mapping pins. The Digital, Servo, and ADC pins cannot be the same as those used in the Camera, otherwise there will be a peripheral conflict. The firmware will display a looping error message in the serial monitor if there is a pin conflict.

You have two options to resolve a conflict, but first, make sure you have selected the board settings that match your board.

Here are your options to rectify a pin conflict...

1. View the datasheet/schematic or pinouts of the PCB and look for PINs that do not conflict with those listed for your module in camera_pins.h. Replace the conflicting PINs with the PINs you would like to use instead. For example, if pin #4 conflicts with servo or DIGITAL pin mapping, change it to a pin that is not already in use and available on the PCB.

2. Remove the entry entirely by moving every pin value up and adding a 0xff at the end. There must always be 24 entries.

3. If you don't care about organizing anything, replace the value with 0xff, and that ARC Dx pin will not do anything. But,  you'll end up with a value in the middle of your port range that doesn't do anything, which might be kinda weird.

Compiling Instructions:

• This was designed with.... Board: ESP32 by Espressif Systems Version 3.3.5 Library: ESP32Servo by Kevin Harrington Version 3.1.3

Camera & Image Pipeline

• Switched to using the official esp_camera.h API alongside the OV2640 wrapper for improved compatibility with newer ESP32 camera cores.
• Added configurable camera XCLK frequency via XCLOCK_FREQUENCY (#define), allowing selection between 20 MHz (default) and 10 MHz for long/poor-quality ribbon cables or noisy environments.
• Zeroed the camera_config_t structure with memset() before use to ensure all new fields introduced by the ESP32 camera library start from a known state.
• Added a robust check for esp_camera_sensor_get() returning nullptr and a descriptive error message to the Serial console, with a safe halt loop if the camera fails to initialize.
• Added a confirmation log message when the camera initializes successfully.
• Improved the auto-compression (ACOMP) logic:
  • Uses safer accumulation and division with guards for zero-frame conditions.
  • Casts image size and average size more defensively.
  • Keeps compression changes within a defined 5-60 range with an explicit target window around 7-8 KB per frame.
• Ensured the camera’s LEDC timer (timer 3 / channel 7) is reserved exclusively for XCLK so servo PWM cannot accidentally reconfigure the camera clock.

WiFi & Network Behavior

• Expanded WiFi event handling to cover the full WiFiEvent_t enum, including RSSI low, beacon timeout, remain-on-channel, WPS PBC overlap, and more, with detailed Serial logging.
• Added a separate Arduino-layer IPEvent() handler for arduino_event_t, covering WiFi and Ethernet events (IPv4/IPv6 acquisition, connect/disconnect, AP events) with verbose Serial diagnostics.
• Kept WiFi.setSleep(false) to prioritize low-latency streaming while documenting the trade-off with power consumption.
• In AP mode, changed the default softAP IP from 192.168.50.1 to 192.168.1.1 for a more standard local network layout.
• Preserved the ESP.restart() safety behavior in client mode when WiFi connectivity is lost, ensuring the device self-recovers.

ARC / ESP32 Pin Mapping

• Introduced explicit mapping tables to decouple ARC logical ports from ESP32 GPIO numbers:
  • ARC_TO_ESP_DIGITAL_PIN_MAPPING[24]
  • ARC_TO_ESP_SERVO_PIN_MAPPING[24]
  • ARC_TO_ESP_ADC_PIN_MAPPING[8]
• Documented that ARC has 24 digital/servo Dx ports and 8 ADC ports, with unmapped entries set to 0xff.
• Reworked all digital, servo, PWM, ultrasonic, and ADC commands to use these mapping tables instead of assuming ARC port index == ESP32 GPIO number.
• Added isArcPortValid() and isGpioValid() helpers to safely validate indices before touching arrays or GPIO, avoiding out-of-range access.

Servo / PWM Handling

• Increased the _Servos array size to 24 and tied it to the mapped GPIO indices for more consistent ARC-to-ESP mapping.
• Added a pin-mode cache (_PIN_MODES[24]) initialized to -1 at startup, so pin configuration is only applied when needed.
• Added servo as a dedicated pin-mode value to distinguish servo-controlled pins from normal INPUT/OUTPUT.
• Introduced guarding logic so that:
  • Setting digital outputs or PWM on a pin will detach any servo mapped to the same ARC port first.
  • Servo and digital usage no longer conflict silently on shared pins.
• Limited ESP32Servo/ESP32PWM to use only LEDC timers 0, 1, and 2 so that timer 3 remains permanently reserved for the camera XCLK.

EZB Protocol & Command Handling

• Kept the core EZB command set (ping, firmware ID, digital, servo, PWM, ultrasonic, ADC, UART expansion, etc.) but refactored the implementation to use the new ARC/ESP mapping tables.
• CmdReleaseAllServos now iterates the ARC_TO_ESP_SERVO_PIN_MAPPING table and only detaches servos on mapped pins, avoiding touching unknown or invalid GPIOs.
• Servo positioning (CmdSetServoPosition) now:
  • Validates ARC port range.
  • Looks up the mapped servo GPIO.
  • Uses servo pin mode and attach/detach behavior based on position, with bounds checking via isGpioValid().
• PWM speed (CmdSetPWMSpeed) now:
  • Uses the servo mapping to find the GPIO used for PWM.
  • Detaches any servo on that GPIO before running analogWrite().
• Digital on/off and digital read commands now:
  • Validate ARC ports.
  • Map through ARC_TO_ESP_DIGITAL_PIN_MAPPING and detach servos only if they share the same GPIO.
  • Enforce correct pin mode (INPUT/OUTPUT) via the pin-mode cache.
• Ultrasonic (CmdHC_SR04) now:
  • Validates ARC ports.
  • Uses digital mapping for both trigger and echo.
  • Detaches any servos that share those GPIOs before triggering.
  • Works only on mapped, valid pins and still returns distance in cm as uint8_t.
• ADC read (CmdGetADCValue) now:
  • Uses ARC_TO_ESP_ADC_PIN_MAPPING instead of a fixed switch statement.
  • Returns 0 for unmapped ADC ports or invalid mappings, with pin-mode setup only when a valid GPIO is configured.
• Added an error(const char*) helper that prints a descriptive message in a tight loop when an invalid ARC port is detected for critical commands, making configuration issues very visible during development.

UART / Serial Enhancements

• Switched to Serial2.setRxBufferSize(8000) for ESP32 core compatibility (replacing setRxBuffer()).
• Kept readSerial2Byte() as a blocking helper that reads directly from Serial2, matching the previous behavior while simplifying the code.
• Maintained the UART expansion commands for CmdEZBv4 (UARTExpansion0/1/2) but ensured they work cleanly with the new buffer configuration and mapping safety checks.

Internal Structure & Safety

• Added explicit forward declaration of doEZProtocol() near the top of the file for clarity.
• Converted several short utility functions (IsAvail, Avail, validity checks) to inline for performance in the tight main loop and protocol handler.
• Replaced the EZ header globals with macros:
  • EZHEADER and EZHEADER_LEN
  • Simplifies use when writing the image prefix to the camera client.
• When accepting new CAM and EZB clients, now use a temporary WiFiClient variable before assigning to the global to avoid partial or invalid states.
• Improved comments and documentation throughout the file, especially around:
  • Camera configuration and troubleshooting.
  • ARC-to-ESP pin mapping behavior.
  • WiFi and Arduino event handling.
  • Expected behavior when port mappings are incorrect.

Behavioral Changes You May Notice

• Default AP IP is now 192.168.1.1 instead of 192.168.50.1.
• If the wrong CAMERA_MODEL_x is selected or the camera fails to initialize, the firmware now prints a clear error and halts instead of failing silently with zero-length frames.
• Digital, servo, PWM, ultrasonic, and ADC operations are now mediated through explicit ARC mappings, making it easier to port this firmware to other ESP32-based boards by adjusting only the mapping tables.
• Auto-compression of camera images should be more stable with fewer visible jumps in JPEG quality due to the guarded averaging logic.

• Removed firmware-level Serial2 RX ring buffer and switched to ESP32 UART hardware buffer (setRxBuffer(8000)).
• Updated UART expansion commands to read/write directly from Serial2.
• Removed unused Serial2 buffer code and related helper functions.
• Minor code cleanup and simplification around UART handling.
• Digital read fix: CmdGetDigitalPort previously returned the port index instead of the actual digital pin state - now correctly returns digitalRead(port).
• Camera/EZB client IP logging fix: Printed _CLIENT.remoteIP() before assigning the client object - corrected to log after available().
• HSR04 bounds check fix: Port range check used <= _PortCnt (off-by-one) - corrected to < _PortCnt since _PortCnt is a count, not last index.

1. Install libraries into arduino ide: https://dl.espressif.com/dl/package_esp32_index.json

2. Board manager install ESP32 by Espressif Systems

This project builds using...

• Espressif Systems esp32 library version 3.0.7
• ESP32Servo by Kevin Harrington version 3.0.6

Version Information

• Added editable definitions at the top of the ino source file for enabling/disabling features

Version Information

• Increase the auto compression adjustment jump from 1 to 5 so it responds quicker.

Version Information

• Works with servo & Camera at the same time
• Added a note that the default IP address in AP Mode is (192.168.50.1)

Version Information

• Works with servos & camera at the same time

Version Information

• added dynamic camera compression

• mapped Dx to GPIOx (i.e. ARC D4 = GPIO4, which is the FLASH LED)

Version Information

• First check-in of the ESP32 Cam firmware

*Note: For servo use with EZ-Cam, only pins 2,4,12-19,21-23,25-27,32-33 are recommended.