Astrolabe Plugin: Bringing the Sky Home
Building a local, offline astronomy engine for HomeSeer
The Sky, No Subscription Required
*Now in the HomeSeer store!
I’ve wanted to build this one for a very long time.
In fact, I’ve started it more than once over the years.
And stopped.
And started again.
And, on more than one occasion, looked at the mathematics involved and quietly found something else to work on.
Because the math gets intense very quickly.
To be fair, HomeSeer already calculates sunrise and sunset, and exposes both beautifully for events.
If all you want is:
Turn the outside lights on at sunset.
HomeSeer already has you covered.
There was nothing wrong with that.
I just wanted more.
A lot more.
I wanted civil, nautical, and astronomical twilight.
The actual positions of the Sun and Moon.
Moonrise and moonset.
Phase and illumination.
And once I decided to do those things, I wanted the calculations to be considerably more rigorous than what is necessary to decide when to turn on the porch light.
Not because HomeSeer’s sunrise needs replacing.
Because sunrise and sunset suddenly became just two answers produced by a much larger astronomical engine.
That was the plugin I had wanted to build for years.
Why it had so many false starts
Calculating approximate sunrise and sunset is one thing.
Building a general-purpose astronomical engine takes you somewhere else entirely.
Orbital theory.
Coordinate transformations.
Precession.
Nutation.
Aberration.
Parallax.
Topocentric corrections.
Iterative solvers.
Time scales.
And several other subjects remarkably good at turning:
“I think I’ll write an astronomy plugin.”
into:
“Perhaps I should reorganize the garage instead.”
So this project had a number of false starts.
But I never quite let go of it.
This time, I stuck with it.
And once the pieces finally started falling into place, I had an enormous amount of fun with it.
Possibly too much.
Because what began as:
“I’m finally going to calculate the Sun and Moon properly.”
rather quickly became:
“Well, now that I have that working, planets shouldn’t be too bad…”
Then came eclipses.
Then occultations.
Then satellites.
Meteor showers.
Observing conditions.
Astrology.
And several very enjoyable excursions into astronomical rabbit holes that were nowhere on the original project plan.
By that point, I had clearly lost control of the scope.
I was also having a great time.
Why calculate it locally at all?
There was another motivation.
A lot of “Sun and Moon” integrations are really weather or astronomy APIs wearing convenient hats.
They ask somebody else’s server for the answer.
Which means an account.
An API key.
A rate limit.
An Internet connection.
Eventually an outage.
And, if history is any guide, possibly one day an exciting email announcing the new pricing structure for access to your sunrise.
That has always struck me as a little silly.
Sunrise isn’t weather.
Where the Sun and Moon should be at a particular instant, from a particular location on Earth, is a solved mathematical problem.
The methods are published.
There is no inherent reason a computer somewhere else on the Internet needs to be involved.
So this plugin computes it.
Locally.
On your HomeSeer machine.
Offline.
For as long as the machine keeps running.
And once I had built the machinery to do that, stopping at sunrise and sunset seemed like a terrible waste.
A word about “accuracy”
I originally described the goal as complete accuracy.
Astronomy deserves a slightly more careful phrase than that.
The calculated geometry can be extremely precise.
The actual sky still gets a vote.
Observed sunrise and sunset, for example, depend partly on atmospheric refraction near the horizon.
Temperature and pressure matter.
Observer elevation matters.
A mountain on the horizon definitely matters.
The atmosphere is under no obligation to match the standard refraction model just because my equations would find that convenient.
So the goal here is not magical perfection.
It is:
Use serious astronomical models, apply the relevant corrections, avoid unnecessary approximations, and be honest about the physical limits of what can be predicted.
That is a standard I am much happier claiming.
The foundation
The solar and planetary calculations are based on VSOP87D, the Bureau des Longitudes analytical planetary theory.
The original VSOP87 data is large, and I was not about to manually transcribe astronomical coefficient tables into source code.
That would create an extraordinary number of opportunities to fat-finger a digit and introduce my least favorite sort of bug:
Everything works.
The answers look reasonable.
And the universe is very slightly wrong.
So the numerical tables used by the implementation are machine-generated into source from the published data, not retyped by hand.
That makes the process reproducible and, more importantly, removes me as a transcription device.
This also avoids overstating exactly how much of VSOP87D is represented by any one internal table. The full Earth VSOP87D series alone contains thousands of term records; what matters to the plugin is that its generated tables come from the published theory rather than from numbers copied by hand.
On top of the planetary solution sits nutation, the small periodic motion of Earth’s rotational axis.
The implementation uses the 106-term IAU 1980 nutation model.
That is an older standard, not the newest IAU precession-nutation model available today, and I want to be clear about that.
For this plugin’s purposes it provides far more precision than ordinary home automation requires, but “this is the model I use” is a much better claim than pretending astronomy stopped revising its standards in 1980.
Then come precession and the topocentric corrections needed to answer a surprisingly important question:
Not merely:
Where is that object?
But:
Where does it appear from this particular roof?
That distinction matters enormously once the Moon gets involved.
And it became the foundation for several things I had not originally planned to build.
What it can tell you
Naturally, there are the expected things:
Sunrise and sunset.
Civil twilight.
Nautical twilight.
Astronomical twilight.
Moonrise and moonset.
Moon phase and illumination.
It also provides the traditional full-Moon names, but with the astronomical rules behind them.
For example, the Harvest Moon is the full Moon nearest the September equinox.
It is not simply:
“Whatever full Moon happens in September.”
That sounds like a minor distinction until the nearest full Moon falls on the other side of the calendar boundary and a twelve-row lookup table confidently gets it wrong.
Then come the planets.
The plugin calculates planetary positions and searches for events actually worth knowing about:
Conjunctions.
Oppositions.
Greatest elongations.
That last one is especially useful for Mercury, because:
“Mercury exists tonight.”
and:
“Mercury might actually be worth trying to see tonight.”
are very different statements.
Underneath, several of these searches reduce to variations of the same numerical problem: find where an angular relationship reaches the condition or extremum we care about.
So the common machinery is reusable.
Adding another body should mean adding data and relationships, not inventing an entirely new universe of arithmetic.
That pleases the programmer in me enormously.
Eclipses
Both kinds.
The traditional route to precise local solar-eclipse circumstances often involves Besselian elements.
They are powerful and well established.
They are also involved enough that many applications either provide only global circumstances or work from precomputed eclipse data.
This plugin takes another route.
Once I already have accurate topocentric positions for the Sun and Moon, the local geometric question becomes wonderfully direct:
From where I am standing, do those two apparent discs overlap?
The difficult part is calculating where the discs actually appear to be.
Once that exists, the eclipse itself becomes geometry.
I rather like that.
Occultations
This one was an unexpected bonus.
An occultation happens when the Moon passes in front of another object, such as a planet or star.
Once the topocentric machinery and eclipse geometry existed, occultations came surprisingly cheaply.
From the geometry’s point of view, it is essentially the same family of question with a different pair of objects.
They are also one of the best demonstrations of why the observer’s actual location matters.
A lunar eclipse is visible across a huge portion of Earth.
An occultation can be a hit in one city and a clean miss in another.
The reason is lunar parallax.
Move the observer a significant distance across Earth and the Moon’s apparent position against the background stars moves with them.
That shift can approach a degree.
So an occultation can genuinely be:
Yes from here.
No from there.
There is also a wonderful bit of astronomical trivia hiding in this part:
Only four first-magnitude stars lie close enough to the ecliptic to be occulted by the Moon.
That is not a catalogue limitation.
That is just the sky being selective.
Satellite passes
Satellite tracking uses SGP4.
This is importantly different from the planetary calculations.
A TLE is not simply a timeless set of physical Keplerian orbital elements that can be dropped into any convenient two-body propagator.
The elements are fitted for use with the SGP4 model.
Use them with the wrong propagator and you can get an orbit that looks completely plausible and is simply wrong.
So the plugin uses the model the data was intended for.
But knowing that a satellite passes overhead is only the beginning.
The more useful question is:
Will I actually see it?
Several things have to line up.
The satellite has to be above your horizon.
Your sky needs to be dark enough.
And the satellite itself generally needs to be illuminated by the Sun.
A satellite, after all, is not normally a light.
It is a moving reflector.
So:
Above the horizon
does not necessarily mean:
visible.
That makes the observing calculation considerably more interesting.
Meteor showers
Meteor-shower information comes from the International Meteor Organization’s working information rather than pretending the plugin can derive everything from celestial mechanics.
That distinction matters.
The location of Mars can be calculated.
A meteor shower’s observed hourly rate cannot be generated from first principles by this plugin.
That is observational data.
People measure it.
Shower activity varies.
Some years are better than others.
So the plugin treats meteor-shower rates as reference information and says so.
I want a clear distinction between:
calculated astronomical state
and:
measured observational expectation.
They are both useful.
They are not the same kind of knowledge.
The part that turns information into advice
Most astronomy software is very good at answering:
Where is it?
I wanted one part of this plugin to answer a more practical question:
Should I bother going outside?
A meteor shower peaking at noon is not terribly useful to an observer.
A shower peaking at 2:00 AM under a bright full Moon may technically be happening, but the experience could be somewhat less spectacular than the calendar entry suggests.
The same shower on a moonless night, with the radiant high?
Now we’re talking.
The observing module combines things such as:
Darkness.
Moon interference.
Radiant altitude.
Event timing.
And, optionally, cloud cover.
So instead of only saying:
“There is an astronomical event.”
HomeSeer can get closer to saying:
“This one may actually be worth walking outside for.”
That is probably the part I wanted most.
And yes, there’s astrology
There is also an astrological surface:
Zodiacal positions.
Retrogrades.
The void-of-course Moon.
Planetary hours.
Lunar mansions.
The interesting part is that most of this required very little new astronomy.
A zodiacal position begins with an ecliptic longitude the plugin already has.
Retrograde motion is a statement about how apparent longitude is changing.
Void-of-course calculations begin with the Moon’s longitude and future angular relationships.
Planetary hours begin with actual local sunrise and sunset.
Lunar mansions divide or interpret the lunar position according to a particular traditional system.
The geometry underneath remains geometry.
What somebody believes that geometry means is a different question.
So the plugin calculates the underlying values and makes no claim that Mars being somewhere particular is responsible for anyone having a difficult Tuesday.
Where traditions use different conventions, I would rather expose that distinction than silently pick one and imply universal agreement.
The astronomy engine should provide the same actual Sun, Moon, and planetary positions regardless of which traditional interpretation somebody places on top of them.
No separate decorative astronomy.
The geometry is the geometry.
Interpretation belongs somewhere else.
Exactly one part uses the Internet
There is one network-connected module.
It ships disabled by default.
With it disabled, the plugin makes no outbound connection at all.
That module exists because there are two useful things that genuinely cannot be generated indefinitely from the observer’s coordinates and the clock.
Not because the mathematics is too difficult.
Because they depend on information about the physical world now.
Satellite orbital elements
You cannot derive the current orbit of the International Space Station forever from an eternal set of constants.
Atmospheric drag changes it.
The atmosphere itself changes.
The station is reboosted.
Thrusters fire.
Orbits evolve.
Someone has to observe the actual orbit and publish updated elements.
Those come from CelesTrak.
Clouds
And then there is perhaps the single most important variable in practical backyard astronomy:
Can I see the sky?
No amount of celestial mechanics can tell me in advance whether a cloud has decided to park itself directly in front of Saturn.
For that, the optional module uses Open-Meteo.
Cloud information feeds directly into the observing advice.
Because a perfect conjunction under solid overcast is not much of an observing opportunity.
It is a rumour.
When enabled, the network module fetches infrequently, caches its data, times out quickly, and fails quietly.
If the forecast is unavailable, the observing advice becomes less informed.
The astronomy does not stop working.
That is deliberate.
Which is really the point
Other than those observations of the changing physical world, the astronomy comes from:
Your coordinates.
The time.
Published astronomical models.
No astronomy account.
No astronomy API key.
No rate limit.
No outside service required to tell HomeSeer where Jupiter is.
No server somewhere that must remain commercially interesting for the Sun to keep rising.
And no future email informing me that astronomical twilight has moved to the Enterprise Plan.
The software may evolve.
The models may be refined.
I may decide to adopt newer astronomical standards as the plugin develops.
But the fundamental capability does not depend on someone continuing to provide an Internet service.
That matters to me.
What I want to add next
Space weather.
Solar flux.
The Kp index.
Solar-flare activity.
Auroral forecasts.
NOAA’s Space Weather Prediction Center publishes that information openly, and it fits the observing module beautifully.
The plugin already asks:
Is tonight worth going outside for?
It considers darkness.
The Moon.
Event timing.
And, when enabled, cloud cover.
An aurora alert is essentially the same practical question with another source of changing real-world information.
And unlike most astronomical events, a geomagnetic storm can provide some advance warning.
Which means HomeSeer could potentially tell you over dinner:
“Tonight might be worth going outside.”
Rather than letting you discover the following morning that apparently everybody else saw the aurora.
That part is not built yet.
I am writing it down here mostly so Future Me cannot pretend he forgot about it.