Appearance
muxen-sextant — Overview
muxen-sextant tells the boat where it is in the natural world. Given a GPS position and the time, it works out what the sun and moon are doing overhead, how far the compass needle is from true north, what the tide is doing at the nearby ports, and which stars are above the horizon — and publishes all of that on the boat's MQTT bus, once every few minutes.
That is what feeds the "environment" pages on the screens: sunrise and sunset, the twilight windows, the moon phase, the magnetic declination the chart plotter needs, the tide curve for the port you are heading for, and a night-sky planisphere.
The daemon has no user interface of its own and no controls. It reads two topics, computes, and publishes five topics. Nothing on the boat depends on it to navigate: it is an information service, not part of any control loop.
What it computes
| Report | Topic | Answers |
|---|---|---|
| Sun | sextant/sun | sunrise, sunset, transit, the three twilights, and where the sun is right now |
| Moon | sextant/moon | moonrise, moonset, transit, phase and its name, illuminated fraction, age, which side is lit and at what angle, days to the next new and full moon, its path across the sky |
| Magnetic | sextant/magnetic | magnetic declination, inclination and total field intensity at the boat's position |
| Tides | sextant/tides | for every tide station within a search radius: the current height, the next high and low water, the tidal coefficient, and a 36-hour curve |
| Sky map | sextant/skymap | the stars above the horizon, constellation stick figures, and the visible planets, as altitude and compass bearing |
All five are computed from the same two inputs: a latitude/longitude and a clock. There is no sensor, no CAN bus, and no external network service involved.
The problem it solves
Every one of these quantities is a function of where and when, and each one is a different piece of specialist arithmetic — spherical astronomy for the sun and moon, a spherical-harmonic field model for the declination, a harmonic tidal series per port. Computing them on a screen, in a browser, on every page load, means shipping three separate solvers and a tide database to every display on the boat.
muxen-sextant does the arithmetic once, on the Brain, and publishes plain JSON. A screen subscribes and draws. Adding a second screen costs nothing.
Where it sits
muxen-nmea2000 ──► MQTT nmea/navigation ──┐
MQTT nmea/datetime ──┴──► muxen-sextant ──► MQTT sextant/sun
(recompute on sextant/moon
drift or interval) sextant/magnetic
sextant/tides
sextant/skymap
│
▼
screens| It reads | From | Purpose |
|---|---|---|
nmea/navigation | MQTT | data.position.latitude and data.position.longitude |
nmea/datetime | MQTT | data.now — used only as a signal that the time source is alive |
/var/lib/muxen-sextant/WMM.COF | disk | World Magnetic Model coefficients |
/var/lib/muxen-sextant/tides.db | disk | tidal harmonics for 8117 stations |
| It writes | To | Purpose |
|---|---|---|
sextant/sun, sextant/moon, sextant/magnetic, sextant/tides, sextant/skymap | MQTT, retained, QoS 0 | the five reports |
app/sextant/info | MQTT, retained, QoS 1 | daemon info: version, online state, reports served |
Both input topics come from muxen-nmea2000. The daemon subscribes to exactly those two topics and to nothing else; besides its daemon info it publishes nothing else, opens no listening socket, and never writes to disk.
The clock it computes with is the Brain's system clock, not the time carried in nmea/datetime. That message is read for its presence, not its content — see Position and time. A Brain whose clock is wrong publishes confidently wrong sun and tide times.
When it recomputes
Not every second. A recompute is triggered by one of three things:
- the first position fix after startup;
- the position drifting more than
--recompute-drift-deg(default 1.25°) in latitude or longitude since the last recompute; --recompute-interval-min(default 15 minutes) having elapsed.
So the sun's altitude and azimuth on the screen are up to fifteen minutes old, by design. Rise and set times, the declination and the tide curve do not change meaningfully on that timescale; the live position of the sun does, and that is the one number in the payloads that is a snapshot rather than a prediction.
The tides report carries a second throttle of its own (--tide-recompute-min, default 30 minutes) because a 36-hour curve for every station within 50 nautical miles is the expensive part of the work.
Position and time covers the full rule, including what happens when the GPS fix is lost.
Accuracy and expiry, in one paragraph
The sun and moon come from libnova and are good to about a minute for rise and set at latitudes within roughly ±72°. The magnetic model is WMM2025, whose nominal validity ends on 1 January 2030 — through 2030 the daemon computes but warns, and from 2 January 2031 it refuses, at which point sextant/magnetic simply stops being published. The tide heights are not referenced to a chart datum: they oscillate about zero, so a negative height is normal and the absolute number cannot be compared with a tide table. Each of those has its own chapter, and each of them matters more than the decimal places suggest.
What it is not
- It is not a navigation instrument. Nothing it publishes is certified, and the tide heights in particular are not soundings. Paper and official tide tables remain the reference for pilotage.
- It holds no state beyond the last computed values in memory. Stop it and the retained MQTT messages are the only thing left.
- It never writes to the boat: no CAN frames, no commands, no configuration changes.
Document map
| Document | Content |
|---|---|
| Getting started | install, start, verify, first payloads |
| Position and time | the two inputs, the recompute rule, fix loss, the clock |
| Sun and moon | the sun and moon reports field by field |
| Magnetic declination | the WMM report, its accuracy and its expiry date |
| Tides | stations, heights, coefficient, curve, and the datum caveat |
| Sky map | the star catalogue, constellations and planets |
| Troubleshooting | symptom → cause → check → fix, plus FAQ and Tips |
| Reference | CLI, defaults, MQTT topics, files, unit, packages, exit status |