README Version 0.0.1 • Revised: September 27, 2025 • Author: AvantMaker • https://www.AvantMaker.com

This project is proudly brought to you by the team at AvantMaker.com.

Visit us at AvantMaker.com where we've crafted a comprehensive collection of Reference and Tutorial materials for the ESP32, a mighty microcontroller that powers countless IoT creations.

AvantAnalogRead is an advanced analog input management library for ESP32, enhancing the standard Arduino analogRead functionality. It provides multi-pin management, configurable debouncing, threshold detection, and software filtering, making it ideal for complex analog monitoring scenarios such as sensor data acquisition and user interface controls.

• Multi-pin Management: Dynamically add and remove pins for unified control.
• Built-in Debouncing: Customizable debounce time for stable readings.
• Threshold Detection: Configurable threshold values with gap control to prevent false triggers.
• Software Filtering: Built-in moving average filter for noise reduction.
• Rich Event Detection: Detects value changes, rising/falling trends, and threshold crossings.
• Non-Blocking Design: Ensures the main program flow is not interrupted.
• Unified Callback Format: Simplifies code and reduces the learning curve.

1. Open the Arduino IDE.
2. Go to Tools > Manage Libraries....
3. Search for AvantAnalogRead.
4. Click the Install button.

1. Download the ZIP file of this repository.
2. Open the Arduino IDE.
3. Go to Sketch > Include Library > Add .ZIP Library....
4. Select the downloaded ZIP file.

Copy the AvantAnalogRead.h, AvantAnalogRead.cpp, and PinConfig.h files from the src folder into your project folder.

Here is a simple example demonstrating how to use the AvantAnalogRead library to monitor a potentiometer (attached to GPIO Pin 33 of ESP32):

#include <AvantAnalogRead.h>

// Create AvantAnalogRead object to handle analog input monitoring
AvantAnalogRead analogReader;

void setup() {
  // Initialize serial communication at 115200 baud rate
  Serial.begin(115200);
  delay(1000);  // Wait for serial to stabilize
  
  // Print example title and separator
  Serial.println("AvantAnalogRead Library Example: Using onChange function");
  Serial.println("=====================================");
  
  // Initialize pin 33 for analog input monitoring
  if (analogReader.addPin(33)) {
    Serial.println("Pin 33 initialization successful!");
    
    // Set debounce time to 100 milliseconds to prevent rapid successive triggers
    analogReader.setDebounceTime(33, 100);
    
    // Set threshold gap to 30 to avoid triggering events with minor fluctuations
    // This means the value must change by at least 30 units to trigger an event
    analogReader.setThresholdGap(33, 30);
    
    // Enable software filtering to reduce noise (filter size of 5)
    // This averages multiple readings to provide more stable values
    if (analogReader.enableFilter(33, 5)) {
      Serial.println("Software filtering enabled for pin 33!");
    } else {
      Serial.println("Failed to enable software filtering for pin 33!");
    }
    
    // Register onChange callback function to be called when pin value changes
    // The callback will be triggered when the value changes beyond the threshold
    if (analogReader.onChange(33, onPinChange)) {
      Serial.println("onChange callback function registered successfully!");
    } else {
      Serial.println("onChange callback function registration failed!");
    }
  } else {
    Serial.println("Pin 33 initialization failed!");
  }
  
  Serial.println("Starting to monitor analog input on pin 33...");
  Serial.println("=====================================");
}

void loop() {
  // Update all pin states and detect events
  analogReader.update();
  
  // Read and display current value once per second (for demonstration only, adjust as needed in actual applications)
  // This helps visualize the current analog value but is not required for the onChange functionality
  static unsigned long lastPrintTime = 0;
  if (millis() - lastPrintTime >= 1000) {
    int currentValue = analogReader.readPin(33);
    if (currentValue >= 0) {
      Serial.printf("Current pin 33 reading: %d\n", currentValue);
    } else {
      Serial.println("Failed to read pin 33!");
    }
    lastPrintTime = millis();
  }
  
  // Short delay to avoid excessive CPU usage
  delay(10);
}


// Callback function: Called when pin value changes beyond the threshold
// This function is automatically triggered when the analog value changes by more than the threshold gap
// Parameters:
//   pin: The pin number that triggered the event
//   value: The current analog value (0-4095)
//   event: The type of event that occurred
void onPinChange(int pin, int value, EventType event) {
  Serial.printf("Pin %d value changed! Current value: %d", pin, value);
  Serial.println();
}

• addPin(int pin): Initializes a specified pin and adds it to the management list.
• removePin(int pin): Removes a pin from the management list and releases its resources.
• isInitialized(int pin): Checks if a pin has been initialized.
• readPin(int pin): Reads the current filtered value of a specified pin.

• setDebounceTime(int pin, unsigned long debounceMs): Sets the debounce time for a specified pin.
• getDebounceTime(int pin): Gets the debounce time setting for a specified pin.
• setThreshold(int pin, int threshold): Sets the threshold value for a specified pin.
• getThreshold(int pin): Gets the threshold value for a specified pin.
• setThresholdGap(int pin, int gap): Sets the threshold gap to prevent noise from triggering events.
• getThresholdGap(int pin): Gets the threshold gap setting for a specified pin.

• enableFilter(int pin, int size): Enables software filtering with the specified filter size (2-20).
• disableFilter(int pin): Disables software filtering for a specified pin.
• isFilterEnabled(int pin): Checks if software filtering is enabled for a specified pin.
• getFilterSize(int pin): Gets the filter size for a specified pin.

• onChange(int pin, PinCallback callback): Sets the callback function for value changes.
• onRising(int pin, PinCallback callback): Sets the callback function for rising values.
• onFalling(int pin, PinCallback callback): Sets the callback function for falling values.
• onAboveThreshold(int pin, PinCallback callback): Sets the callback function for values above threshold.
• onBelowThreshold(int pin, PinCallback callback): Sets the callback function for values below threshold.

• enablePinEvents(int pin): Enables all event detection for a specified pin.
• disablePinEvents(int pin): Disables all event detection for a specified pin.
• enableAllEvents(): Enables event detection for all initialized pins.
• disableAllEvents(): Disables event detection for all pins.

• update(): Processes the value detection and event triggering for all pins. Must be called regularly in loop().

The library includes several example sketches to demonstrate different features:

• BasicChangeMonitor: Demonstrates basic value change detection with a potentiometer.
• BasicRiseFallMonitor: Shows how to detect rising and falling value trends.
• BasicThresholdMonitor: Illustrates threshold crossing detection.
• changeStopHandling: Detects when a potentiometer stops changing and reports the final stable value.
• EventManage: Demonstrates event management methods with two potentiometers.
• PotMQTTControl: Combines potentiometer monitoring with MQTT to send stable values to a broker.
• PotWebServer: Displays real-time potentiometer values on a webpage served by ESP32.

1. All pins must be initialized with addPin() before use.
2. The update() function must be called regularly in loop(), preferably with an interval of no more than 50ms.
3. Callback functions should be kept as short as possible to avoid delaying other operations.
4. For high-precision detection, it is recommended to reduce the update() call interval.
5. In memory-constrained environments, removePin() can be used to release resources for pins that are no longer needed.
6. The software filter size should be chosen based on the noise level of your analog signal - larger values provide more smoothing but increase response time.

This library is released under the MIT License. See the LICENSE file for details.

Contributions are welcome! Please feel free to submit issues and pull requests.

💡 Check out our other ESP32 libraries at AvantMaker GitHub!