12 KiB
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:
For how homing relates to startup trust/authority, also see
Quick Summary
There are three related but different ideas
- Return to home Move the mount to the configured home coordinates
- Sensed home Use home switches/sensors to find home
- 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?#returnshasSense,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
- Check the current home-sense state
- Choose an initial direction
- Slew until the sense state changes in the expected way
- Decelerate to a stop
- 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_FASTtoHOME_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_AUTOon 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
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.