367 lines
12 KiB
Markdown
Executable File
367 lines
12 KiB
Markdown
Executable File
# Startup Authority And Coordinate Trust Notes
|
|
|
|
## Purpose
|
|
|
|
These notes describe how startup authority and coordinate trust currently work
|
|
for the mount, and how that affects automatic motion such as goto, sync,
|
|
park/unpark, and home/return.
|
|
|
|
## Core idea
|
|
|
|
The mount tracks a runtime trust state whose only question is:
|
|
"Do we trust the current coordinate basis enough for coordinate-based
|
|
automatic motion?"
|
|
|
|
If trust is true:
|
|
- coordinate-based automatic operations are allowed
|
|
|
|
If trust is false:
|
|
- coordinate-based automatic operations are blocked
|
|
- manual guide recovery is still allowed
|
|
- plain sidereal tracking is not gated by startup authority itself, but it may
|
|
still be blocked by other safety policy
|
|
|
|
## Two useful distinctions
|
|
|
|
1. Immediate startup authority
|
|
- trust is available immediately at boot from an already-available authority
|
|
source
|
|
|
|
2. Deferred startup authority
|
|
- boot starts untrusted
|
|
- an authoritative startup-time action later establishes trust
|
|
|
|
Date/time readiness is separate from both of the above.
|
|
|
|
Limit enforcement is related but separate too:
|
|
- startup authority answers whether the coordinate basis is trusted
|
|
- date/time readiness answers whether sky-referenced operation is ready
|
|
- limit enforcement can become active as soon as both are available
|
|
|
|
## What currently establishes trust
|
|
|
|
Trust can currently come from either immediate startup authority sources or
|
|
later authoritative actions.
|
|
|
|
Immediate startup authority sources:
|
|
- paired mount-axis absolute position sources at boot, with origin(s)
|
|
established
|
|
- trusted mount coordinate memory restore
|
|
|
|
Boot policy is selected by MOUNT_STARTUP_MODE.
|
|
Default:
|
|
- SA_AUTO
|
|
|
|
Modes:
|
|
- SA_STRICT:
|
|
boot stays untrusted unless an immediate startup authority source succeeds
|
|
- SA_AUTO:
|
|
if neither mount axis has an absolute position source and mount coordinate
|
|
memory is OFF, boot grants legacy session trust automatically
|
|
- SA_PERMISSIVE:
|
|
boot grants session trust automatically even when stricter authority sources
|
|
exist
|
|
|
|
Later authoritative actions:
|
|
- authoritative set-origin at a known home position
|
|
- authoritative reset at a known home position
|
|
- successful switch-based home
|
|
- SWS v2.10d or later hosting absolute encoders (for pointing correction)
|
|
|
|
Ordinary sync is not used to restore trust.
|
|
|
|
## What currently revokes trust
|
|
|
|
Trust is revoked conservatively when the system can no longer honestly assume
|
|
the coordinate basis is valid.
|
|
|
|
Currently implemented:
|
|
- motor/encoder fault
|
|
- NV fault (default behavior, because NV_INIT_ERROR_REVOKES_AUTHORITY defaults to ON)
|
|
|
|
Important non-revocation note:
|
|
- a motion stop caused by limits or StallGuard is not, by itself, a trust
|
|
revocation event
|
|
|
|
## What is blocked while untrusted
|
|
|
|
Blocked:
|
|
- goto
|
|
- set park
|
|
- park
|
|
- unpark
|
|
- normal sync
|
|
- home/return unless switch-based home is available
|
|
|
|
Allowed:
|
|
- manual guide
|
|
- plain sidereal tracking, subject to the normal tracking safety policy
|
|
|
|
Important tracking note:
|
|
- startup authority does not itself gate plain sidereal tracking
|
|
- however, tracking is still subject to other conditions such as parked state,
|
|
date/time-dependent enable rules, and limit policy
|
|
- by default, tracking is disallowed when limits are not enforced
|
|
|
|
## Parking workflow
|
|
|
|
Parking is part of the same trust model because park/set-park/unpark all depend
|
|
on the mount coordinate basis being believable.
|
|
|
|
While untrusted:
|
|
- set park is blocked
|
|
- park is blocked
|
|
- unpark/restore is blocked
|
|
|
|
Why:
|
|
- set park stores a coordinate-based reference that should not be accepted if
|
|
the current coordinate basis is already in doubt
|
|
- park and unpark are automatic coordinate-based motions, so they should follow
|
|
the same trust rules as goto
|
|
|
|
Operationally this means:
|
|
- a parked state is only useful if it was established from a trusted coordinate
|
|
basis
|
|
- unpark/restore is allowed when resuming from previously trusted parked state
|
|
- unpark/restore should not be thought of as a way to recover trust from unknown
|
|
state
|
|
- the legacy "unpark from home" exception is only allowed on simpler mounts; it
|
|
is disabled for SA_STRICT, for mounts using coordinate memory, and for mounts
|
|
with absolute position sources
|
|
|
|
## Workflow 1: Boot With Immediate Startup Authority
|
|
|
|
This is the cleanest startup path.
|
|
|
|
On these mounts, trust can be granted automatically at boot because the mount
|
|
already has an authoritative coordinate basis before any manual recovery is
|
|
needed.
|
|
|
|
Current immediate startup authority sources are:
|
|
- paired mount-axis absolute position sources
|
|
- trusted mount coordinate memory
|
|
|
|
## Workflow 1a: Boot With Paired Mount-Axis Absolute Coordinate Authority
|
|
|
|
This applies when:
|
|
- both mount axes report absolute position at startup
|
|
- the required encoder origin(s) are already established
|
|
- startup reset is therefore allowed to treat the mount-axis absolute readings
|
|
as authoritative for the initial coordinate basis
|
|
|
|
This is intentionally stricter than "one axis happens to be absolute."
|
|
For the mount axes, absolute coordinate authority is only valid as a paired
|
|
startup basis.
|
|
|
|
In practice this covers the supported mount-axis absolute-authority cases,
|
|
including:
|
|
- paired servo absolute encoders
|
|
- paired ODrive absolute-authority configuration
|
|
|
|
For runtime/NV origin storage:
|
|
- UINT32_MAX is used as the "origin not established" sentinel
|
|
|
|
Compile-time configured nonzero AXIS*_ENCODER_ORIGIN values are treated as
|
|
already established by configuration.
|
|
|
|
## Workflow 1b: Boot With Trusted Mount Coordinate Memory
|
|
|
|
Mount coordinate memory acts much like an "effective absolute startup source"
|
|
in the trust model:
|
|
- it can re-establish a coordinate basis at boot
|
|
- but only if the saved record is marked trusted
|
|
|
|
Important assumption:
|
|
- this depends on the mount being moved only by the drive system
|
|
- if clutches are present, they must not slip and must not be disengaged while
|
|
coordinate memory is being relied on as a startup authority source
|
|
|
|
Mount coordinate memory already uses:
|
|
- alternating A/B records
|
|
- CRC validation
|
|
|
|
It now also uses a trust bit:
|
|
- trusted records may restore authority
|
|
- untrusted records do not restore authority
|
|
|
|
This separates:
|
|
- storage validity
|
|
- semantic trust
|
|
|
|
So coordinate memory is not just "last known position storage." It is also a
|
|
startup authority source when, and only when, the saved record is trusted.
|
|
|
|
## Workflow 2: Boot Without Immediate Startup Authority
|
|
|
|
What happens here depends on MOUNT_STARTUP_MODE.
|
|
|
|
In SA_STRICT:
|
|
- if the mount has neither:
|
|
- paired mount-axis absolute position sources
|
|
- trusted mount coordinate memory
|
|
- trust is not granted automatically at startup
|
|
|
|
In SA_AUTO:
|
|
- if the mount has neither:
|
|
- paired mount-axis absolute position sources
|
|
- mount coordinate memory enabled
|
|
- boot grants legacy session trust automatically
|
|
- this preserves the long-standing "power up and goto" workflow on simpler
|
|
mounts
|
|
|
|
If mount coordinate memory is configured but the saved record is missing or
|
|
untrusted, SA_AUTO does not silently fall back to permissive trust. In that
|
|
case the system stays untrusted until an authoritative action succeeds.
|
|
|
|
In SA_PERMISSIVE:
|
|
- boot grants session trust automatically regardless of startup authority
|
|
sources
|
|
|
|
Current recovery model:
|
|
1. user manually guides to a known place if needed
|
|
2. user performs an authoritative action:
|
|
- set origin
|
|
- authoritative reset at a known home position
|
|
- successful switch-based home
|
|
- reboot with a valid startup authority source
|
|
3. trust becomes true again
|
|
|
|
Important practical consequence:
|
|
- the default SA_AUTO mode preserves permissive startup for simple mounts with
|
|
neither paired absolute position sources nor coordinate memory enabled
|
|
- SA_STRICT remains available for observatory and interlock-sensitive installs
|
|
|
|
## Workflow 3: Boot Untrusted, Then Establish Trust With Auto-Home
|
|
|
|
Auto-home with switches is best thought of as deferred startup authority.
|
|
|
|
It is not an immediate startup authority source.
|
|
Instead:
|
|
- boot begins untrusted
|
|
- switch-based home runs
|
|
- if successful, trust is established afterward
|
|
|
|
Switch-based home and auto-home-at-boot share the same sensed-home path.
|
|
|
|
Success:
|
|
- successful sensed home leads to authoritative reset
|
|
- trust is restored
|
|
|
|
Failure:
|
|
- coordinates are still reset for consistency
|
|
- failure is latched
|
|
- trust is not restored
|
|
- auto-home at boot does not continue as if homing succeeded
|
|
|
|
This behavior is intentionally consistent with normal switch-based return/home,
|
|
not just boot homing.
|
|
|
|
## Coordinate memory during homing
|
|
|
|
Important edge case:
|
|
when switch-based homing is in progress, mount coordinates are effectively
|
|
arbitrary relative to physical truth.
|
|
|
|
To prevent a power loss during homing from producing a misleading trusted
|
|
restore candidate:
|
|
- coordinate memory is marked untrusted as soon as switch-based homing starts
|
|
- periodic saves during HS_HOMING remain untrusted
|
|
- after successful authoritative homing, trust is restored normally
|
|
|
|
So if power is lost mid-home:
|
|
- the mount will come up with coordinate memory present but untrusted
|
|
- automatic coordinate-based motion will remain blocked
|
|
- the user can home/reset again, regain trust, and continue
|
|
|
|
## Workflow 4: Date/Time Not Ready
|
|
|
|
Date/time readiness and startup trust are related but not the same thing.
|
|
|
|
Trust answers:
|
|
- "Do we believe the coordinate basis is valid?"
|
|
|
|
Date/time answers:
|
|
- "Can we safely/usefully perform sky-referenced operations right now?"
|
|
|
|
So a mount may have trust while date/time is still not ready.
|
|
|
|
In that state:
|
|
- the coordinate basis may still be considered authoritative
|
|
- but some operations may remain postponed or blocked until date/time is ready
|
|
|
|
For mounts using trusted coordinate memory restore or trusted paired absolute
|
|
startup position:
|
|
- once date/time becomes ready, limit enforcement can be enabled immediately
|
|
- this does not require a later goto, reset/home, or unpark just to make
|
|
limits active
|
|
- that in turn allows tracking requests to succeed normally under the usual
|
|
limit-safety policy
|
|
|
|
Example:
|
|
- unpark recovery may wait for the normal site/time flow even when trust is
|
|
already valid
|
|
|
|
## Workflow 5: Losing Trust During Runtime
|
|
|
|
If trust is lost after startup:
|
|
- coordinate-based automatic motion stops being allowed
|
|
- manual guide recovery remains available
|
|
- sidereal tracking is still not gated by startup authority itself, but it
|
|
remains subject to the normal tracking safety policy
|
|
|
|
The guiding rule is:
|
|
- if the system knows where it is, coordinate-based automatic motion is allowed
|
|
- if it does not know where it is, coordinate-based automatic motion is blocked
|
|
- guide-based manual recovery remains available
|
|
|
|
## Important startup workflows to remember
|
|
|
|
1. Basic mount with clutches, no absolute encoders, no coordinate memory:
|
|
- common user workflow is manually place at home, power on, then goto/sync
|
|
- SA_AUTO preserves this by granting session trust at boot
|
|
- SA_STRICT intentionally blocks this until an authoritative action succeeds
|
|
|
|
2. Mount without coordinate memory and without clutches:
|
|
- mount may power up far from home
|
|
- user must guide back to home
|
|
- then perform an authoritative home/reset action
|
|
- then begin normal operation
|
|
- current model fits this workflow well
|
|
|
|
3. User wants only sidereal tracking at startup:
|
|
- trust does not gate sidereal tracking by itself
|
|
- but default safety behavior still disallows tracking when limits are not
|
|
enforced
|
|
- this is intentional and should remain so
|
|
|
|
## NV policy
|
|
|
|
The compile-time switch:
|
|
- NV_INIT_ERROR_REVOKES_AUTHORITY
|
|
|
|
Default:
|
|
- ON
|
|
|
|
Meaning:
|
|
- if NV reports an init/read fault that may undermine coordinate or motion
|
|
confidence, trust is not granted or is revoked
|
|
|
|
This is intentionally strict, but it has an escape hatch for expert use.
|
|
|
|
## Status exposure
|
|
|
|
The trust state is exposed in :Gu# so clients can detect it without extra
|
|
status calls.
|
|
|
|
Longer term, a small circular event log is probably a better place to record
|
|
why trust changed than trying to pack too much into live status.
|
|
|
|
## Open future work
|
|
|
|
- circular timestamped event log for trust loss/recovery reasons
|
|
- possibly record a simple trust-loss reason code
|
|
- maybe future fault-tolerant KV/partition design
|
|
- refine the basic clutch/manual-home startup case so normal users are not
|
|
surprised while still preserving the stricter safety model for systems with
|
|
stronger authority sources
|