515 lines
16 KiB
Markdown
515 lines
16 KiB
Markdown
# 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
|
||
|
|
|
||
|
|
- [STARTUP_AUTHORITY_NOTES.md](STARTUP_AUTHORITY_NOTES.md)
|
||
|
|
- [HOMING_NOTES.md](HOMING_NOTES.md)
|
||
|
|
- [COMMAND_REFERENCE.md](COMMAND_REFERENCE.md)
|
||
|
|
|
||
|
|
## Quick Summary
|
||
|
|
|
||
|
|
## The cleanest mental model is
|
||
|
|
|
||
|
|
1. a user target is turned into mount coordinates
|
||
|
|
2. the system checks whether that target is reachable in one or more valid
|
||
|
|
orientations
|
||
|
|
3. the system chooses a sensible branch and motion plan
|
||
|
|
4. goto executes that plan, possibly with waypoints or alternate orientation
|
||
|
|
handling
|
||
|
|
5. 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
|
||
|
|
|
||
|
|
1. make sure goto is allowed right now
|
||
|
|
2. convert the request into mount coordinates
|
||
|
|
3. decide which orientation options are valid
|
||
|
|
4. choose the actual target branch and pier side
|
||
|
|
5. add a waypoint/home step if needed
|
||
|
|
6. start the slew
|
||
|
|
7. 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 `ALTALT` forms 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_ONLY`
|
||
|
|
- `PSS_WEST_ONLY`
|
||
|
|
- `PSS_EAST`
|
||
|
|
- `PSS_WEST`
|
||
|
|
- `PSS_BEST`
|
||
|
|
- `PSS_AUTO`
|
||
|
|
- `PSS_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 `+360` or `-360` to 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_AVOID`
|
||
|
|
- `GG_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_START`
|
||
|
|
- `GG_NEAR_DESTINATION_WAIT`
|
||
|
|
- `GG_NEAR_DESTINATION`
|
||
|
|
- `GG_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 at `ALT = 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_AUTO` falls back to `PSS_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 `+360` or `-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.
|