11 KiB
Executable File
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.hsrc/telescope/mount/pec/Pec.cppsrc/telescope/mount/pec/Pec.command.cpp
Quick Summary
The clean mental model is
- PEC stores one correction value per sidereal second of worm rotation
- a worm index event establishes where the buffer starts
- playback adds/subtracts a small tracking-rate correction each second
- 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
- real sense input (
PEC_SENSE != OFF) - virtual wraparound indexing (
PEC_SENSE == OFF)
With real sense input
- a sense event on
PEC_SENSE_PINdefines 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
Sensesubsystem - 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_NONEPEC_READY_PLAYPEC_PLAYPEC_READY_RECORDPEC_RECORD
Meaning
PEC_NONEPEC inactivePEC_READY_PLAYuser requested playback; PEC is waiting for the right timing/index positionPEC_PLAYPEC actively applying correctionsPEC_READY_RECORDuser armed recording; PEC is waiting for the right timing/index positionPEC_RECORDPEC 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
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.