From 208f4eca39a53381b4c4f21f471a999aaf76d093 Mon Sep 17 00:00:00 2001 From: Richard Date: Tue, 22 Sep 2026 17:06:06 -0700 Subject: [PATCH] docs(user-guide): say which key confirms, and that SQUARE does not A first-night rev4 owner could not confirm a shutdown and kept landing in the help menu instead. The key list in "The Menu System" stopped at scroll and select, so nothing told him that RIGHT is the confirm key on a confirmation screen, or that SQUARE opens the Quick Menu rather than confirming. The Quick Start's alignment steps reinforced the wrong habit by presenting SQUARE as the key that "completes" a step. Expand the canonical key list in user_guide.rst with two bullets: RIGHT confirms and LEFT goes back on a confirmation screen, and SQUARE does not confirm. Mirror both bullets into the duplicate list in quick_start.rst. Link the list from the Shutdown section, and name the confirm key in both shutdown passages. Reframe the alignment steps so SQUARE reads as the screen's own start/save action, matching the START ALIGN and SAVE hints the screen draws. Also correct the shutdown wording: the power button emits its event only after a hold of more than a second, so the confirming press is a press and hold too, not a short press. Verified in code: keypad.KEYMAP/LONG_KEYMAP (joystick centre sends SQUARE, and LNG_SQUARE when held), menu_manager.key_long_square (Quick Menu), text_menu.key_right / key_power (Confirm-Cancel select, power acts as select on the shutdown menu), marking_menus.MarkingMenu (HELP is the UP option), keyboard_pi.run_keyboard (1s long-press and power thresholds), align.key_square and align_daytime.key_square (start, then save). Closes #647 Co-Authored-By: Claude Opus 5 (1M context) --- docs/source/quick_start.rst | 31 ++++++++++++++++++++++--------- docs/source/user_guide.rst | 27 ++++++++++++++++++--------- 2 files changed, 40 insertions(+), 18 deletions(-) diff --git a/docs/source/quick_start.rst b/docs/source/quick_start.rst index 3f6f5dff1..ca5c5c61f 100644 --- a/docs/source/quick_start.rst +++ b/docs/source/quick_start.rst @@ -147,6 +147,10 @@ between screens: - The **RIGHT** arrow selects the current menu item, which either sets an option or opens another menu - The **LEFT** arrow takes you back to the previous menu or screen - Press and hold **LEFT** for more than a second to jump back to the TOP of the menus +- **RIGHT** is also the confirm key. On a screen that asks you to confirm, such as the + shutdown screen, **RIGHT** selects the highlighted option and **LEFT** goes back +- **SQUARE** does not confirm. Press and hold it to open the Quick Menu, described below. A + short press does whatever the screen you're on uses it for Some menus, like the catalog selection, let you check several menu items on and off with the **RIGHT** arrow. @@ -515,7 +519,8 @@ Now align in a few steps: a planet. Point your telescope at it and roughly center it in your eyepiece. 2. Look at the PiFinder screen and find that star plotted there. Press the **+/-** keys to zoom out if it helps you identify it. -3. Press **SQUARE** to switch to star-selection mode. +3. Press **SQUARE** to start the alignment. The hint along the bottom of the screen reads + START ALIGN, and the screen switches to star-selection mode. .. image:: images/quick_start/align_start.png @@ -526,8 +531,9 @@ Now align in a few steps: 4. Use the arrow keys to highlight the star your telescope is pointing at, then return to the eyepiece and center it as well as you can. -5. Press **SQUARE** to complete the alignment. The PiFinder now places objects wherever in - your eyepiece that star sits. To exit without changing the alignment point, press **0**. +5. Press **SQUARE** to save the alignment. The hint now reads SAVE. The PiFinder then places + objects wherever in your eyepiece that star sits. To exit without changing the alignment + point, press **0**. .. image:: images/quick_start/align_done.png @@ -535,6 +541,9 @@ The marker returns to the normal Telrad-style reticle, showing your newly adjust point. The PiFinder saves it, so you don't need to repeat this unless you remove the PiFinder from your telescope and attach it again. +**SQUARE** starts and saves the alignment on this screen only. It is not a general confirm +key. On a screen that asks you to confirm, such as the shutdown screen, press **RIGHT**. + .. note:: You can also align on any catalog object. If you've found an object and it's not centered, center it up, press and hold **SQUARE** for one second, and select Align. This isn't like @@ -552,7 +561,8 @@ where the camera sees it, and mark that spot directly. .. image:: images/quick_start/align_day_start.png Opening the screen switches the camera to a short daytime exposure so you can see what it's -pointing at. Press **SQUARE** to begin. +pointing at. Press **SQUARE** to start the alignment. The hint along the bottom of the +screen reads START ALIGN. The view splits into four quadrants, labelled to match the keypad corners: **7** top-left, **9** top-right, **1** bottom-left, **3** bottom-right. Press the key for the quadrant your @@ -574,9 +584,11 @@ arrow press also leaves quadrant mode, so you can switch to fine adjustment at a .. image:: images/quick_start/align_day_fine.png Center your distant object in the eyepiece, move the marker onto it on screen, then press -**SQUARE** to save. Press **0** to exit without changing the alignment. Use something far -enough away that the focus matches the night sky, such as a distant treetop, chimney or -hilltop, rather than something across the room. +**SQUARE** to save the alignment. The hint now reads SAVE. Press **0** to exit without +changing the alignment. Use something far enough away that the focus matches the night sky, +such as a distant treetop, chimney or hilltop, rather than something across the room. + +**SQUARE** starts and saves the alignment on this screen. It is not a general confirm key. .. note:: In daylight the PiFinder shows the image in plain white rather than the usual red, since @@ -693,8 +705,9 @@ Shutting down the PiFinder A shutdown isn't strictly required before you turn the power off, but the PiFinder is a computer and skipping it risks file corruption. Press and hold the power button for about a -second. The screen asks you to confirm, and a second press shuts the PiFinder down and -turns it off. The :ref:`user_guide:shutdown` section walks through it with pictures, +second. The screen then asks you to confirm. Press and hold the power button again, or +press the **RIGHT** arrow. The PiFinder shuts down and turns itself off. **SQUARE** does +not confirm here. The :ref:`user_guide:shutdown` section walks through it with pictures, including the keypad route. .. note:: diff --git a/docs/source/user_guide.rst b/docs/source/user_guide.rst index ec610dad4..d53175ba8 100644 --- a/docs/source/user_guide.rst +++ b/docs/source/user_guide.rst @@ -66,9 +66,15 @@ options. Scroll through a menu and select items with these keys: - The **RIGHT** arrow selects the current menu item, which either sets an option or opens another menu - The **LEFT** arrow takes you back to the previous menu or screen - Press and hold **LEFT** for more than a second to jump back to the TOP of the menus +- **RIGHT** is also the confirm key. On a screen that asks you to confirm, such as + :ref:`user_guide:shutdown`, **RIGHT** selects the highlighted option and **LEFT** goes back +- **SQUARE** does not confirm. Press and hold it to open the :ref:`user_guide:quick menu`. + A short press does whatever the screen you're on uses it for, such as cycling through + extra information The arrows are the four directions of the joystick. Pressing the joystick straight in does -the same as the **SQUARE** key. +the same as the **SQUARE** key, and holding it in opens the Quick Menu. To confirm, press +**RIGHT**. .. note:: On v3 and v2.5 PiFinders the arrows are four separate buttons in a row along the bottom @@ -780,11 +786,11 @@ goes out once the screen and keypad come up. .. image:: images/quick_start/rev4_power.jpeg To shut down, press and hold the button again for about a second. The screen goes straight -to the shutdown confirmation. A second press confirms it, a tone plays, and the PiFinder -turns itself off once it has closed everything down safely. In normal use you never need to -cut the power by hand. If the software ever hangs and will not shut down, press and hold -**PWR** for more than 14 seconds to reset the power system. See -:ref:`troubleshooting:the pifinder won't turn on`. +to the shutdown confirmation. Press and hold the button once more to confirm, or press the +**RIGHT** arrow. A tone plays, and the PiFinder turns itself off once it has closed +everything down safely. In normal use you never need to cut the power by hand. If the +software ever hangs and will not shut down, press and hold **PWR** for more than 14 seconds +to reset the power system. See :ref:`troubleshooting:the pifinder won't turn on`. The menus get you to the same place if your hands are already on the keypad. See :ref:`user_guide:shutdown`. @@ -1301,9 +1307,12 @@ confirmation below appears from wherever you are. .. image:: images/quick_start/shutdown_confirm.png -Press the power button again, or the **RIGHT** arrow, to confirm. Press the **LEFT** arrow -to go back. The screen and keypad turn off within a few seconds, and the PiFinder turns -itself off. +Press and hold the power button again, or press the **RIGHT** arrow, to confirm. Press the +**LEFT** arrow to go back. The screen and keypad turn off within a few seconds, and the +PiFinder turns itself off. + +**SQUARE** does not confirm on this screen. Press and hold it and the Quick Menu opens +instead. For what each key does, see :ref:`user_guide:the menu system`. The keypad gets you to the same screen. The Tools menu offers a Shutdown menu item under Power, and the Quick Menu is faster: