16 KiB
Executable File
Goto Notes
Purpose
These notes describe how goto, sync, orientation choice, and target-limit planning currently work in OnStepX.
This is a workflow note. It is meant to help explain how the system decides on a sensible motion plan, not to document every goto command.
For related topics also see
Quick Summary
The cleanest mental model is
- a user target is turned into mount coordinates
- the system checks whether that target is reachable in one or more valid orientations
- the system chooses a sensible branch and motion plan
- goto executes that plan, possibly with waypoints or alternate orientation handling
- runtime limits continue watching during the motion
So goto in OnStepX is not just
- convert coordinates
- slew there
It is more like a small decision engine.
The Main Distinction: Goto vs Sync
goTo.setTarget(...) is the common decision point for both goto and sync.
That means both operations share
- target conversion
- orientation selection
- reachability checks
- axis1 wrap/unwind correction
Then they diverge
- goto moves the mount to the chosen target
- sync keeps the current physical mount orientation and reassigns coordinates to match the chosen target
So sync is not a separate simpler target model. It reuses most of the same target-planning logic, then applies it as a coordinate reassignment instead of motion.
What A Goto Request Really Does
At a high level a goto request goes through these steps
- make sure goto is allowed right now
- convert the request into mount coordinates
- decide which orientation options are valid
- choose the actual target branch and pier side
- add a waypoint/home step if needed
- start the slew
- continue monitoring limits and refine near the destination
The important thing is that the target may have more than one valid representation.
Examples
- east-side vs west-side orientation on a GEM
- axis1 target plus or minus 360 degrees when wrapping/unlimited motion exists
- alternate orientation choices on mounts such as
ALTALT
Workflow 1: Entry Conditions
Before goto or sync can proceed, the mount checks a number of ordinary conditions:
- startup authority must already be trusted
- both axes must be enabled
- the mount must not be parked
- no other goto/guide/motion operation can already be active
- no goto-blocking limit/sense error can already exist
- no motor fault can already exist
For goto specifically, date/time readiness matters through the ordinary mount and limit logic as well.
In other words, goto is not treated as a way to escape unknown state.
Workflow 2: Converting The Target
The incoming target may start life in
- native coordinates
- mount coordinates
- equatorial, horizontal, or
ALTALTforms depending on mount type
The goto code converts as needed so the mount can reason about
- target hour angle / declination where applicable
- target altitude for horizon checks
- target instrument coordinates for each orientation choice
This is why the same sky target can still lead to more than one valid motion plan.
Workflow 3: Choosing Orientation
This is one of the core pieces.
OnStepX supports a family of orientation-selection policies
PSS_EAST_ONLYPSS_WEST_ONLYPSS_EASTPSS_WESTPSS_BESTPSS_AUTOPSS_SAME_ONLY
What these really mean
- some insist on one side only
- some prefer one side but can fall back to the other if needed
- some try to stay on the current side
- some ask the planner to choose what seems best
PSS_AUTO
This was added mainly to support automatic meridian-flip style behavior when the mount is in the meridian-overlap region and can legitimately continue tracking on the other side without interruption.
In that sense, AUTO is not just "pick something convenient." It is meant to
prefer the side/orientation that keeps the mount on a sensible continuing
tracking path when overlap allows it.
This is still not the same thing on every mount type.
For ordinary equatorial cases
- it usually picks a preferred side from current hour angle
- in overlap cases, that helps place the target on the side where tracking can continue unimpeded after the orientation change
For ALTAZM and ALTALT
- it falls back to
PSS_BEST
So AUTO is really an automatic orientation policy, not one fixed algorithm.
In practical terms, it is most at home on GEMs, especially imaging setups where
automatic meridian-flip style behavior is desirable. Compared with a fixed
preference such as PSS_EAST, PSS_AUTO is better at using meridian-overlap
freedom to end up on the side where tracking can keep going cleanly after the
change.
On fork mounts, the usual practical approach is often different. Users commonly
widen the meridian limits to allow much more freedom, then keep a fixed side
preference such as PSS_EAST or PSS_WEST for normal operation. If they want
the mount to use the other orientation, they typically change that preferred
side. Forks often do not need, and often should not do, automatic flip-style
behavior in the first place. So wide limits help create freedom, but the
selected side policy still drives whether the planner stays put or flips.
PSS_BEST
BEST is distance-aware.
It compares the reachable east- and west-orientation targets in instrument space and may choose the alternate orientation if that target is closer.
This is why OnStepX can sometimes choose what looks like a shortcut
- through the pole
- through an alternate valid orientation
- through a less-obvious wrapped branch
That behavior can look surprising, but it is intentional.
In practical terms, PSS_BEST is often attractive for visual use because it
can reduce unnecessary flips and choose the shorter or less awkward path. That
can make the mount feel nicer at the eyepiece even when it is not the same
choice an imaging workflow would prefer.
Workflow 4: Reachability And Target Unwinding
After a tentative target exists, Limits::validateTarget(...) checks whether
the target is reachable.
This includes
- altitude min/max
- east-side axis1 window
- west-side axis1 window
- meridian overlap limits for GEMs
- axis2 limits
These sketches help visualize why the same configured GEM limits can look different depending on which side of the pier the mount is currently using:
When east of the pier, the active limit window is interpreted against the east-side geometry shown above.
When west of the pier, the same ideas map onto the mirrored west-side geometry.
But there is another subtle step
- axis1 may be normalized by plus or minus 360 degrees to find a sensible branch
That means the planner does not necessarily use the raw first axis1 value that falls out of the transform.
Instead it may
- keep the current branch if it is already best
- unwind to a nearby branch if that is closer
- shift by
+360or-360to make the target fit the valid motion window
This is why a coordinate that "looks outside range" on first glance may still be reachable after normalization.
It is also why wrapped or effectively unlimited axes feel smarter than a simple "move to exactly this number" implementation.
What AXIS1_WRAP Changes
If AXIS1_WRAP == ON
- axis1 is configured with a 360-degree wrap
- its configured range becomes
-360 .. +360 - sync-threshold style coordinate-jump checks are bypassed
That does not mean the mount ignores all planning.
It means
- axis1 has a broader wrapped coordinate space to work in
- goto can choose a sensible branch in that larger space
This is most relevant on azimuth-like axes and other mounts where bounded
-180 .. +180 thinking is too restrictive.
Workflow 5: Waypoints And Home During Orientation Change
If an equatorial goto changes pier side and MFLIP_SKIP_HOME == OFF, OnStepX
does not always go straight to the final destination.
Instead it may
- insert a waypoint at home
- or insert an avoid waypoint first, then go to home, then continue
That is why the goto stage machine includes
GG_WAYPOINT_AVOIDGG_WAYPOINT_HOME- near-destination refine stages
- final destination
So a meridian flip or alternate-orientation goto is often a multi-stage motion, not one direct straight-line idea.
Horizon Avoidance
There are two different horizon-avoidance ideas in the goto system.
The first is path-shaping during side/orientation changes.
When a pier-side change is involved, goto may first route through
- about 4 hours HA
- or about 3 hours HA
before going home and then heading to the final target.
The reason is practical horizon avoidance
- some otherwise valid geometry would pass too low near the horizon during a flip or alternate-orientation transition
- low-latitude cases can make that especially awkward
So the planner uses a small detour heuristic rather than pretending all valid math paths are equally safe in practice.
The second is runtime rate shaping based on distance from the altitude limit.
There is a runtime slowdown heuristic
- in equatorial mode with
MOUNT_HORIZON_AVOIDANCE == ON - the axis frequencies are scaled down near the minimum altitude limit
- the amount of slowdown varies with distance from that limit
- the code decides whether to slow RA-like or Dec-like motion depending on whether declination is increasing or decreasing
This is best thought of as practical protective behavior, not pure geometry.
Workflow 6: Near Destination Refinement
Goto does not always drive directly to the literal final target at full intent.
Depending on encoder/tolerance context, it may
- slew to a near-destination first
- wait to settle
- refine in one or more additional stages
- then finish at the final destination
That final approach is not only about positional refinement. In practice, the near-destination exit can also be used to normalize backlash on arrival by finishing with a consistent last-direction approach instead of simply accepting whatever direction the earlier slew happened to end with.
This is why the code carries
GG_NEAR_DESTINATION_STARTGG_NEAR_DESTINATION_WAITGG_NEAR_DESTINATIONGG_DESTINATION
It is also why encoder presence changes behavior
- with suitable encoder/tolerance support, more refined near-target behavior is allowed
- during homing/parking or on simpler cases, that refinement can be reduced or skipped
Runtime Limits Are Not The Same As Target Validation
This is another important distinction.
Target validation answers
- "is this planned target/orientation allowed?"
Runtime limit monitoring answers
- "while the mount is moving or tracking, have we crossed something dangerous?"
Runtime checks include
- horizon / overhead limits
- meridian east/west limits
- axis min/max limits
- sensed min/max limits
Those runtime checks can
- stop one axis
- stop the whole mount
- abort goto
- trigger automatic meridian flip in some GEM tracking cases
So there are really two layers
- planned target acceptance
- live motion policing
Automatic Meridian Flip
If automatic meridian flip is enabled and the mount is tracking, some runtime limit crossings do not simply stop motion.
Instead the limit code may request a new goto to the current sky position on the opposite side:
- east-side request if currently west and beyond the west meridian limit
- west-side request if currently east and beyond the axis1 max side
So automatic meridian flip is implemented as
- a limit-triggered alternate-orientation goto
not as a separate completely different motion engine.
How Non-GEM Mounts Differ
For fork and alt/az style mounts, some axis-limit reasoning is based on shaft angles rather than GEM-style pier-side interpretation.
The limit code therefore sometimes normalizes the current axis1 position back into a "normal east-like" coordinate form before checking limits.
That is one reason the same target can feel simpler on some mounts and much more orientation-sensitive on others.
For fork mode specifically, this is why wide meridian limits are often used as
a practical way to increase motion freedom without constantly tripping a
side-change style decision. But wide limits are not the whole story. Orientation
selection still matters. In typical fork use, that usually means keeping
PSS_EAST or PSS_WEST fixed until the user intentionally changes it to get
the opposite orientation, even though the generous limit window would allow
more than one valid branch.
ALTALT And Other Less Common Modes
ALTALT is one of the modes that can seem obscure from the outside.
One useful way to picture it is by re-aiming the primary axis of a familiar equatorial mount.
- on a GEM, that axis points parallel to Earth's rotation axis
- on an
ALTAZM, that same idea would point the primary axis at the zenith - on an
ALTALT, the primary axis points north on the horizon atALT = 0
That is why ALTALT is not just "equatorial with funny numbers." It is a
different mount geometry with its own natural strengths and weak spots.
In practice this means
- target conversion differs
PSS_AUTOfalls back toPSS_BEST- tracking and motion behavior are not identical to GEM or ordinary alt/az
- the mount can move naturally through the zenith and celestial-pole regions
- it is therefore one of the most natural mount geometries for satellite tracking
- the field will still rotate even if the mount is otherwise tracking the general sky motion correctly
- the geometry is weakest for targets near due north or due south on the horizon
So it is better to think of ALTALT as another consumer of the same decision
framework, but with a different singularity pattern and a different relationship
between its primary axis and Earth's rotation.
Special Geometry: Sector Gear And Tangent Arm
Sector gear axis1 and tangent-arm axis2 are special enough that ordinary full range goto thinking does not always apply.
For these mounts
- target reachability is influenced by limited physical travel
- some checks are relaxed or specialized
- origin handling can matter more than wide-range coordinate elegance
So goto on these mounts is partly about
- choosing a useful target in a constrained motion envelope
not simply navigating a wide continuous axis range.
No-Goto Builds
If GOTO_FEATURE == OFF
- real automatic goto motion does not exist
- sync still reuses the target-selection logic
- the old fake-completion paths for home/park are intentionally gone
So this mode still benefits from
- coordinate planning
- orientation choice for sync-like operations
But it is not pretending to offer the full automatic motion planner.
Examples
Example 1: Ordinary GEM goto
- user asks for a sky target
- planner computes east and west solutions
- both may be reachable
- preferred side or best-distance logic chooses one
- goto may go directly, or through home if the side changes
Example 2: PIER_SIDE_BEST
- both orientations are valid
- alternate orientation is closer in instrument space
- planner chooses the alternate branch
- this can look like a shortcut through the pole or a less-obvious orientation
Example 3: Wrapped axis1
- raw target axis1 value is not ideal
- planner shifts by
+360or-360 - resulting branch is closer or simply the only valid one inside limits
Example 4: Horizon-avoidance flip
- side change is needed
- direct route would be too low near the horizon
- goto first detours to an avoid waypoint
- then goes home
- then continues to the final destination
Good Mental Summary
The cleanest way to think about goto in OnStepX is
- transforms produce candidate target representations
- limits decide which ones are reachable
- pier-side/orientation policy chooses among them
- wrap normalization may unwind coordinates into better branches
- waypoints and heuristics make the chosen path practical
- runtime limits keep watching after motion begins
So the goto system is best understood as
- a target-planning and motion-decision engine
not just a coordinate conversion followed by a slew.

