Files
onstep/docs/SENSING_NOTES.md
2026-05-20 21:48:13 +02:00

10 KiB
Executable File

Sensing Notes

Purpose

These notes describe the shared sensing subsystem used across OnStepX for

  • home sense
  • limit sense
  • park sense
  • PEC sense
  • some local focuser/button-style inputs

The main reason this deserves its own note is that a "sense input" in OnStepX is not just a simple digital switch. The same general machinery supports:

  • ordinary digital active-high or active-low inputs
  • digital inputs with software time filtering
  • analog threshold sensing
  • analog hysteresis behavior
  • runtime inversion of the logical sense state

There is also a related but separate Button helper for more button-specific input behavior, including analog range comparison. That is covered near the end of this note.

Quick Summary

The simplest mental model is

  1. raw GPIO or analog input comes in
  2. Sense turns it into a normalized ON/OFF state
  3. higher-level code decides what ON/OFF means operationally

Examples

  • home code asks whether home sense is active/ON according to its configured HIGH/LOW meaning
  • limit code asks whether the min/max sense is ON
  • PEC asks whether the worm index sense is ON

The same low-level sensing code is reused in all of those cases.

Where The Shared Sense Code Lives

The main subsystem is

  • src/lib/sense/Sense.h
  • src/lib/sense/Sense.cpp

Main API

  • sense.add(...)
  • sense.isOn(...)
  • sense.changed(...)
  • sense.stableMillis(...)
  • sense.reverse(...)
  • sense.poll()

In most feature code, the higher-level subsystem does not read the GPIO pin directly. It registers a sense input once and then works with the normalized result through a sense handle.

How Sense Configuration Works

Each sense input is defined by

  • a pin
  • an init mode such as INPUT, INPUT_PULLUP, or INPUT_PULLDOWN
  • a packed trigger value

The packed trigger value normally combines pieces with |.

That is the usual configuration pattern.

Examples

  • HIGH
  • LOW
  • HIGH | HYST(20)
  • LOW | HYST(50)
  • HIGH | THLD(512)
  • LOW | THLD(300) | HYST(25)

Combining flags numerically with | is typically the intended style.

What The Trigger Encodes

The trigger value carries

  • the active state bit: HIGH or LOW
  • an optional analog threshold via THLD(v)
  • an optional hysteresis via HYST(v)

Important rule

  • if the threshold part is zero, the input is treated as digital
  • if the threshold part is nonzero, the input is treated as analog

So

  • HIGH | HYST(20) is still digital
  • LOW | THLD(400) | HYST(15) is analog

Digital Sense

Digital mode is used when there is no threshold component.

Behavior

  • raw input is read with digitalReadEx(pin)
  • HYST(n) is the required stable time in milliseconds before a digital state change is accepted
  • the new digital sample must remain unchanged for that long before the logical state changes

So in digital mode, HYST() does not mean an analog band. It means

  • how long the signal must stay stable before the change is accepted

Examples

  • HIGH active-high digital input, no extra filtering
  • LOW active-low digital input, no extra filtering
  • HIGH | HYST(10) active-high digital input, require about 10ms of stable state before the logical result changes
  • LOW | HYST(50) active-low digital input with heavier software debounce/noise filtering

This is useful for

  • switch debounce
  • modest EMI/RFI filtering
  • noisy digital inputs that should not chatter

Analog Sense

Analog mode is used when a threshold component is present.

Behavior

  • raw input is read with analogRead(...)
  • on ESP32, analogReadMilliVolts(...) is converted back into the common ANALOG_READ_RANGE scale for higher accuracy on this platform
  • the threshold and hysteresis act like a software Schmitt trigger

This means

  • if the sample rises above threshold + hysteresis, the logical value becomes HIGH
  • if the sample falls below threshold - hysteresis, the logical value becomes LOW
  • inside the band between those two thresholds, the last logical state is retained

That band is effectively a deadband zone

  • the signal can move around inside it without causing repeated state changes
  • a state change only happens after the signal leaves the deadband on one side or the other

Examples

  • HIGH | THLD(512) active-high analog threshold at mid-scale, no hysteresis band
  • LOW | THLD(300) | HYST(25) active-low analog threshold input with a hysteresis band around the threshold
  • HIGH | THLD(800) | HYST(50) active-high analog input that must move well above and below the threshold before changing state

This is useful when

  • a clean digital threshold is not available from hardware
  • analog noise would otherwise cause state chatter

Why Hysteresis Means Two Different Things

This is one of the easiest things to forget.

In digital mode

  • HYST(n) means time in milliseconds

In analog mode

  • HYST(n) means an analog hysteresis band around the threshold, creating a deadband zone where the current state is held

