Analog Switch Input

Overview

An Analog Switch Input reads a multi-position switch on a single analog pin. Instead of one wire per position, the switch presents a different voltage (or resistance) for each position, and this input decodes which position is selected. Use it for rotary mode switches, multi-button steering controls and resistor-ladder keypads.

Prerequisites & hardware

  • A switch wired to one analog pin that produces a distinct level per position.
  • Know each position's nominal value so you can set the recognition tolerance.
  • External divider: the input does not provide an internal pull-up. In Resistors mode you fit an external pull-up resistor (and optionally a pull-down) to turn the switch's resistance into a voltage, and enter those resistor values so the controller can work out the switch resistance. In Voltage mode the switch presents the voltages directly and no divider is needed.

Add it in the app

  1. Add a new input and choose Analog Switch Input as the type.
  2. Select the pin the switch is wired to.
  3. Give it a clear alias (e.g. Mode Switch).
  4. Choose the mode and range. The two modes are mutually exclusive — pick whichever suits your hardware:
  5. Resistors: enter the external pull-up (and pull-down) resistor values that form the divider.
  6. Voltage: enter the voltage range (min/max voltage) the position sits in.
  7. Set the precision and, for mechanical switches, the debounce timings.

Settings reference

Setting Meaning Unit Range / values Notes
Range Input voltage range / scaling reference — 5 V, Internal 5 V, 12 V, Raw Choose to cover the switch's full-scale voltage. Raw reports unscaled counts.
Mode How the position is defined — the two are mutually exclusive — Resistors, Voltage Resistors = an external pull-up/pull-down divider turns the switch resistance into a voltage; Voltage = the position is recognised by its voltage range. Configure only the fields for the mode you choose.
Pull-up Value of the external pull-up resistor forming the divider Ω uint32 Resistors mode only. Tells the controller the divider's upper leg so it can compute the switch resistance.
Pull-down Value of the external pull-down resistor Ω uint32 Resistors mode only. The lower leg of the divider (optional).
Min voltage / Max voltage Voltage range for the position mV uint32 Voltage mode only. The window the position's voltage falls in.
Precision Matching tolerance for recognising the position — uint32 How close a reading must be to count as this position. Too loose = wrong position; too tight = missed positions.
Enable filter Turns on debounce filtering — on / off Recommended for mechanical switches.
Delay Debounce delay before a change is accepted ms sint32 New position must be stable this long.
Hold Minimum time a position is held ms sint32 Stops rapid re-triggering.
Interspace Minimum gap between transitions ms sint32 Ignores transitions closer than this.

Common settings

Analog Switch Input also uses the shared settings — alias and pin. See Common IO Settings.

Example — detect one switch position (Voltage mode)

Each Analog Switch Input recognises one position/level. This example detects a single rotary position that sits at ~2.5 V:

  1. Type Analog Switch Input, alias Mode Pos 2, on the switch's pin.
  2. Mode Voltage, Range 5 V.
  3. Min/Max voltage 2300/2700 mV — the window around that position.
  4. Precision moderate so the detent maps cleanly to this position.
  5. Enable filter, Delay 20, Hold 30 to settle between detents.

To decode every position of a multi-position rotary as its own signal, add one Analog Switch Input per position — e.g. a 5-position rotary uses 5 inputs, each watching its own voltage range. That is a valid setup but not the typical use; most installs detect a single switch level.

Troubleshooting

  • Wrong position selected / jumps between two: the levels are too close for the precision — tighten precision or space the positions further apart.
  • No position recognised: in Voltage mode the reading is outside Min/Max voltage; in Resistors mode the entered pull-up/pull-down values don't match the resistors actually fitted.
  • Position flickers when turning: enable the filter and raise Delay / Interspace.
  • Voltage doesn't change with the switch (Resistors mode): check the external pull-up is fitted — without it the divider produces no voltage.