Satellites and comets

weewx-celestial manual · weewx-celestial on GitHub · Report an issue

---

Satellites and comets are the two things on the Celestial page that you choose. Both are computed by weewx-skyfield and both live in weewx.conf, and each one takes the same three separate edits:

1. the [Skyfield] [[Satellites]] or [[Comets]] entry, which tells weewx-skyfield to track it,
2. its declared fields, which put it in the live feed — nineteen for a satellite, six for a comet, in the satellites or comets group of [StdReport] [[CelestialReport]] [[[LoopData]]] [[[[fields]]]] (see the Fields reference), and in the same group of any other report that names the panels it embeds (see Panels in your own skin),
3. a display name under [StdReport] [[Defaults]] [[[Almanac]]], so every report and the loop feed call it the same thing. (Display names reach the page on WeeWX 5.3 and later; on 5.2 the tag name itself is shown.)

The extension bundles a utility that makes all three in one command, one object per run, so the three cannot drift apart. (The second is also made by weectl extension install, which rebuilds the two groups for whatever [Skyfield] sets it finds — so a satellite added by hand per weewx-skyfield’s manual is declared on the next install, and the utility is the way to declare it now.) The skin itself needs no configuration: it enumerates whatever is configured.

Adding and removing satellites

source /home/weewx/weewx-venv/bin/activate
cd /home/weewx/bin    # the directory CONTAINING the `user` package
                      # (~/weewx-data/bin on pip installs)
python -m user.celestial --add-satellite zenit23088=23088 --name 'Zenit-2 23088' --config /home/weewx/weewx.conf --output /tmp/weewx.conf.new
git diff --no-index --word-diff /home/weewx/weewx.conf /tmp/weewx.conf.new   # review, then move into place

On a Debian or Red Hat package install there is no venv to activate, and WeeWX’s own code lives in /usr/share/weewx — on the path only inside weectl — so run from /etc/weewx/bin with a PYTHONPATH=/usr/share/weewx python3 prefix instead. The same goes for every python -m user.celestial command in this manual.

The tag (zenit23088 — a lowercase identifier of your choosing, refused if it shadows a body name the almanac already serves) becomes the satellite’s report tag and loop-field name; the number is its NORAD catalog number (search CelesTrak). --output writes a copy and never touches the original; --in-place edits weewx.conf directly after making a .bak-celestial-<version> backup (root-owned configurations need sudo for either the move or --in-place). Restart weewxd afterwards — it fetches the new satellite’s orbital elements soon after start.

Review with a word-diff. The satellites group is one very long comma-separated line, so a plain diff shows two unreadable lines and tells you nothing about what changed.

Every edit is independently idempotent, so any starting state converges: a satellite already configured per weewx-skyfield’s manual keeps its [[Satellites]] entry and gains the fields; re-running with a different number or --name updates that piece in place (the rename path); --name omitted leaves an existing name alone and merely prints the line to add later.

Keep the list short — each satellite is a separate CelesTrak fetch every three hours — and note that a satellite’s orbital inclination bounds the latitudes it can appear over, so a satellite configured for a station it never crosses will honestly report no passes for ever (weewx-skyfield’s manual has the details).

--remove-satellite zenit23088 is the exact inverse: it deletes the [[Satellites]] entry, the satellite’s declared fields (the group is rebuilt for the satellites that remain), and the display name — each if present, so removing an absent satellite is a no-op. Three things it deliberately leaves: the cached element file (wxskyfield_sat_<norad>.csv, or .tle from a weewx-skyfield before 2.10, beside the station database); any almanac.zenit23088.* entries on the legacy [LoopData] [[Include]] fields line, which the utility never edits and which weewx-loopdata will warn about at startup until the line is trimmed or retired; and — when you remove an installer default (iss, tiangong) — the knowledge that a future weewx-skyfield upgrade re-adds the [[Satellites]] entry, and the next weewx-celestial install then declares its fields again, so re-run the removal afterwards. The utility prints all three reminders.

Adding and removing comets

A comet is the same three edits — the [Skyfield] [[Comets]] entry (tag = MPC designation), six declared fields, the display name — and --add-comet makes them in one command, one comet per run:

python -m user.celestial --add-comet a3="C/2023 A3" --name 'Tsuchinshan-ATLAS' --config /home/weewx/weewx.conf --output /tmp/weewx.conf.new

The designation is the Minor Planet Center’s — a numbered periodic (1P, 220P) or provisional (C/2023 A3 — quote it, it has a space) designation, fragment suffixes allowed (C/1947 X1-B).

All comets ride one shared MPC element file, fetched every two days, so adding comets costs no extra downloads — but a comet the MPC has dropped serves no values, and the page renders it absent rather than inventing one.

Everything else works exactly like the satellite verbs: idempotent edits, --output/--in-place, the --remove-comet inverse, and the same installer-default warning (removing halley or hale_bopp wants re-running after a weewx-skyfield upgrade re-adds the [[Comets]] entry).

Satellites and comets share the almanac.<tag> namespace, so each family refuses the other’s tags — and both refuse body names. You cannot have a comet called iss.

What they look like on the page

A configured satellite gets a live marker on the sky dome, a row in each of the two satellite rosters, and a share of the pass countdown chip. A configured comet gets a diamond and tail on the Geocentric dial, a roster row between Neptune and Proxima, and a windowed perihelion chip. What each mark’s shape and brightness mean is in Reading the page.

Configure several and they fly together: the dome draws every satellite that is up, and each keeps its own pair of roster rows. Three overhead at once, on the morning of 18 August 2026 — the ISS climbing through the zenith, Tiangong crossing to the north, and NOAA-21 skimming the western horizon at four degrees.