Navigation tools that work
with no signal at all

Open them on a phone, an iPad, or a laptop

The six tools — offline, installable, no account

Each is its own page with its own manifest and service worker, so each installs as a separate home-screen icon and caches itself on first load. Each one tells you on its own screen whether it is cached yet, rather than leaving you to guess.

• The launcher — a tile per tool.
• celnav — an altitude from a photograph of the sun or moon, and thirty-three lessons in nine modules that teach celestial navigation from first principles.
• colregs — lights and day shapes for 22 vessel types from any bearing, 28 encounter scenarios, sound signals that actually sound, fifteen lessons on the rules and seven on contact management, with the tracking party and Ekelund as exercises.
• tides — harmonic prediction for 8,334 stations: the day’s table, the curve, the moon and sun, and whether there is enough water.
• deck-log — the boat’s records, append-only in UTC, with the spares replayed from the log rather than stored.
• weather — your own barometer, reasoned over and shown working. It will not show you its forecast until yours is written down.
• drill — a study machine with no material in it. You load a pack from your own device; it is read in the browser and never leaves it.

They are not ports in the loose sense. Every lesson file and every data table is produced by running the awk engine’s own functions and capturing what they print rather than transcribed, and the test suite regenerates all of them on every run and compares them with what is committed — so a change to the shell that has not reached the browser fails at the desk rather than at sea. The shared arithmetic is held to the same standard: 21,264 comparisons for the rules of the road and 4,099 for contact management, against every awk on the machine.

The celestial engine was additionally diffed against the awk over 20,568 reference values when it was ported, and reproduces the shell tool’s own self-test against an independent reference ephemeris to 0.151′. The self-test runs on every suite run; that 20,568-row comparison was a one-off and its harness is not yet in the repository, which is a gap and is recorded as one.

To install one: in Safari, Share then Add to Home Screen; on a Mac, Add to Dock. Prove it once at the dock rather than at sea: open every screen, turn the network off, relaunch from the icon.

Design

Why it is built this way

Three constraints shaped both tools, and each one has a consequence worth knowing.

• It has to work when nothing else does. No internet, no app store, no almanac to buy, nothing that runs out at the end of the year. The almanac is computed from orbital theory built into the script.
• One file per tool. Each program carries its own engine inside it as text and writes it out on first run. Moving a tool to a new device is moving one file.
• The working is visible. Every intermediate value is printed. If an answer looks wrong you can see where it went wrong, and continue by hand from any line of the output. These are assistants, not black boxes.

Tool one

celnav — celestial navigation, offline

You give it a sextant altitude, a time and a rough position. It gives you a line of position, a fix, and every number in between.

• Sight reduction with the full working: GHA, declination, LHA, dip, refraction, parallax, semi-diameter, Hc, Zn, intercept.
• The fix by least squares from any number of sights, then re-reduced from its own answer until the position stops moving — so the intercept method's straight-line approximation never becomes a source of error, however far out your DR was.
• Running fix. Set course and speed and every line of position is advanced to the fix time for you.
• Sight planning: twilight times in UT and local, what is above the horizon, and the best three bodies to shoot.
• Fix geometry in miles, so a weak cut is named as weak before you steer on it.
• A deviation card from a swing. Give it the date, a body, your variation and a list of heading,time,bearing from swinging the ship, and it works the true bearing for each one and prints the card — celnav devcard. The same arithmetic for a single bearing is celnav compass.
• Latitude the direct way, with no fix at all: the noon sight at local apparent noon, and Polaris with its three corrections. And celnav table prints a Pub. 249 page, generated rather than scanned, with the entering arguments worked out for you.

Accuracy, measured rather than claimed

Checked against an independent high-precision ephemeris over 1990–2076, sampling every 11 days. The figures are total angular error in apparent position.

One arcminute is one nautical mile. The almanac contributes well under half a mile everywhere, which puts it comfortably below a good sextant observation from a small vessel — your instrument and your clock stay the limiting factors, as they should be. The fix arithmetic was checked separately against 200 randomised worldwide cases with exact synthetic sights: every one with sound geometry recovered the true position within 0.11 nm.

A note of caution: a phone camera is worth about two to three arcminutes once calibrated — the same order as a plastic lifeboat sextant, several times worse than a metal one in practised hands. Uncorrected lens distortion can cost tens of arcminutes, which is why the build carries a star-field calibration and says so on the page when it has not been done.

It teaches, as well as computes

Thirty-three lessons in nine modules from first principles, an annotated walkthrough of one real sight in ten steps, six kinds of drill generated from the real almanac and marked, and a sandbox where you change one number and watch the navigational triangle move. All of it is in the browser build too — the drills included, which means a drill is the same problem on either: a seed is the problem’s name, so red 4821 worked on deck can be checked at a terminal. And there the walkthrough’s three figures are the app’s own drawings rather than pictures of a terminal.

Tool two

colregs — the rules of the road

The lights are not drawings. Each one is described by its position on the vessel, its height, and its arc of visibility, and the program works out what you can see from where you are standing. Shoot her from astern and the masthead lights correctly disappear.

The same thing, as your terminal prints it

