init
This commit is contained in:
Executable
+401
@@ -0,0 +1,401 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user