satpass

Amateur satellite pass predictor for field operators. Terminal-native, zero runtime dependencies, works offline. The "up, not out" companion to hfprop: where hfprop tells you which HF bands are open, satpass tells you which birds are workable and exactly when they come over the horizon.

Knowing when an amateur satellite is overhead is a comms capability that survives when terrestrial infrastructure is denied: FM voice repeaters (SO-50, PO-101), the ISS APRS digipeater, linear transponders for weak-signal work, store-and-forward. satpass turns a Raspberry Pi and a whip antenna into a schedule.

satpass // orbital intelligence for the light fighter  FN31PR  (41.729, -72.708)

NEXT PASSES  (next 24h, min el 10 deg)
SAT               AOS (local)      EL   AZ RISE->SET      DUR   VIS
SO-50 (SaudiSat  07-22 03:12:27   13  SSE->NE   11.2m  sun
SO-50 (SaudiSat  07-22 04:50:20   76  SW ->NNE  14.1m  sun
ISS (ZARYA)      07-22 06:14:08   48  NW ->SE   10.7m  EYE

Doctrine

• Zero runtime dependencies. Standard library only. No pip install to fail in the field, no supply chain. satpass carries its own SGP4 orbital propagator (src/satpass/sgp4.py), validated against the canonical Vallado reference vectors to sub-kilometer accuracy.
• Offline by default. Reach the network exactly once, on an explicit satpass tle --update. Everything else is computed locally from cached orbital elements. Predict passes for days with no signal.
• Runs on anything. Any Python 3.9+. Pi, salvaged laptop, phone in Termux.
• Pipe-friendly. --json on every command for scripting and mesh relay.

Install

pip install .
# or, without installing, run straight from a checkout:
python -m satpass --help

Optional Reticulum/mesh broadcast support:

pip install ".[reticulum]"

Quickstart

satpass grid FN31pr          # set your station (Maidenhead grid square)
satpass tle --update         # fetch amateur TLEs from Celestrak (needs a signal)
satpass now                  # what's above the horizon right now
satpass next --hours 24      # every workable pass in the next 24h
satpass passes ISS           # detailed pass list for one bird
satpass track SO-50          # live az/el + Doppler while you work a pass
satpass watch                # live monitor; beeps when a bird rises

After the one-time tle --update, everything runs offline.

Commands

Command	What it does
satpass now	Satellites above the horizon this instant: elevation, azimuth, range, Doppler, downlink freq.
satpass next [--hours N] [--min-elev D] [--sat NAME]	Upcoming passes across all tracked birds, sorted by rise time.
satpass passes <sat> [--hours N]	Detailed pass list for one satellite (name or NORAD number).
satpass track <sat>	Live pointing (az/el) and Doppler-corrected up/down frequencies during a pass, refreshed each second; counts down to the next AOS when the bird is below the horizon.
satpass sats	List tracked satellites with radio metadata and TLE age.
satpass tle [--update]	Refresh TLEs from Celestrak, or show cache status.
satpass grid [<locator>]	Set or show your station grid square.
satpass watch [--min-elev D]	Live monitor; terminal bell + alert on acquisition of signal.
satpass history [--days N]	Passes recorded while watching.

Global flags: --json (machine output), --grid LOCATOR (override station for one run), --offline (never touch the network).

The VIS column flags illumination: EYE = a visible pass (satellite sunlit, your sky dark) you could see with the naked eye; sun = sunlit but the sky is too bright; blank = the bird is in Earth's shadow. DOPPLER shows APPR (approaching, receive high) or RECD (receding, receive low).

How it works

satpass aggregates one data source and bundles one:

• Celestrak amateur-satellite TLE group (GROUP=amateur), fetched on tle --update and cached in SQLite.
• Bundled radio metadata (src/satpass/data/satellites.json): uplink, downlink, and mode for common workable birds, joined to live TLEs by NORAD catalog number. Frequencies are not in TLEs, so this is curated. Always confirm frequencies and transponder schedules against the AMSAT status page before an operation.

Pass geometry is computed by propagating each TLE with the vendored SGP4, rotating the result into an Earth-fixed frame by Greenwich sidereal time, and reading off topocentric azimuth/elevation/range from your grid square.

Scope and accuracy

• LEO only. satpass implements near-Earth SGP4. Deep-space objects (period >= 225 min) such as the QO-100 geostationary transponder or Molniya orbits are refused with a clear message. Every FM/linear amateur bird worked from the ground is LEO and in scope.
• Frame math omits polar motion and nutation and treats UTC as UT1. Pointing accuracy is far better than any handheld antenna needs.
• TLEs age. Predictions degrade past about a week; satpass warns you when the cache is stale. Refresh when you have a signal.
• Predictions are only as good as your clock. An off-grid board with no real-time clock or NTP can boot to a wrong time, which silently ruins every prediction. satpass checks the system clock against the newest TLE epoch and warns (on stderr) when it is provably wrong. Keep the clock set (GPS, RTC module, or NTP when you have a link).

Extending the satellite list

Add entries to src/satpass/data/satellites.json keyed by NORAD catalog number. A satellite with no metadata is still tracked from its TLE; it simply shows no frequencies. A metadata entry whose catalog number isn't in the TLE cache is harmlessly ignored.

License

MIT. The vendored SGP4 is reimplemented from the public references by David Vallado and Brandon Rhodes; see LICENSE.