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

462 lines
12 KiB
Markdown
Executable File

# Homing Notes
## Purpose
These notes describe how mount homing currently works in OnStepX.
This is a workflow note, not a deep explanation of low-level input filtering.
For the shared sensing subsystem itself, see:
- [SENSING_NOTES.md](SENSING_NOTES.md)
## For how homing relates to startup trust/authority, also see
- [STARTUP_AUTHORITY_NOTES.md](STARTUP_AUTHORITY_NOTES.md)
## Quick Summary
## There are three related but different ideas
1. Return to home
Move the mount to the configured home coordinates
2. Sensed home
Use home switches/sensors to find home
3. Reset at home
Rebuild the coordinate basis from the known home position
Those are often used together, but they are not the same operation.
## The Main Entry Points
## The core mount home commands are
- `:hC#`
move to home
- `:hF#`
reset the mount at home / cold-start position
- `:hA0#` / `:hA1#`
disable/enable automatic home at boot
- `:hC1,R#` / `:hC2,R#`
toggle home-sense reversal for axis1/axis2
- `:hC1,n#` / `:hC2,n#`
set home sense offset in arc-seconds
## Status command
- `:h?#`
returns `hasSense,axis1Offset,axis2Offset`
## What "Home" Means
## The configured home position is derived from
- mount type
- configured home defaults
- site latitude where relevant
- optional sense offsets
- special geometry such as meridian-flip handling
That home position is refreshed by `Home::init()` and then returned through
`home.getPosition(...)`.
So "home" is not just a fixed pair of axis numbers. It is computed in context.
## It is also important to separate
- mount orientation
- coordinates assigned to that orientation
Without home switches, "home" is primarily a coordinate definition that the
system returns to or resets against. In that case, home is not independently
observed from hardware. It is whatever mount orientation the current coordinate
basis says corresponds to the home coordinates.
That means the practical truth about what mount orientation counts as "home"
can shift when the coordinate basis shifts.
## Examples
- an authoritative reset at home reassigns the coordinate basis
- sync/model/origin changes can improve accuracy by shifting how the system
maps mount orientation into coordinates
- after those changes, the home coordinates may correspond somewhat differently
to mount orientation than before
With home switches, the home procedure has a stronger mount-orientation anchor
because the system is observing a real sense event during homing.
## So it is best to think of home as
- a reference in coordinate space
that may or may not be strongly anchored to mount orientation depending on
whether home sensing is available.
## The Three Main Workflows
## Workflow 1: Return To Home Without Sensors
This is the simple "move to home coordinates" path.
## It happens when
- `home.request()` is called
- no home switches/sense inputs are configured
## Behavior
- goto must be available
- startup authority must already be trusted
- date and time must be ready
- the mount slews to the computed home coordinates
This is just motion to a known coordinate target. It does not establish truth
from hardware sensing.
## Workflow 2: Sensed Home
This is the switch/sensor-based path.
## It happens when
- `home.request()` is called
- home sense is available
## Behavior
- goto must be available
- if startup authority is not trusted, sensed home is still allowed because it
can establish trust
- the guide subsystem starts a special home-guiding mode
- each axis uses `autoSlewHome()` to find the home switch state
- the axis may first move off the switch or toward it depending on the current
sensed state
- the axis refines through fast/slow/fine homing stages
## If sensing succeeds
- `home.guideDone(true)` runs
- an authoritative reset is performed
- startup authority becomes trusted
## If sensing fails
- `home.guideDone(false)` runs
- a non-authoritative reset/recovery path is attempted
- the home operation is marked failed
## What The Axis Class Actually Does During Sensed Home
The mount-level home request is only part of the story. The detailed switch
search sequence lives down in the axis class.
Each relevant axis uses `Axis::autoSlewHome()`.
## The important sequence is
1. Check the current home-sense state
2. Choose an initial direction
3. Slew until the sense state changes in the expected way
4. Decelerate to a stop
5. Refine through additional slower passes
## More concretely
- if home sense is already ON, the axis first moves forward off the switch
- if home sense is OFF, the axis first moves reverse toward the switch
- when the sense state changes appropriately, the axis stops
- the homing stage advances from `HOME_FAST` to `HOME_SLOW`
- then usually to `HOME_FINE`
## During the refinement sequence
- the slew rate is reduced
- the axis repeats the search with tighter motion
- if the switch state is still not in the expected condition after the slow
pass, an approach correction path is used before the final fine pass
This is why sensed home is more than "drive until switch closes once." It is a
small staged search procedure implemented at the axis level.
## Timeout also matters
- if no explicit timeout is supplied, the axis derives one from the configured
home distance limit and slew rate
- if the search times out, the homing slew aborts
## Motion safety still applies
- motion errors abort homing
- motor faults abort homing
- common min/max sense conflicts can also abort the slew
## So the full sensed-home sequence is
- mount/home layer decides that sensed home should happen
- guide layer starts coordinated home-guiding
- axis layer performs the actual staged switch search
- home layer interprets success/failure and performs reset/recovery
## Workflow 3: Reset At Home
This is the coordinate-basis rebuild step.
## It happens through
- `home.reset(...)`
- `:hF#`
- startup reset logic
- successful sensed-home completion
## Behavior
- tracking is stopped
- tracking-rate offsets are cleared
- goto first-use state is reset
- motor positions are reset to zero where appropriate
- home instrument coordinates are written back
- nominal index positions are captured
- backlash and slow slew defaults are restored
## If the reset is authoritative
- startup trust is granted
## If it is not authoritative
- it does not grant trust by itself
## Authoritative vs Non-Authoritative Reset
This is one of the key distinctions.
## Authoritative reset means
- the software has a good reason to believe the home position being applied is
truly correct
## Examples
- successful sensed home
- startup reset using valid paired absolute authority
- explicit authoritative origin/home workflows
## Non-authoritative reset means
- coordinates are being reassigned to home, but the software is not treating
that as proof of truth
## This distinction matters because
- authoritative reset can establish startup trust
- non-authoritative reset cannot
## How Trust Interacts With Homing
Homing is one of the main bridges between untrusted and trusted state.
## Important rules
- plain return-to-home without sensors requires trust first
- sensed home can be used to regain trust
- authoritative reset grants trust
- non-authoritative reset does not
## There is also one permissive carveout
- in `SA_AUTO` on simple mounts with no absolute encoders and no coordinate
memory, home/reset is allowed to bypass the sync-limit style coordinate jump
restriction
That keeps older/simple mounts practical without weakening the stricter cases
globally.
## Auto Home At Boot
## If `automaticAtBoot` is enabled
- autostart requests home after boot
This shares the same sensed-home or return-home machinery as a normal home
request. It is not a separate home implementation.
## That means
- success behaves like normal homing success
- failure behaves like normal homing failure
- auto-home does not silently pretend success if the sensed-home flow fails
## No-Goto Behavior
## If `GOTO_FEATURE == OFF`
- home request is rejected
- reset/home-with-motion request is rejected
- sensed home through guide-home is also rejected
This is intentional.
## In no-goto builds
- there is no fast automatic slew/home capability
- home/return is not supposed to pretend to exist as a supported motion mode
## How Home Sense Offsets Work
Each mount axis can have a stored sense offset.
## These offsets mean
- the physical home sense event is not necessarily the final logical home
coordinate
## Typical use
- a switch is placed somewhere repeatable but not exactly at the desired final
home location
- the offset defines the difference between switch-detected home and desired
coordinate home
## Commands
- `:hC1,n#`
- `:hC2,n#`
## Examples
- `:hC1,120#`
set axis1 home offset to +120 arcsec
- `:hC2,-300#`
set axis2 home offset to -300 arcsec
## Two Offset Modes
The config option `MOUNT_HOME_AT_OFFSETS` changes how offsets are used.
## When `MOUNT_HOME_AT_OFFSETS == OFF`
- sensed home resets at the switch-derived home first
- then, if offsets are in use, the mount may perform a finishing move toward
the true home coordinates after the authoritative reset
## When `MOUNT_HOME_AT_OFFSETS == ON`
- offsets are folded directly into the computed home position
## So the difference is basically
- separate finishing move
vs
- home already means the offset-adjusted position
## Home Sense Reversal
Each axis can also reverse the meaning of its home sense input.
## Commands
- `:hC1,R#`
- `:hC2,R#`
This is layered on top of the usual home-sense logic and is applied through
`setReversal()`.
Axis1 also has a latitude-related reversal for equatorial mounts in the
southern hemisphere, so axis1 home sense behavior is slightly more subtle than
just a plain stored boolean.
## Examples
## Example 1: Simple mount, no home switches
- user powers on
- mount already has trusted startup authority or permissive `SA_AUTO`
- `:hC#` moves to home coordinates
- `:hF#` can reset at the home position
## Example 2: Mount with home switches
- user or autostart requests home
- guide-home uses switch sensing to find home
- successful sensed home performs authoritative reset
- trust is granted
## Example 3: Switch is repeatable but not exactly at desired home
- home sense is configured
- nonzero offsets are stored
- sensed home finds the switch
- reset establishes truth
- final coordinate home may be offset from the literal switch crossing
## Special Geometry Cases
Sector gear axis1 and tangent-arm axis2 are special.
In those cases, homing and reset do not always follow the plain "reset both
axes to zero and write home coordinates" pattern.
For these geometries, home is not only about returning to a meaningful
coordinate reference. It is also about resetting the mechanism so later gotos
and tracking have useful travel remaining inside the limited range.
## So on a sector gear or tangent-arm mount, homing is often better understood as
- mechanical re-baselining of the constrained axis
- restoring useful travel for later motion
- re-establishing the coordinate-to-mechanism relationship for that limited
range
Because of that, some of the ordinary coordinate-based prechecks are also less
meaningful here. On these mounts the code relaxes or skips parts of the normal
"how far are we from home in coordinates?" logic before sensed homing, because
operation is fundamentally constrained and often more manual.
## Instead
- origin/position handling is adjusted to fit the special axis geometry
- successful sensed home may set origin more directly for the special axis
So if behavior looks a little different on sector gear or tangent-arm mounts,
that is expected.
## Failure Modes
## Homing can fail because of
- goto disabled
- motion already active
- missing date/time for plain return-home
- distance-to-home outside the configured sensed-home search limit
- switch search timeout
- motion error or motor fault during homing
- reset failure after the home-search phase
The code tries to fail conservatively rather than pretending home succeeded.
## Relationship To Sensing
Homing depends heavily on the shared sensing subsystem, but that low-level
behavior is documented separately.
## If you need to understand
- how `HIGH | HYST(20)` is interpreted
- how analog threshold/hysteresis sensing works
- how runtime reversal works
## see
- [SENSING_NOTES.md](SENSING_NOTES.md)
## Good Mental Summary
## The cleanest summary is
- return-to-home is motion to a known coordinate target
- sensed home is a hardware-based search procedure
- reset-at-home rebuilds the coordinate basis
- authoritative homing/reset can establish startup trust
Those are related operations, but they are not interchangeable.