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

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

  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

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.