Analog Inputs

Analog inputs are two-part configuration items. First you add the physical signal as an input. Then you define what the changing values mean in the Level Inputs section.

Use this flow for potentiometers, sliders, pressure sensors, distance sensors, meters, and any prop control that reports a changing level instead of a simple on/off state.

Display prerequisite

The Level Inputs section appears after at least one analog input source is configured in Configure > Connections > Inputs, Outputs, and Modules.

Setup path

Step	UI path	What you configure
1	Configuration > Connections > Inputs	The physical analog source, input ID, and pin or channel
2	Configuration > Definitions > Level Inputs	The ranges, centers, maps, smoothing, and labels that give the analog value meaning
3	Configuration > Behavior	The rule, sequence, or action that uses the level input value
4	Monitor or live configuration view	The raw and smoothed values while the prop hardware is moved

Do not start in Level Inputs until the analog source exists. If no analog inputs have been added, the Level Inputs section shows No analog inputs configured.

Add the analog source

1. Open the controller UI.
2. Go to Configuration.
3. Open Connections.
4. Find the Inputs section.
5. Add a new input.
6. Choose an analog input type such as Analog Sensor or Custom Analog.
7. Give it a clear ID, for example radio_dial, pressure_plate, or slider_left.
8. Select the physical pin, expansion input, or multiplexer channel that the sensor is wired to.
9. Save or apply the configuration.
10. Move the physical control and confirm the live value changes.

The ID is important because Level Inputs, behavior rules, and operator views use it as the source reference. Use a name that describes the prop part, not the electronics part.

Define the level input

After the source exists, define how the controller should interpret the changing value.

1. Go to Configuration.
2. Open Definitions.
3. Open Level Inputs.
4. Click Add Level Input Control.
5. Select the analog source in the Input dropdown.
6. Choose the Mode that matches the prop behavior.
7. Use the current raw and smoothed readings in the card header while adjusting the physical control.
8. Use Learn buttons to capture real values from the installed hardware.
9. Save the configuration.

Each Level Input Control can read one analog source and turn it into named ranges, centered targets, or an output map.

Common fields

Control	What it does
Name	Optional display name for this level control. If blank, the UI follows the selected input name.
Input	Selects the analog input source created in Connections > Inputs.
Mode	Chooses how the value is interpreted: Range, Center, or Map.
Scale	Uses Linear for normal sensors and Logarithmic when useful for controls that feel better with a curved response.
Current	Shows the latest raw input reading. Use it while moving the prop.
Smoothed	Shows the stabilized reading after smoothing/noise handling. Use this for final threshold choices.

Range mode

Use Range mode when the puzzle cares which band the value falls inside.

Examples include a radio dial with station zones, a slider with low/medium/high positions, a pressure gauge with safe/warning/danger zones, or a lever that must land inside a valid window.

Control	What it does
Min	Lower fallback value for the control.
Max	Upper fallback value for the control.
Learn Min	Captures the current live value as the minimum.
Learn Max	Captures the current live value as the maximum.
Range slot Name	The label behavior rules can use, such as station_3, safe, or too_high.
Range slot Min	Lowest value included in that named slot.
Range slot Max	Highest value included in that named slot.
Slot Learn Min/Max	Captures the installed hardware reading into that slot.
Add Slot	Adds another named band for the same analog source.

A range slot should include player tolerance. Do not make the slot only one or two raw units wide unless the hardware is extremely stable.

Center mode

Use Center mode when the puzzle has one or more target values with tolerance around each target.

Examples include a tuning dial, combination knob, balanced meter, or alignment prop where the exact center matters but the player should not need pixel-perfect precision.

Control	What it does
Center	The target reading for the current slot.
Variance %	The tolerance around the center value. Larger values are easier for players.
Learn Center	Captures the current live value as the target center.
Slot Name	The value label exposed to behavior rules.
Add Slot	Adds another named target center for the same input.

Use Center mode when the player is trying to hit a target. Use Range mode when the player is moving through zones.

Map mode