WHAT DO YOU SEE?
----------------------------------------------------------------------
masthead height
                                    R
                                    W
                                    :
                                    R
                                    :W
                                    ::
                                    ::
                                    ::
                               G    ::
                               :    ::
                               :    ::
                               :    ::
deck                           :    ::
                 =================================
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

----------------------------------------------------------------------
You are broad on her starboard bow.
Letters are the colours: W white  R red  G green  Y yellow

• Lights — twenty vessel types, drawable from any bearing.
• Day shapes — ball, diamond, cone, cylinder, and what each of them means.
• Encounters — a head-up plan view and the question that matters: who keeps out of the way, and what do you actually do. Fourteen scenarios, each with the rule that governs it.
• Sound signals drawn as timelines, since a script cannot make a noise.
• Fifteen lessons on the rules themselves, each ending with a question.

The same thing, as your terminal prints it

WHAT DO YOU DO?
----------------------------------------------------------------------
                         HEAD  UP
                       .................
                .......                 .......
             ....                             ....
          ...                                     ...
        ..                                           ..
      ...                                             ...
     ..                .................                ..
    ..              ...                 ...              ..
   .              ...                     ...    HER       .
  ..             ..                         .. \           ..
  .              .             ^             .  :           .
  .              .             |             ..  ::         .
  .              .            YOU            .     :        .
  ..             ..                         ..             ..
   .              ...                     ...              .
    ..              ...                 ...              ..
     ..                .................                ..
      ...                      .                      ...
        ..                                           ..
          ...                                     ...
             ....                             ....
                .......                 .......
                       .................

----------------------------------------------------------------------
You are a power-driven vessel under way.
You see a power-driven vessel showing her red sidelight, on your starboard beam, heading as drawn.
----------------------------------------------------------------------
 a) Stand on: she must keep clear of you.
 b) Give way: alter to starboard and pass under her stern.
 c) Give way: alter to port to cut across ahead of her.
 d) Slow down and let her decide.

Plotting a developing situation

The snapshot asks who gives way. This asks the harder question: is there a risk at all, how close will she come, and does your action actually open the distance? Three observations six minutes apart, with the scatter a hand bearing compass really gives you.

Tool three

tides — harmonic prediction, 8,334 stations

Not a downloaded table that expires. The harmonic constants are aboard, and the prediction is computed from them for any date, past or future, with no network.

• Every station in its own standard time, because that is how a tide table is read and how a harbour speaks. Converting them all to UTC would be tidier and wrong.
• Loose search. Type part of a name in any order — new lon finds New London — because nobody remembers a station’s full official name at 0400.
• The curve as well as the table, with the turns marked, so the shape of the day is visible rather than four numbers to interpolate between.

No tidal current data. NOAA has 4,430 current stations but United States waters only, and worldwide coverage is the point of the thing — so it is left out rather than offered for a quarter of the planet.

Tool four

deck-log — the boat’s records

The deck log, the engine, provisions and spares, in one book kept by one person at one moment. A watch stander says the report once; nobody says it three times at 0400.

• Append only, UTC, corrections as new records. The maritime convention is that you do not erase a log — you line through, initial and write the correction. A log has standing after an incident, and that cannot be retrofitted.
• Inventory is derived, never stored. The holding of any part is computed by replaying the log, so it cannot disagree with the log, because it is the log. A stored count is the obvious design and it is the one that drifts.
• Told at the moment of use. “That was your last one, one short of your minimum” — while you are still standing at the engine, not in a report afterwards.
• Four states, not two. A reading, a zero (which is a reading), asked-and-not-taken, and asked-and-not-observable. A form that punishes blanks gets invented numbers.

Tool five

weather — read your own barometer

With no network it cannot forecast. No GRIBs, no synoptic charts, no models. What it does is make you your own forecaster from the barometer, the sky and the wind — and it says so in its own about rather than implying otherwise.

Celestial is what you do when GPS dies. This is what you do when the sat comms die.

• It shows its working. Barometric tendency, backing and veering, Buys Ballot, the atmospheric tide correction applied before any statement about trend, swell as early warning, fog from dew point against sea temperature, cloud base from the spread.
• You forecast first. It shows nothing of its reasoning until your call is committed — otherwise you have not forecast anything, you have read an answer and agreed with it.
• Three scorers: you, the rules, and persistence. Persistence is the honest floor: a forecast that cannot beat “much as it is now” has shown no skill.

Tool six

drill — a study machine with nothing in it

Sections, recall practice, and a graded test that opens the next section when you pass it. What it does not have is any material: you load a content pack from your own device, it is read by the page, and it is kept in that browser’s own storage.

• Nothing leaves the device. No upload, no account, no network call — the file is read in the browser and stays there.
• Material somebody else owns can be studied without being published. The machine is published; what you study is yours and stays yours.
• A pack is one JSON file — sections with their reference text, and questions tagged to the section they belong to. The format is documented in docs/web/drill/README.md.

And a launcher

bashnav — one command in front of five

Pure sh, no awk, no network. It finds the tools next to itself, on the path, or in the place the operating system actually lets an app write, and puts a numbered list in front of them.