That dual meaning is intentional, but it is easy to misread in config.

What "ON" Means

The subsystem separates

  • the filtered internal logical value (HIGH or LOW)
  • whether that logical value counts as ON for the caller

sense.isOn(...) returns true when the filtered value matches the configured active state.

So

  • active-high means HIGH is considered ON
  • active-low means LOW is considered ON

This lets higher-level code work with

  • "is the home sense active?"
  • "is the limit sense active?"

without caring whether the hardware is electrically active-high or active-low.

Runtime Reversal

sense.reverse(handle, state) flips the interpretation at runtime.

This is different from the original config.

Config answers

  • what electrical state counts as active

Runtime reversal answers

  • should this sense be interpreted the opposite way right now

In practice this is used by code such as

  • Axis::setHomeReverse()

This is useful when the electrical truth stays the same but the motion logic needs the opposite interpretation.

Where Sense Is Used

Shared Sense users currently include

  • axis home sense
  • axis min/max limit sense
  • park sense
  • park signal monitoring
  • PEC worm index sense
  • local focuser sense inputs

That is why it is better to think of Sense as a general-purpose input normalization subsystem, not just "home switch code."

Example: Home Sense

Axis home sense is registered in Axis::init().

Important behavior

  • homing first checks whether home sense is already ON
  • if it is ON, motion first goes forward off the switch
  • if it is OFF, motion first goes reverse toward the switch

So home sense is not just an endpoint detector. It also affects the search direction and homing flow.

Typical home examples

  • AXIS1_SENSE_HOME HIGH simple active-high home switch
  • AXIS1_SENSE_HOME LOW | HYST(20) active-low home switch with digital debounce
  • AXIS1_SENSE_HOME HIGH | THLD(450) | HYST(20) analog thresholded home sense with hysteresis

Example: Limit Sense

Limit sense uses the same subsystem for min/max axis limits.

Runtime behavior

  • Axis::poll() updates the sensed limit flags
  • Limits::poll() reacts and stops the relevant motion direction

One important special case

  • min and max can share the same physical pin

By default

  • the axis notes this as commonMinMaxSense
  • the higher-level limit logic avoids treating one shared input as two separate independent events

Config option

  • LIMIT_SENSE_STRICT == ON disables that relaxation and treats shared min/max more strictly

Typical limit examples

  • LIMIT_SENSE LOW common active-low limit input
  • LIMIT_SENSE LOW | HYST(10) common active-low limit input with digital filtering

Example: Park Sense

Parking uses the same sensing framework for

  • PARK_SENSE
  • PARK_SIGNAL

Those are not special sensing implementations. They are just more clients of the shared normalized ON/OFF sensing subsystem.

Example: PEC Sense

PEC can also use the same shared Sense subsystem.

That means the PEC index input can also be

  • digital
  • analog thresholded
  • analog with hysteresis

Then PEC adds its own higher-level logic on top, such as only accepting a new index event after enough motion has occurred.

So

  • Sense decides whether the input is ON
  • PEC decides whether that ON transition counts as a valid worm index event

What Sense Does Not Do

The shared Sense subsystem does not implement every kind of analog input pattern.

In particular, it does not implement

  • "pressed when analog value lies within a range"

It is focused on

  • digital filtered ON/OFF sensing
  • analog threshold-plus-hysteresis ON/OFF sensing
  • src/lib/pushButton/PushButton.h
  • src/lib/pushButton/PushButton.cpp

That helper is more button-focused and adds behavior such as

  • press/release semantics
  • click and double-click detection
  • tone/frequency detection
  • analog threshold mode
  • analog range/value mode

That analog value/range mode is the "pseudo-digital using analog sampling and range comparison" behavior.

So if someone is looking for

  • analog value-in-range detection
  • button semantics
  • tone-style input behavior

they should usually look at Button, not Sense.

Practical Rules Of Thumb

If the input is a normal switch

  • start with plain HIGH or LOW

If the switch chatters or is noisy

  • add HYST(n) and remember that in digital mode it means milliseconds

If the input is fundamentally analog

  • use THLD(...)
  • add HYST(...) if you want Schmitt-trigger-like stability

If the meaning of the signal must flip at runtime

  • use runtime reversal rather than redefining the electrical config

Good Mental Summary

The cleanest way to think about sensing in OnStepX is

  • config defines how raw input should be interpreted
  • Sense turns that raw input into a stable ON/OFF result
  • higher-level features decide what ON/OFF means operationally

That separation is why the same low-level sensing subsystem can be reused for home, limits, park, PEC, and other features without each subsystem reinventing analog/digital input conditioning.