Use Map mode when the analog input should continuously drive another system instead of producing a named trigger.

Examples include using a slider to control DMX brightness, mapping a knob into an output range, or translating a sensor value into a lighting/display span.

Control	What it does
Target Type	Selects the kind of output or subsystem to drive.
Target	Selects the specific configured target in that subsystem.
Channel/Span	Selects the target channel, start channel, or span field used by that target type.
In Min	The analog reading that should produce the minimum output.
In Max	The analog reading that should produce the maximum output.
Out Min	The output value sent when the input is at In Min.
Out Max	The output value sent when the input is at In Max.
Scale	Linear gives a straight response. Logarithmic gives a curved response.
Tolerance	Ignores tiny changes so the mapped output does not chatter.

Map mode creates a live mapping. It is not the right choice when you want a named puzzle state such as correct, too_low, or station_4; use Range or Center for those cases.

Noise floor and smoothing

Analog values can move slightly even when the prop is not being touched. Use these controls to make the firmware respond to intentional player movement instead of electrical noise.

Control	What it does
Enable Noise Trigger	Keeps noise handling active for the level input. Leave this enabled for most physical sensors.
Adaptive	Lets the controller track the baseline automatically instead of using only a fixed threshold.
Threshold	Fixed movement amount required before a change is treated as intentional. This is disabled when Adaptive is active.
Smoothing %	Stabilizes readings. Higher smoothing is steadier but responds more slowly.

Set smoothing after you watch the real hardware. If the Smoothed value lags too far behind the Current value, lower smoothing. If the Smoothed value still jitters, raise smoothing or improve wiring/grounding.

Use level values in behavior

After a Range or Center level input is saved, its named slots become values that behavior rules can reference.

1. Go to Configuration > Behavior.
2. Add or edit the rule, transition, action, or sequence that should respond.
3. Choose the analog input or level input as the source.
4. Choose the named value produced by the Range or Center slot.
5. Save and test with the real prop.

Use labels that make the rule readable later. radio_station_3 is easier to audit than range_3.

Example: radio tuning dial

1. Add an analog input in Configuration > Connections > Inputs.
2. Name the input radio_dial.
3. Select the pin or channel wired to the potentiometer.
4. Save and confirm the live value changes when the knob turns.
5. Go to Configuration > Definitions > Level Inputs.
6. Add a Level Input Control.
7. Select radio_dial as the Input.
8. Choose Center mode.
9. Create one slot for each station, such as station_1, station_2, and station_3.
10. Turn the dial to each physical station position and use Learn Center for that slot.
11. Set Variance % wide enough that a player can find the station reliably.
12. Use the station labels in Behavior rules to trigger audio, lights, or solve state changes.

Example: pressure gauge zones

1. Add the sensor in Configuration > Connections > Inputs.
2. Name the input pressure_gauge.
3. Save and watch the Current and Smoothed values at rest and under pressure.
4. Go to Configuration > Definitions > Level Inputs.
5. Add a Level Input Control.
6. Select pressure_gauge as the Input.
7. Choose Range mode.
8. Add slots named low, safe, and high.
9. Use slot Min and Max values to define each zone.
10. Add tolerance so the reading does not bounce between adjacent zones.
11. Use the safe range in Behavior when the puzzle should pass.

Troubleshooting

Symptom	Likely cause	What to check
Level Inputs says no analog inputs are configured	The source was not created first	Add the analog source in Configuration > Connections > Inputs
Current value never changes	Wrong pin, wrong channel, wiring issue, or missing ground	Recheck the input source, wiring, and shared ground
Smoothed value changes too slowly	Smoothing is too high	Lower Smoothing %
Value jitters while untouched	Electrical noise or threshold too low	Improve wiring, keep Adaptive enabled, increase smoothing, or raise threshold
Correct target is hard to hit	Range is too narrow or center variance is too small	Widen the slot range or increase Variance %
Behavior cannot find the expected value	Slot names were not saved or the wrong mode was used	Save the Level Input Control and use Range or Center for named values