Detail

Colour, and night vision

Three modes, remembered between sessions: day, night, plain.

Night mode is deep red on black, with highlights in a brighter red, and contains no green at all. Rebuilding dark adaptation takes about twenty minutes, and a bright screen at 0300 costs you every one of them. Whatever colour marks the assumed position and the fix on the plot marks the matching symbol in the key underneath, so the legend reads as a colour match rather than a list.

Plain mode emits no escape sequences, and is selected automatically whenever output is not a terminal — so a redirected fix is always clean text.

celnav night
colregs night

Getting it

Install

Copy the file, make it executable, run it. That is the whole procedure.

git clone https://github.com/navigationtools/bashnav.git
cd bashnav
./bin/celnav doctor        # checks your awk, your clock, the data folder
./bin/colregs about

On macOS, Linux and the BSDs there is nothing to install — the system awk already has what the tools need.

On an iPad

Nothing to install. Open a tool above in Safari and add it to the home screen — no shell, no awk, no package manager, no gawk. That is the route this page leads with and the one to use.

The shell build does still run on an iPad, under a-Shell or iSH, which is worth knowing if you would rather have the tools at a prompt than as apps. a-Shell already carries an awk with the maths library. Under iSH only, the BusyBox awk is sometimes built without it, and apk add gawk inside iSH supplies one — apk is Alpine's package manager and exists nowhere else. celnav doctor says which you have and names the fix. iOS gives an app only its own sandbox to write in, so the tools keep their data under ~/Documents, the one place a-Shell can create files.

Documentation

celnav manual (PDF, 11 pages) · quick reference card (PDF) · source on GitHub

How it is checked

What the tests cover, and what they cannot

Two suites run on every change, under four awk implementations and two shells. They check the invariants — every drill marks its own correct answer as correct; every lights question has exactly one right answer, six hundred of them checked; the light tables satisfy Annex I wherever Annex I is geometry; a bearing drawing away from your bow never crosses ahead, four hundred fresh geometries a run; the almanac agrees with an independent reference ephemeris; three star sights from a known position resolve back to it. Alongside them, about twenty-six thousand lines of golden files capture every screen the tools can produce, so any change to what you see becomes a diff somebody has to accept on purpose.

None of that can tell you whether Rule 27 says what the program says it says. A test can check that a quiz marks answer C as correct; it cannot check that C is right. It can check that a light table is geometrically consistent; it cannot check that a mine clearance vessel shows those lights. Those are judgements against a document, and they need a person holding the document.

So if you are going to send one thing, send one of these — in the order of how much damage a wrong one would do:

1. Who gives way, and what to do. The twenty-eight encounters and the sixty-five distinct give-way calls the lights quiz can make. A wrong light table makes you misname a ship; a wrong verdict here makes you turn the wrong way. This logic was written backwards once during development and caught by a reader, not by a test. Rules 12–18.
2. The light tables. Twenty-two vessels, and every picture, question and answer is computed from them. Two errors have already been found — both by somebody looking at a picture, trying to account for every light in it, and failing. Rules 20–31 and Annex I.
3. The teaching. The lessons paraphrase the rules rather than quote them, and a paraphrase that is nearly right is worse than one that is obviously wrong.
4. Distractors that are also correct. The lights questions are proved to have a single right answer. The encounters are not — an option that is also defensible would mark you wrong for being right.
5. What is missing. No test notices an absent vessel, an absent rule, or an exception that goes unmentioned.

Both tools carry the same list: colregs about, then 3 and 5. A fix that disagrees with your own worked sight, or an almanac value that disagrees with a printed Nautical Almanac, is the most valuable thing you can send about celnav — it has been validated against a computed reference, never against the book.

The tool that stops teaching and asks to be taught

Everything above is an argument, and arguments are cheap. colregs review is the part that does something about it: 163 claims the tests cannot check, put to you one at a time, with the Convention open beside you.

colregs review          # then 1, “carry on from where I left off”

Each claim offers four answers — correct, wrong, or correct but with a comment, and skip. Both of the first two ask for one line about what is wrong. It remembers what you have already answered, so you can do ten claims and come back a week later. When you are done it builds a report and prints a link that opens a GitHub issue with the report already in it: the program never opens a socket, so nothing leaves your machine until you press return in your own browser.

The claims are generated from the same tables the code runs on, so the list cannot drift from the program, and they are ordered by how much damage a wrong one would do — encounter verdicts and give-way calls first, day shapes last.

It works, and the third answer is the one that earns its keep. The first run through it covered 36 of the 163 claims and found three faults: a scenario that said “you see” a fog signal you can only hear; a give-way call that told you to stand on against a vessel constrained by her draught; and a contact carrying two bearings that could contradict each other. All three came from claims marked correct, with a comment rather than from the ones flagged wrong — and each turned out wider than the claim that exposed it: one became two, one became nine, one became seven. The suite was passing 1,234 checks throughout.

Corrections to the astronomy are just as welcome and have no equivalent tool yet: celnav, tides and weather make claims a test can only check for self-consistency. Those go in an issue the ordinary way, and saying which source or edition you are working from is the most useful thing you can add.