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
+420
View File
@@ -0,0 +1,420 @@
# PEC Notes
## Purpose
These notes describe how PEC currently works in OnStepX.
## PEC is one of the harder features to reason about because it combines
- persistent state
- a sampled correction table
- worm indexing
- tracking state
- guide interaction
- park/unpark interaction
## The implementation is concentrated mainly in
- `src/telescope/mount/pec/Pec.h`
- `src/telescope/mount/pec/Pec.cpp`
- `src/telescope/mount/pec/Pec.command.cpp`
## Quick Summary
## The clean mental model is
1. PEC stores one correction value per sidereal second of worm rotation
2. a worm index event establishes where the buffer starts
3. playback adds/subtracts a small tracking-rate correction each second
4. recording learns those per-second corrections from accumulated guide action
## So PEC in OnStepX is basically
- a one-second-slot correction table wrapped around the worm rotation
## What PEC Applies To
## Current mount PEC support is for
- axis1 only
Although the implementation and terminology are written around a worm cycle,
the correction model does not technically require a worm. It can also model
other repeatable geared error sources as long as:
- the cycle can be indexed
- the cycle length is stable
- the cycle period fits within the supported PEC limits/buffer size
## If `PEC_BUFFER_SIZE_LIMIT == 0` or `PEC_STEPS_PER_WORM_ROTATION == 0`
- PEC is effectively disabled
## The Main Stored Data
## PEC stores
- whether valid PEC data have been recorded
- current PEC state
- worm rotation length in steps
- the PEC correction buffer itself
The small settings live in normal NV settings storage.
## The correction table itself lives in a dedicated NV partition named
- `PEC`
## Important persistence detail
- changing or recording PEC data in RAM does not automatically write the PEC
table to NV
- writing the PEC table to NV only happens on explicit user command
## This is separate from PEC control state
- arming playback/record or disabling PEC updates the small PEC settings in NV
- but the actual correction table is only written by explicit save command
## That means
- after a recording session, the in-memory PEC table may differ from the
persisted PEC table
- if the user does not explicitly save the new data, a reboot comes back with
whatever PEC table was previously stored
## This is useful because
- a bad recording session can simply be abandoned by not saving it
## The PEC Buffer
The PEC buffer is not stored as one entry per motor step.
## Instead
- one entry represents one sidereal second of worm rotation
## That means
- buffer size in bytes is approximately worm rotation time in seconds
## Example
- if one worm rotation takes 720 sidereal seconds
- the PEC buffer has 720 entries
Each entry is an `int8_t` correction value.
So each second of worm rotation gets a small signed rate correction.
## How Worm Rotation Length Is Used
## The configured worm rotation length is stored as
- `PEC_STEPS_PER_WORM_ROTATION`
## PEC uses that to derive
- seconds per worm rotation
- buffer size
- current worm-rotation position from current axis1 motor steps
## So PEC fundamentally depends on
- knowing how many axis1 motor steps correspond to one worm rotation
## Two Ways PEC Gets Its Index
## PEC can work with
1. real sense input (`PEC_SENSE != OFF`)
2. virtual wraparound indexing (`PEC_SENSE == OFF`)
## With real sense input
- a sense event on `PEC_SENSE_PIN` defines the worm index
- PEC waits for enough worm travel before accepting another index
- this avoids repeated false retriggers too close together
## Without real sense input
- PEC treats worm rotation wraparound as a virtual index
## So
- hardware sense gives a stronger physical anchor
- no-sense PEC is still possible, but indexing is inferred
## How The Index Event Works
## When PEC sense is enabled
- the sense input is read through the shared `Sense` subsystem
- a valid ON transition after enough worm travel is treated as an index event
- the current axis1 motor step position becomes `wormSenseSteps`
- PEC marks that it has a valid worm reference
- playback buffer position can be realigned to that reference
## This is why the sensing note matters here too
- low-level sense filtering decides whether the PEC index input is ON
- PEC then adds its own motion/spacing logic before trusting that event as a
real index
## When PEC Is Active
PEC is only allowed to do real work when the mount is in an appropriate state.
## Main requirements
- the mount must be tracking
- guide state must not exceed pulse-guide style use
- the mount must not be parking or parked
## If those conditions are not true
- PEC disables recording
- PEC pauses playback
## Important distinction
- playback pause is not the same as losing PEC data
## If PEC was playing and the mount becomes ineligible
- state drops back to `PEC_READY_PLAY`
- playback can resume after re-indexing/alignment timing is right again
## The PEC State Machine
## Main states
- `PEC_NONE`
- `PEC_READY_PLAY`
- `PEC_PLAY`
- `PEC_READY_RECORD`
- `PEC_RECORD`
## Meaning
- `PEC_NONE`
PEC inactive
- `PEC_READY_PLAY`
user requested playback; PEC is waiting for the right timing/index position
- `PEC_PLAY`
PEC actively applying corrections
- `PEC_READY_RECORD`
user armed recording; PEC is waiting for the right timing/index position
- `PEC_RECORD`
PEC actively recording guide-derived corrections
## Why "Ready" States Exist
PEC does not jump into play or record at an arbitrary instant.
## Instead, it waits until
- the worm position is aligned to a one-second slot boundary
This makes the table alignment cleaner and keeps the one-second buffer indexing
consistent.
## So "ready" means
- the user has requested the action
- PEC is waiting for the correct phase/alignment to begin
## Playback
## During playback
- PEC advances the buffer index once per sidereal second
- it looks up the correction for the current worm segment
- it applies that as a fractional tracking-rate offset
## One subtle detail
- playback uses the correction from one second earlier than the current segment
The code comments describe this as a rough latency estimate between image
acquisition and response.
So PEC playback is intentionally shifted slightly ahead in effect.
## Recording
## During recording
- guide contribution on axis1 is accumulated
- once per sidereal second, that accumulated correction is quantized into a
small signed step value
- that value becomes the PEC table entry for the current buffer slot
## If this is not the first recording
- new data are blended with existing data using a weighted average
## So PEC recording is not just "write raw guide values directly." It is
- accumulate
- quantize per second
- optionally blend with existing data
## What "First Recording" Changes
## If this is the first time PEC is being recorded
- the new table is taken directly from current recording data
## If PEC data already exist
- new data are blended with the old table
That lets users refine an existing PEC table rather than always replacing it
from scratch.
## Cleanup After Recording
## When recording finishes
- PEC automatically switches to play
- the table is run through a cleanup pass
## Cleanup includes
- a low-pass smoothing pass
- a linear-regression style correction so the total sequence sums close to zero
That last part matters because PEC corrections should not create a long-term
net tracking bias over a whole worm cycle.
## If the cleanup result looks unreasonable
- PEC invalidates the recorded data
- PEC drops back to `PEC_NONE`
## Why The Sum Matters
A PEC table is supposed to redistribute tracking slightly over the worm cycle,
not permanently add or subtract motion over a full cycle.
## So after cleanup
- the total correction sequence should roughly cancel out
That is why PEC does a "reality check" on the residual sum.
## Park / Unpark Interaction
PEC interacts with park in an important way.
## When parking
- PEC is turned off
- the current worm sense position is saved into park settings
## When unparking/restoring
- that saved worm sense position is restored
## If a real `PEC_SENSE` input exists
- worm index truth is also recovered automatically once the worm rotates far
enough to detect the next valid PEC index event
So the restored saved position helps continuity immediately after unpark, while
the physical PEC sense can later re-anchor the index automatically on the next
cycle.
So park/unpark is part of how PEC continuity is maintained across a parked
interval.
This is another reason PEC is harder to reason about than a simple runtime
feature. It is not independent of park state.
## Examples
## Example 1: Playback with real worm index
- PEC data were previously recorded
- user enables PEC playback
- state becomes `PEC_READY_PLAY`
- mount tracks
- PEC waits for the right segment timing
- playback starts
- a later real PEC index event can realign buffer start
## Example 2: Recording new PEC data
- mount is tracking
- user arms PEC recording
- state becomes `PEC_READY_RECORD`
- at the right timing boundary PEC enters `PEC_RECORD`
- guide activity is accumulated into one-second corrections
- after one worm cycle, recording finishes
- cleanup runs
- PEC switches into playback
## Example 3: Mount stops tracking during playback
- PEC was in `PEC_PLAY`
- tracking stops or mount becomes ineligible
- PEC falls back to `PEC_READY_PLAY`
- rate goes to zero
- playback can later resume when conditions are valid again
## Commands
## There are several PEC commands, but the most important control ones are
- `:$QZ+#`
arm/enable playback
- `:$QZ-#`
disable PEC
- `:$QZ/#`
arm recording
- `:$QZZ#`
clear the PEC buffer
- `:$QZ!#`
save PEC data to NV
- `:$QZ?#`
get PEC status
## There are also read/write commands for
- table contents
- worm rotation steps
- buffer size
- current index location
## For the exact command list, see
- [COMMAND_REFERENCE.md](COMMAND_REFERENCE.md)
## Things That Make PEC Hard To Reason About
## PEC combines several different concerns at once
- mount motion state
- tracking state
- guide accumulation
- worm index sensing
- one-second slot timing
- persistent storage
- park/unpark continuity
That is why local code reading can still leave the feature feeling opaque.
## Good Mental Summary
## The most useful summary is
- PEC is a per-second correction table over one worm rotation
- indexing tells PEC where the table starts
- playback applies one correction slot each sidereal second
- recording learns those slots from guide activity
- cleanup makes the finished table smooth and net-neutral over the full cycle
If you keep that model in mind, the rest of the state machine becomes much
easier to follow.