116 lines
4.3 KiB
Markdown
116 lines
4.3 KiB
Markdown
---
|
|
title: "Analog Level Switch Component Documentation"
|
|
description: "Documentation for the AnalogLevelSwitch component, which reads analog inputs as multi-position switches"
|
|
keywords: "ESP-32, analog, level switch, multi-position switch, modbus, Arduino, embedded"
|
|
---
|
|
|
|
## Analog Level Switch
|
|
|
|
**Path**: [`src/AnalogLevelSwitch.cpp`](../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](https://github.com/thijse/Arduino-Log) - For logging capabilities
|
|
- [Component](../src/Component.h) - Base component class
|
|
- [ModbusTCP](../src/modbus/ModbusTCP.h) - For Modbus communication
|
|
|
|
```mermaid
|
|
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.
|
|
|
|
```mermaid
|
|
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
|
|
|
|
```cpp
|
|
#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. |