From b4fe668c450385902a53d70093a29a517e50d6e2 Mon Sep 17 00:00:00 2001 From: Richard Date: Mon, 10 Aug 2026 17:17:19 -0700 Subject: [PATCH] docs: support-driven corrections and gap-filling Works through the 2026-08-10 support review of docs/source. Corrections: - Rev4 Straight sits at 45 degrees, not straight back. The old wording read as "rev4 reproduces v3's straight-back geometry", which talks rear-focus telescope owners out of the configuration that suits them. - A rev4 takes the v3 - imx462 camera type. Said so in sd_card, troubleshooting and menu_map, using the literal menu strings. - Dropped the SkySafari version ranking. Stated the floor once, on the page's own requirements line: a paid version, 6 or later. - The dovetail foot is a single M5 bolt, and you don't take the PiFinder off the telescope to tighten it. - Observing reports run to 45C/110F, and that is a unit-level figure rather than a battery rating. - The web nav label is "Network Setup" in both the top bar and the mobile sidenav (python/views/base.html:19,30). The page contradicted itself. Equatorial platforms: An alt-az telescope on an EQ tracking platform stays in Alt/Az. The docs instructed those owners into Equatorial, which is the misconfiguration that makes corrections jump around. Fixed in the Object Details note and in the troubleshooting FAQ. Gaps: - New "Getting a GPS lock" section: ephemeris download, why "Sats seen/used 0/0" is not a progress bar, why power cycling restarts the wait, why a phone is not a comparison, and what the lock types mean. Cross-linked from the quick start and from a new "The GPS never locks" symptom. - catalogs: added Comets (CM) and Planets (PL), both of which need a GPS lock, plus the automatic MPC element refresh. Pointed at observing lists for "can I add my own objects?". - Sleep mode: only key presses hold the PiFinder awake. Motion wakes it but does not reset the timer, so polar alignment and slow slews dim the screen mid-task. - Documented the rev4 focus lock ring, including focusing under stars before locking it. - Equipment AFOV takes whole degrees; a decimal discards the eyepiece while still reporting "Eyepiece added". - Test Mode surfaced in the FAQ as the cloudy-night answer. Facts verified against source rather than carried over: sleep timer semantics (main.py PowerManager), lock type labels (ui/gpsstatus.py), catalog codes and planet list (catalogs.py, comets.py, de421), AFOV int() parse (server.py) and the nav labels (views/base.html). docs build: python -m sphinx -b html -n -q source -> zero warnings. Co-Authored-By: Claude Opus 5 (1M context) --- docs/source/catalogs.rst | 27 +++++++++++++ docs/source/connectivity.rst | 2 +- docs/source/equipment.rst | 6 +++ docs/source/menu_map.rst | 6 ++- docs/source/quick_start.rst | 41 +++++++++++++++---- docs/source/sd_card.rst | 6 ++- docs/source/skysafari.rst | 3 +- docs/source/troubleshooting.rst | 56 +++++++++++++++++++++---- docs/source/user_guide.rst | 72 ++++++++++++++++++++++++++++++--- 9 files changed, 192 insertions(+), 27 deletions(-) diff --git a/docs/source/catalogs.rst b/docs/source/catalogs.rst index 0c8060f86..0fad78741 100644 --- a/docs/source/catalogs.rst +++ b/docs/source/catalogs.rst @@ -11,6 +11,10 @@ entries to scroll. For those, use **Name Search** to jump to an object by its designation, or sort by **Nearest** to show the objects closest to where your telescope points. +To observe objects the PiFinder doesn't carry, build your own list rather than +adding a catalog. See :ref:`user_guide:observing lists` for importing a list as a +CSV file, and :ref:`user_guide:custom targets` for entering coordinates by hand. + Abl ---- The Abell Catalog of Planetary Nebulae (George O. Abell, 1966): 79 confirmed planetary nebulae. @@ -27,6 +31,20 @@ C ---------- Caldwell catalog +CM +---- +Comets. The PiFinder computes each comet's position from orbital elements +published by the Minor Planet Center. + +The catalog fills in once the PiFinder has a GPS lock, because a comet's position +depends on your time and place. Until then it appears empty. + +The PiFinder refreshes the orbital elements by itself. Whenever it starts up with +internet access in Client mode, it checks the Minor Planet Center for a newer set +and downloads it. There is no manual update to run. If you plan a night of comet +observing, turn the PiFinder on at home on WiFi for 15 to 20 minutes beforehand +so it can collect fresh elements. + Col ---------- 471 open clusters compiled by Swedish astronomer Per Collinder. @@ -59,6 +77,15 @@ NGC ---------- NGC 2000.0, The Complete New General Catalogue and Index Catalogue of Nebulae and Star Clusters by J.L.E. Dreyer (edited by R.W. Sinnott). +PL +---- +Mercury, Venus, Mars, Jupiter, Saturn, Uranus and Neptune, along with the Moon and +Pluto. The Sun is not included. The PiFinder computes their positions for the +moment you look, and updates them as the night goes on. + +The catalog fills in once the PiFinder has a GPS lock, because a planet's position +depends on your time and place. Until then it appears empty. + RDS ---- The RASC Double Stars Observing Program: 110 double stars visible from the northern hemisphere across many constellations. diff --git a/docs/source/connectivity.rst b/docs/source/connectivity.rst index a77f0b6f5..aae7bd3c0 100644 --- a/docs/source/connectivity.rst +++ b/docs/source/connectivity.rst @@ -92,7 +92,7 @@ Internet access, follow these steps: 1) Make sure the PiFinder is in Access Point mode 2) Connect your phone, tablet, or computer to the PiFinder's WiFi network called PiFinderAP 3) Open http://pifinder.local in your web browser -4) Click the 'Network' link in the top bar. On a smaller screen, click the three stacked horizontal lines in the upper-left corner and select 'Network'. +4) Click the 'Network Setup' link in the top bar. On a smaller screen, click the three stacked horizontal lines in the upper-left corner and select 'Network Setup'. .. image:: images/user_guide/pf_web_net0.png 5) When prompted, enter the password for your PiFinder. The default is ``solveit``. 6) Scroll down to the 'Wifi Networks' section and click the + button to add a network diff --git a/docs/source/equipment.rst b/docs/source/equipment.rst index f1d10adec..b1fd1cf75 100644 --- a/docs/source/equipment.rst +++ b/docs/source/equipment.rst @@ -26,6 +26,12 @@ field stop as well if you know it, because it gives a more precise field-of-view figure. Store as many of each as you like and switch between them as the night goes on. +.. important:: + Enter the apparent field of view as a whole number of degrees. Type 82, not + 82.5. A decimal here discards the eyepiece even though the page still reports + "Eyepiece added", so the eyepiece never appears in your list. Focal length and + field stop both accept decimals as normal. + Adding and editing your gear ---------------------------- diff --git a/docs/source/menu_map.rst b/docs/source/menu_map.rst index da2cfcc5c..ab20ad601 100644 --- a/docs/source/menu_map.rst +++ b/docs/source/menu_map.rst @@ -219,7 +219,8 @@ User Pref... have the buzzer. See :ref:`user_guide:sounds`. Sleep Time How long the PiFinder waits before power-save dims the screen. Values: - Off, 10s to 2m. + Off, 10s to 2m. Only key presses reset the timer. Moving the PiFinder + wakes it from sleep but does not keep it awake. Menu Anim Menu scrolling animation speed. Values: Off, Fast, Medium, Slow. Scroll Speed @@ -275,7 +276,8 @@ Advanced Rev4 Straight. Changing this restarts the PiFinder. Camera Type Which camera sensor your PiFinder has. - Values: v2 (imx477), v3 (imx296), v3 (imx462). + Values: v2 - imx477, v3 - imx296, v3 - imx462. A rev4 PiFinder takes + v3 - imx462. There is no separate rev4 entry, and that one is correct. GPS Settings Configure the GPS receiver. diff --git a/docs/source/quick_start.rst b/docs/source/quick_start.rst index 4b84834b9..b921878a1 100644 --- a/docs/source/quick_start.rst +++ b/docs/source/quick_start.rst @@ -217,7 +217,13 @@ rotated the body into: - **Rev4 Left**: the screen faces left, for a Dobsonian or Newtonian with the focuser on the left of the tube. - **Rev4 Right**: the screen faces right, for a focuser on the right. -- **Rev4 Straight**: the screen faces back, directly away from the camera. +- **Rev4 Straight**: the screen faces back, set at 45°. + +Straight suits a telescope you focus from the rear, such as a refractor or a +Schmidt-Cassegrain. The screen is angled rather than flat, so you read it from behind the +telescope, where you already stand to observe. This is why rev4 has no separate Flat +configuration. If the telescope sits above head height, or you point it very high, rotate +the body left or right instead. The screen is easier to read from the side. **AS Bloom** and **AS Heart** are the exceptions: they name a telescope rather than an orientation. You can order Analog Sky's Bloom and Heart with a PiFinder fully integrated @@ -247,9 +253,9 @@ Any mounting angle works, as long as the camera points where the telescope point still prefer it roughly level so the screen is easy to read. The dovetail is adjustable, so you can set a comfortable angle even if your finder shoe -isn't right at the top of the optical tube. Loosen the two dovetail screws, set the PiFinder -on your telescope, adjust the angle to suit, then remove it and tighten the two screws. -You're all set for a night of observing. +isn't right at the top of the optical tube. Loosen the single M5 bolt that holds the foot, +tilt the PiFinder to the angle that suits you, then tighten the bolt again. You're all set +for a night of observing. .. note:: * Mount the PiFinder so the camera has an unimpeded view of the sky. @@ -307,7 +313,10 @@ relies on the accelerometer. An 'X' means it hasn't worked out where it's pointi Leave the PiFinder on the GPS Status screen to speed up the lock. That screen turns the camera off, which reduces electromagnetic noise and helps the receiver see more - satellites. + satellites. "Sats seen/used" reads 0/0 for most of the wait, so don't read it as a + progress bar, and don't turn the PiFinder off and on again while you wait. That restarts + the process from the beginning. See :ref:`user_guide:getting a gps lock` for the full + picture. .. note:: No GPS, or don't want to wait for a lock? Enter your location and time by hand and @@ -328,9 +337,13 @@ brighter or dimmer than the screen, use **Key Bright** in the .. note:: After a while with no activity, the PiFinder dims the screen and slows its exposures, solving, and other processes to save battery and prevent glare at the eyepiece. The - default is 30 seconds. You can change it, or turn it off, in the + default is 30 seconds. You can change it, or turn it off, with Sleep Time in the :ref:`user_guide:settings menu`. Any key press, or moving the PiFinder, wakes it. + Only key presses keep it awake. Motion wakes the PiFinder, but it does not reset the + timer, so slow work at the telescope can dim the screen while you watch it. Set Sleep + Time to Off when that gets in the way. + Start with the Start menu ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -429,6 +442,16 @@ the camera icon. A solve takes a second or so to catch up with each change of t the icon always lags a little behind. The HFD readout responds much faster, and the technique is the same: a small turn, then a pause to let things settle. +A rev4 PiFinder has a lock ring on the lens. Once you are happy with focus, tighten the +ring against the lens holder by hand. The focus then holds through transport, so you do +not set it again every time you move the telescope. To change focus later, loosen the +ring, adjust, then tighten it again. + +Focus first, lock second. Your PiFinder is focused on the bench before it ships, which is +close but not the best it can do. Refine it here under real stars, chasing the lowest HFD, +and only then tighten the ring. Lock it straight out of the box and you lock in "pretty +good" rather than sharp. + .. note:: **Can’t get a plate solve?** The usual causes are simple. Make sure the lens cap is off @@ -574,7 +597,11 @@ switch between them. Under partially obstructed skies, or when a lock is just taking longer than you'd like, leave this screen active to boost the GPS signal by temporarily stopping the camera. Like most electronics, the camera generates electromagnetic noise that can drown out the faint -GPS satellite signals. +GPS satellite signals. The screen shows "Lock boost on" while it does this. + +A first lock takes several minutes, and the satellite counts stay at 0/0 for most of that +time. For what the counts and the lock types mean, and why a restart sets the wait back to +the start, see :ref:`user_guide:getting a gps lock`. Once a lock shows, press the **LEFT** arrow to go back to the menu. This turns the camera on again, and you're ready to find your first object. diff --git a/docs/source/sd_card.rst b/docs/source/sd_card.rst index 1d854e66e..ddfc74b13 100644 --- a/docs/source/sd_card.rst +++ b/docs/source/sd_card.rst @@ -143,8 +143,10 @@ of minutes. After swapping the card you usually need to set the **Camera Type** again. A freshly imaged card defaults to one sensor, and if it doesn't match your PiFinder the camera view is blank. From the main menu, select Settings, - scroll down to Advanced, then select Camera Type. The v3 sensors are - ``imx462`` and ``imx296``. Then **turn the PiFinder fully off and on again**, + scroll down to Advanced, then select Camera Type. A rev4 PiFinder takes + ``v3 - imx462``. There is no separate rev4 entry, and that one is correct. + The v3 sensors are ``v3 - imx462`` and ``v3 - imx296``, and older v2 cameras + are ``v2 - imx477``. Then **turn the PiFinder fully off and on again**, because a software restart alone won't apply the change. See :ref:`troubleshooting:the camera view is blank or black` for more. Re-check your WiFi settings too. They don't carry over to a freshly imaged card. diff --git a/docs/source/skysafari.rst b/docs/source/skysafari.rst index e141c9342..6e24e4cea 100644 --- a/docs/source/skysafari.rst +++ b/docs/source/skysafari.rst @@ -11,7 +11,7 @@ First, check that your phone or tablet is on the same network as the PiFinder. App Setup --------- -You need SkySafari Plus or Pro to connect. Set up a telescope profile in the Telescope section of the settings page: +You need a paid version of SkySafari to connect: Plus or Pro, version 6 or later. The free version has no telescope control. Set up a telescope profile in the Telescope section of the settings page: .. image:: images/SkySafari/IMG_4792.jpeg @@ -80,7 +80,6 @@ A few things are worth knowing about the connection: phone, tablet or computer, disconnect the first. * The PiFinder cannot connect to SkySafari and a GoTo mount at the same time. Use one or the other. -* SkySafari 5 Plus, 6, and 7 all work. Version 7 is the most reliable. .. note:: If the PiFinder enters power-save mode, it stops sending position updates. SkySafari then diff --git a/docs/source/troubleshooting.rst b/docs/source/troubleshooting.rst index 213e2e31d..69c5fb8be 100644 --- a/docs/source/troubleshooting.rst +++ b/docs/source/troubleshooting.rst @@ -98,8 +98,9 @@ If Align (Day) shows nothing whatsoever, the **Camera Type** setting probably do the camera in your PiFinder. - From the main menu, select Settings, scroll down to Advanced, then select Camera Type and - try a different option. The v3 sensors are ``imx462`` and ``imx296``. Older v2 cameras are - ``imx477``. Trying each one does no harm. + try a different option. A rev4 PiFinder takes ``v3 - imx462``. There is no separate rev4 + entry, and that one is correct. The v3 sensors are ``v3 - imx462`` and ``v3 - imx296``, + and older v2 cameras are ``v2 - imx477``. Trying each one does no harm. - **After changing Camera Type, turn the PiFinder fully off and on again.** A software restart alone does not apply it. - A software update can quietly reset this setting, so re-check it after you update. @@ -138,6 +139,34 @@ Work through these in order: **aperture must be fully open** for the PiFinder to see enough stars to solve. +The GPS never locks +------------------- + +A first lock takes several minutes, and often longer. The receiver has to download orbit +data from the satellites before it can fix a position, and that download runs at a fixed +slow rate whatever the sky is like. Most reports of a dead GPS turn out to be a wait that +was cut short. + +- **Open the Start menu and select GPS Status, then leave the PiFinder there.** The screen + turns the camera off to help the receiver, and shows **Lock boost on** while it does. +- **"Sats seen/used: 0/0" is not a progress bar.** It sits at 0/0 for most of the wait and + then climbs quickly near the end. +- **Don't turn the PiFinder off and on again to check.** A restart throws away the partial + download and starts over. Repeated restarts can stop a lock arriving at all. +- **Get the receiver under open sky.** It does not work indoors or under a roof. +- **Don't compare it with your phone.** Phones use assisted GPS over the mobile network, so + they lock in seconds. That comparison says nothing about your PiFinder or your sky. + +If you would rather not wait, enter your location and time by hand and start observing. See +:ref:`user_guide:place & time`. For what the lock types mean, see +:ref:`user_guide:getting a gps lock`. + +.. note:: + A GPS lock is not needed to focus, align, or push to objects once your location and time + are set. It is needed before the Planets and Comets catalogs fill in, because those + depend on your time and place. + + An object has "disappeared" from a list (for example, M45) ---------------------------------------------------------- @@ -190,6 +219,13 @@ all expected: Frequently Asked Questions -------------------------- +**It's cloudy. Can I still learn my way around?** + Yes. Test Mode solves a saved star image from disk and supplies a stand-in location, so + the PiFinder behaves as though it is pointed at the sky. You can explore the menus, + catalogs, filters and Push-To indoors. From the main menu, select Tools, then select Test + Mode. It stays on until you restart the PiFinder, and it blocks real observing while it + runs, so restart before you go out. + **Do I still need a finder scope or Telrad?** Not for finding objects. Once aligned to your telescope, the PiFinder replaces a traditional finder. A zero-power finder, such as a red dot or a Telrad, is handy for the @@ -251,11 +287,17 @@ Frequently Asked Questions **Can I use the PiFinder on an EQ mount?** Yes. The PiFinder works with any mount, and plate solving behaves the same whatever the mount type. Switch it to EQ mode in the :ref:`user_guide:settings menu` by setting - "Mount Type" to EQ, which presents Push-To distances in RA/Dec instead of Alt/Az. On - software 2.5.0 and earlier the accelerometer tracking doesn't work correctly in EQ mode, so - the Push-To numbers are unreliable while you move the telescope. Once you stop and the - camera solves, the correct distances appear. Version 2.6.0 and later support EQ mode - fully, with accelerometer tracking. + "Mount Type" to EQ, which presents Push-To distances in RA/Dec instead of Alt/Az. + + An equatorial *platform* is the exception. Leave "Mount Type" on Alt/Az when you put an + alt-az telescope, such as a Dobsonian, on a tracking platform. You still move the + telescope in altitude and azimuth, and the PiFinder corrects for the platform's rotation + on its own. Setting EQ mode there is what makes the Push-To corrections jump around. + + On software 2.5.0 and earlier the accelerometer tracking doesn't work correctly in EQ + mode, so the Push-To numbers are unreliable while you move the telescope. Once you stop + and the camera solves, the correct distances appear. Version 2.6.0 and later support EQ + mode fully, with accelerometer tracking. **Can I control my motorized (GoTo) mount with the PiFinder?** Not yet. This is in active development. It will rely on INDI support for your mount, so diff --git a/docs/source/user_guide.rst b/docs/source/user_guide.rst index 2cd140e00..243c9bb38 100644 --- a/docs/source/user_guide.rst +++ b/docs/source/user_guide.rst @@ -269,9 +269,13 @@ consulting the object image can make all the difference. .. note:: By default the Push-To arrows guide you in altitude and azimuth, the way an Alt/Az or - Dobsonian mount moves. On an equatorial mount or platform, set Mount Type to Equatorial - in the :ref:`user_guide:settings menu`. The guidance then switches to right ascension - and declination to match your mount's axes. + Dobsonian mount moves. On an equatorial mount, set Mount Type to Equatorial in the + :ref:`user_guide:settings menu`. The guidance then switches to right ascension and + declination to match your mount's axes. + + Leave Mount Type on Alt/Az if you use an alt-az telescope on an equatorial tracking + platform. You still move the telescope in altitude and azimuth, and the PiFinder + corrects for the platform's rotation on its own. The number in the upper right is the object's :ref:`contrast reserve `. It estimates how easily the object @@ -905,9 +909,10 @@ A few habits keep the cell healthy: - **Charge where you can keep an eye on it,** and not on or near anything flammable. Do not charge or leave the PiFinder in extreme heat. A closed car on a sunny day is the classic way to cook a battery. -- **Mind the temperature.** The PiFinder has been used from about -15°C (5°F) to 40°C - (100°F). Capacity drops in the cold, though the computer's own heat keeps the cell warm - enough to work in most conditions. Do not charge a battery that is below freezing. +- **Mind the temperature.** Observers report using the PiFinder from about -15°C (5°F) to + 45°C (110°F). That range describes the whole PiFinder in the field, not a separate + battery rating. Capacity drops in the cold, though the computer's own heat keeps the cell + warm enough to work in most conditions. Do not charge a battery that is below freezing. - **For long-term storage,** leave the cell partly charged rather than full or empty and keep it somewhere cool and dry. Top it up every few months so it does not discharge completely. - **Dispose of it responsibly.** Take a worn-out lithium battery to a battery-recycling @@ -1029,6 +1034,51 @@ discard what's set, if you'd rather start fresh or hand control back to GPS. signal. You can focus, align, browse objects, and push to them. The :ref:`user_guide:star chart` and Align screens also work before a GPS lock. +Getting a GPS lock +---------------------------------- + +The PiFinder's GPS receiver takes a few minutes to work out where it is. This is normal, +and it is the part of the first night that surprises people most. Knowing what the +receiver is doing saves you from chasing a fault that isn't there. + +Before it can fix a position, the receiver has to download orbit data from the satellites +themselves. That download runs at a slow, fixed rate, so it takes several minutes however +good your sky is. Expect longer after the PiFinder has been off for a while, or when you +have travelled a distance since the last session. Later nights at the same site are +quicker, because the PiFinder still holds usable data. + +Open the Start menu and select GPS Status to watch progress. That screen turns the camera +off, which cuts electrical noise and helps the receiver hear more satellites. It shows +**Lock boost on** while it does this. Leave the PiFinder on that screen and let it work. + +Four things are worth knowing while you wait: + +- **"Sats seen/used: 0/0" is not a progress bar.** It reads 0/0 for most of the wait and + then climbs quickly near the end. A long run of zeros does not mean the receiver has + failed or that the sky is blocked. +- **Leave the PiFinder on.** Turning it off and on again restarts the download from the + beginning. Rebooting every few minutes to check on it is the one reliable way to never + get a lock. +- **Your phone is not a fair comparison.** Phones use assisted GPS. They download the same + orbit data over the mobile network in seconds and already know roughly where they are. A + phone showing dozens of satellites next to your PiFinder tells you nothing about + conditions. +- **Give the receiver a clear view.** It needs open sky. Indoors, under a roof, or hard up + against a wall all slow it down or stop it. + +Once the fix arrives, the Lock Type on the GPS Status screen tells you how good it is: + +- **Accurate** is a 2D fix. It gives latitude and longitude without altitude. +- **Precise** is a 3D fix, which adds altitude. + +Both are plenty. The PiFinder only needs a rough position on Earth to point your telescope, +so a night that reads Accurate works exactly as well as one that reads Precise. **Limited** +and **Basic** appear before a full fix, while the receiver is still settling. + +.. note:: + You do not have to wait. If the sky is good and you would rather start observing, enter + your location and time by hand as described above. Everything works from there. + Update Software ------------------ @@ -1131,6 +1181,16 @@ the PiFinder solves again. slips while you work the adjusters quietly ruins the correction. On a platform, leave the telescope alone entirely and adjust only the platform. +.. note:: + Turn Sleep Time off before you start. Adjuster knobs move the telescope too slowly for + the motion sensor to notice, so the screen dims part way through an adjustment even + though you are working. Only key presses hold the PiFinder awake, and the longest sleep + delay is 2 minutes, so **Off** is the setting that suits this job. Sleep Time sits under + User Pref in the :ref:`user_guide:settings menu`. + + The same applies to a motorized mount at guide speed. A slow slew may not register as + motion, so the Push-To numbers appear to freeze and then jump when the PiFinder wakes. + .. image:: images/user_guide/polar_align_adjust_docs.png The top line summarises the measurement: the number of points used, the total sweep, and,