Files

402 lines
10 KiB
Markdown
Raw Permalink Normal View History

2026-05-20 21:48:13 +02:00
# 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
## Related But Separate: `Button`
## There is a related helper in
- `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.