402 lines
10 KiB
Markdown
402 lines
10 KiB
Markdown
# 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.
|