firmware-base/docs-c/components/POT.md

title	description	keywords
POT - Analog Potentiometer Reader Component	ESP32 analog potentiometer reader with digital filtering capabilities and Modbus integration	ESP32 potentiometer analog filtering modbus industrial control embedded systems

POT - Analog Potentiometer Reader

Path: src/pot.h

Revision History: Initial documentation

A lightweight, efficient analog potentiometer reader component with multiple filtering options and Modbus integration. It features three damping algorithms (none, moving average, and EMA), deadband processing to suppress noise, and support for both local and remote control modes.

REQUIREMENTS

• Hardware:
  • Analog input pin for potentiometer connection
  • Optional RC low-pass filter hardware for additional noise reduction
• Software:
  • Arduino framework
  • ArduinoLog library
  • Modbus support (ModbusTCP)

FEATURES

• Three damping algorithms:
  • No damping (raw readings)
  • Moving Average (box-car) filtering with configurable window size
  • Exponential Moving Average (EMA) with configurable alpha
• Dead-band filtering to suppress small value changes
• Configurable scaling from raw ADC values (0-1023) to application range (0-100 by default)
• Modbus TCP integration with support for:
  • Reading current potentiometer value
  • Switching between local and remote control modes
  • Setting remote value for when in remote control mode
• No dynamic memory allocation, designed for resource-constrained microcontrollers
• Avoids floating-point operations for optimal performance

DEPENDENCIES

• Component
• App
• ArduinoLog
• Modbus
• ModbusTCP

graph TD
    POT --> Component
    POT --> App
    POT --> ArduinoLog
    POT --> Modbus
    POT --> ModbusTCP

BEHAVIOUR

stateDiagram-v2
    [*] --> Setup: Initialization
    Setup --> Local: Default Mode
    Setup --> Remote: Via Modbus

    state Local {
        [*] --> ReadAnalogValue
        ReadAnalogValue --> ApplyFilter
        ApplyFilter --> ApplyDeadband
        ApplyDeadband --> NotifyIfChanged
    }

    state Remote {
        [*] --> ReadModbusValue
        ReadModbusValue --> NotifyIfChanged
    }

    Local --> Remote: Mode Change via Modbus
    Remote --> Local: Mode Change via Modbus

TODOS

PERFORMANCE

• Consider adaptive filtering based on rate of change for better response characteristics
• Explore efficient normalization techniques to handle different ADC resolutions (10-bit vs 12-bit)
• Implement more sophisticated filtering algorithms if needed for high-noise environments

SECURITY

• Add bounds checking for remote control values to prevent overflow/underflow conditions
• Implement authentication for remote control mode changes in security-sensitive applications
• Consider adding fail-safe behavior for loss of Modbus communication

COMPLIANCE

• Verify compliance with IEC 61131-3 for industrial control systems
• Ensure Modbus implementation follows Modbus specification guidelines
• Document EMC considerations for analog input circuits

RECOMMENDATIONS

• Use a hardware RC low-pass filter as suggested in the component comments for noisy environments
• Select appropriate damping algorithm based on application needs:
  • NONE: Fast response but noisy
  • MOVING_AVERAGE: Good balance of smoothing and responsiveness
  • EMA: Smooth response with less memory requirements
• Adjust deadband (POT_DEADBAND) based on the stability requirements of the application

EXAMPLE

This example demonstrates how to initialize a POT component with moving average filtering:

#ifdef PIN_POT_SPEED
  potSpeed = new POT(
    this,                         // owner
    PIN_POT_SPEED,               // pin
    ID_POT_SPEED,                // id
    POT_SPEED_MB_ADDR,           // modbusAddress
    POTDampingAlgorithm::DAMPING_MOVING_AVERAGE // filtering algorithm
  );
  
  if (potSpeed)
  {
    components.push_back(potSpeed);
    Log.infoln(F("POT Speed initialized. Pin:%d, ID:%d, MB:%d"),
               PIN_POT_SPEED, ID_POT_SPEED, POT_SPEED_MB_ADDR);
  }
  else
  {
    Log.errorln(F("POT Speed initialization failed."));
  }
#endif

References

The component implements several filtering techniques for noise reduction:

• Moving Average: Implemented as an incremental ring buffer with O(1) complexity
• Exponential Moving Average (EMA): Uses a 1-pole IIR filter with the formula: y[n] = y[n-1] + (x[n] - y[n-1]) / 2^k

The hardware recommendations include an RC low-pass filter with the potentiometer itself serving as the resistor, and suggested capacitor values based on desired cutoff frequencies:

• For faster response (~30 Hz): Use 1 μF
• For moderate filtering (~10 Hz): Use 2.2 μF or 3.3 μF
• For more smoothing (~5 Hz): Use 4.7 μF or 6.8 μF