docs: support-driven corrections and gap-filling

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.

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

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
 ----------------------------
 

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.
 

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.

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.

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

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