Files
2026-05-20 21:48:13 +02:00

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.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

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.