421 lines
11 KiB
Markdown
Executable File
421 lines
11 KiB
Markdown
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.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.
|