---
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.