4.3 KiB
| title | description | keywords |
|---|---|---|
| Analog Level Switch Component Documentation | Documentation for the AnalogLevelSwitch component, which reads analog inputs as multi-position switches | ESP-32, analog, level switch, multi-position switch, modbus, Arduino, embedded |
Analog Level Switch
Path: src/AnalogLevelSwitch.cpp
Revision History: Initial documentation
The Analog Level Switch component reads an analog input pin and interprets the voltage as a discrete position or "slot". This is useful for interfacing with multi-position switches, potentiometers, or resistor networks connected to an analog input. The component provides smooth reading with configurable debouncing, hysteresis, and auto-calibration for reliable slot detection.
REQUIREMENTS
- An analog input pin connected to a voltage divider circuit
- Appropriate resistor selection for desired voltage levels (detailed guidance provided in header file)
FEATURES
- Converts analog readings into discrete position slots
- Configurable number of positions/slots (up to 32 by default)
- Adjustable ADC value offset and step size per slot
- Smoothing with moving average or exponential moving average
- Configurable debouncing and hysteresis to prevent position flickering
- Modbus integration with registers for current level and raw values
- Individual slot state monitoring as Modbus coils
DEPENDENCIES
- ArduinoLog - For logging capabilities
- Component - Base component class
- ModbusTCP - For Modbus communication
graph TD
AnalogLevelSwitch --> Component
AnalogLevelSwitch --> ModbusTCP
AnalogLevelSwitch --> ArduinoLog
Component --> App
BEHAVIOUR
The AnalogLevelSwitch reads the analog input at regular intervals, applies smoothing, debouncing, and then maps the analog value to a discrete slot.
stateDiagram-v2
[*] --> Initialize
Initialize --> ReadAnalog
ReadAnalog --> SmoothValues
SmoothValues --> DetermineSlot
DetermineSlot --> Debounce
Debounce --> StateChanged: n confirmations
Debounce --> ReadAnalog: not confirmed
StateChanged --> NotifyChange
NotifyChange --> ReadAnalog
TODOS
PERFORMANCE
- Review smoothing algorithm choice based on application requirements (MA vs EMA)
- Consider using hardware filtering for high-noise environments
- Optimize ADC reading intervals based on use case
SECURITY
- Validate Modbus access controls to prevent unauthorized writes
- Consider adding range validation for configuration parameters
COMPLIANCE
- Ensure ADC readings are within the ESP-32's input voltage specifications
- Review compliance with relevant industrial standards if used in regulated environments
RECOMMENDATIONS
- For optimal performance, use 1% or better tolerance resistors in voltage divider
- Keep equivalent resistance of voltage divider relatively low (1k-100k range) to ensure ADC accuracy
- Be mindful of resistor tolerance and ADC non-linearity when designing circuits
- Use the resistor calculation guidance in the header file to design appropriate circuits
EXAMPLE
#ifdef PIN_ANALOG_LEVEL_SWITCH
analogLevelSwitch = new AnalogLevelSwitch(
this, // owner
PIN_ANALOG_LEVEL_SWITCH, // analogPin
ALS_NUMBER_OF_LEVELS, // numLevels
ALS_LEVEL_STEP, // levelStep
ALS_ADC_VALUE_OFFSET, // adcValueOffset
ID_ANALOG_LEVEL_SWITCH, // id
ALS_MODBUS_ADDR // modbusAddress
);
if (analogLevelSwitch)
{
components.push_back(analogLevelSwitch);
Log.infoln(F("AnalogLevelSwitch initialized. Pin:%d, Levels:%d, Step:%d, Offset:%d, ID:%d, MB:%d"),
PIN_ANALOG_LEVEL_SWITCH, ALS_NUMBER_OF_LEVELS, ALS_LEVEL_STEP,
ALS_ADC_VALUE_OFFSET, ID_ANALOG_LEVEL_SWITCH, ALS_MODBUS_ADDR);
}
else
{
Log.errorln(F("AnalogLevelSwitch initialization failed."));
}
#endif
References
The component is specifically designed for multi-position switches using voltage dividers. The header file includes detailed information on the resistor selection process for creating a voltage divider setup that can reliably detect different switch positions.