This commit is contained in:
sagiferi
2026-05-20 21:48:13 +02:00
parent a907d8ba74
commit d3c13f997e
446 changed files with 70716 additions and 0 deletions
+366
View File
@@ -0,0 +1,366 @@
# 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