Skip to content

Sidereal (LST) and apparent-solar time-row modes#1

Closed
peterlewis wants to merge 1 commit into
astro-packfrom
sidereal-modes
Closed

Sidereal (LST) and apparent-solar time-row modes#1
peterlewis wants to merge 1 commit into
astro-packfrom
sidereal-modes

Conversation

@peterlewis

Copy link
Copy Markdown
Owner

Stacked on mitxela#6 (astro-pack) — review that first; this PR's own diff is just the sidereal/solar modes.

What this adds

Two opt-in time-row modes that turn the big HH:MM:SS digits into a live ticking clock in an alternate timebase:

  • MODE_LST — Local Sidereal Time (the astronomer's clock; a GPS-disciplined sidereal clock is the appeal).
  • MODE_SUNDIAL — local apparent solar time; reads exactly 12:00:00 at your meridian transit.

How it stays honest and leaves civil timekeeping untouched

It clones the existing MODE_COUNTDOWN takeover (new COUNT_ALT, four SysTick_Alt_Px handler clones). The heavy GMST/EoT double maths runs once per second in the main loop (thread context), staging pre-rendered 7-seg digits; the SysTick handlers latch them at the true PPS boundary via the untouched PPS() path. So:

  • civil currentTime, PPS discipline, calibrateRTC/write_rtc, and the date row are byte-identical to stock;
  • the setPrecision P3→P0 sub-second digit-hiding applies to sidereal unchanged (it degrades in lock-step with civil holdover because the reseed epoch is the disciplined currentTime);
  • no double-precision maths ever runs in an ISR.

The display is quantised to civil second boundaries and reseeded each second. Sidereal's 1.00273791× rate therefore makes the seconds display double-step about once every 6 min — deliberately visible, the authentic signature of a GPS-disciplined sidereal clock rather than a rate-warped one.

Not mistaking it for civil time

A dedicated colon animation (alt_colon_mode, default alt_sawtooth) marks the alternate modes and is automatically kept distinct from the civil colon unless explicitly matched — sundial especially can sit within minutes of civil. With no position (no fix, no fake_longitude) the row shows dashes; it never displays GMST-as-LST.

Maths

astro.c regains local_sidereal_time() / local_solar_time(), with the GMST series factored into one shared gmst_hours() helper (plus the +T² term so truncation stays sub-ms for decades). The native suite is 53/53, including the IAU GMST(J2000.0) anchor and Meeus Astronomical Algorithms example 12.b. UT1−UTC (DUT1, ±0.9 s) is the documented accuracy floor.

Default-off: without MODE_LST/MODE_SUNDIAL in config, no alt handler is ever installed and behaviour is identical to stock.

Status

Builds clean (arm-none-eabi-gcc -O3, zero warnings in changed code). Passed an adversarial review pass (ISR-safety, quantisation, mode-machine). Hardware validation pending — flagging as draft until watched on the device.

MODE_LST and MODE_SUNDIAL turn the big HH:MM:SS digits into a live ticking
Local Sidereal Time or apparent-solar ('sundial') clock. Both reuse the
COUNT_COUNTDOWN takeover pattern: the heavy GMST/EoT double maths runs once
per second in the main loop, staging pre-rendered digits that the SysTick
handlers latch at the true GPS PPS boundary -- so accuracy and the P3..P0
sub-second digit-hiding are inherited from the disciplined civil second, and
civil timekeeping (currentTime, PPS, the date row) is untouched.

The display is quantised to civil second boundaries and reseeded every second,
so sidereal's 1.00273791x rate makes the seconds double-step once every ~6 min
-- the honest signature of a GPS-disciplined sidereal clock rather than a
rate-warped one. A dedicated colon animation (alt_colon_mode, default
alt_sawtooth, kept distinct from the civil colon) marks the mode so it can
never be mistaken for civil time; sundial especially can sit within minutes of
it. With no position the row shows dashes -- never GMST-as-LST.

astro.c regains local_sidereal_time()/local_solar_time() with the GMST series
factored into one helper (gmst_hours, +T^2 term); native suite 53/53 incl. the
IAU J2000 anchor and Meeus example 12.b. All default-off: stock behaviour is
unchanged.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@peterlewis

Copy link
Copy Markdown
Owner Author

Superseded by mitxela#8 (draft, targets upstream). Branch kept for the clean stacked diff against astro-pack.

@peterlewis peterlewis closed this Jul 5, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant