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

12 KiB
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
  1. 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
  1. 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
  1. 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