docs: rev4 screen, joystick, and 'Which PiFinder do I have?' (WP3) - #575
Merged
Conversation
Bring the screen/keypad half of the manual in line with rev4 (WP3 of the rev4 docs plan). - New "Which PiFinder do I have?" section in the Quick Start, identifying a unit by the two things visible without opening it: the directional control (one joystick on rev4, four arrow buttons on v3/v2.5) and the screen. - Version notes on index, quick_start, user_guide and troubleshooting now name rev4 and link to that section. - Introduce the joystick once, in Unboxing, including the centre press as a second route to SQUARE. Key names are unchanged, so the rest of the prose stands as written. - Configuration Setup now covers all ten PiFinder Type entries, including the five rev4 ones, and says how to pick. AS Bloom and AS Heart are Analog Sky telescopes that can be ordered with an integrated PiFinder. - Note rev4's much wider dimming range in the brightness passage. TODO(rich) markers flag the rev4 photos that only Rich can shoot. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Rich confirmed the rev4 card is reachable from outside the case in a spring-loaded side slot, where v3 and v2.5 keep it behind three screws. That is a third unmissable external difference, so it joins the joystick and the screen in "Which PiFinder do I have?". The card-swap procedure itself belongs in sd_card.rst and is deliberately not described here. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…parison Re-taken at 176 px per D3 rule 3, in the sections this branch edits: - pifinder_type_select.png now shows the five rev4 entries (AS Bloom, AS Heart, Rev4 Left/Right/Straight) that the new prose describes. - settings_menu_config.png was stale as well as small: it showed PiFinder Type sitting directly in the Settings menu, where the surrounding prose has long said Settings -> Advanced -> PiFinder Type. It is now the Advanced menu. - settings_select.png re-taken unchanged in composition. New: main_menu_rev4_docs.png (176 px) and main_menu_v3_docs.png (128 px) -- the same main menu on each panel, side by side in "Which PiFinder do I have?". The 128 px capture is deliberate: it is illustrating v3/v2.5 hardware. The screen paragraph now says what those two captures actually show rather than quoting a menu-row capacity that no real menu displays. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
brickbots
marked this pull request as ready for review
August 7, 2026 21:57
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
WP3 of the rev4 documentation update (
rev4-docs-update-plan.md§4). Screen, keypad, and a new"Which PiFinder do I have?" section. Docs only — no code, no
menu_map.rst, nobuild_guide.rst/BOM.rst.Sibling packages: WP1 (power & charging), WP2 (sound/Volume), WP4 (bring-up page). This PR shares
quick_start.rstwith WP1 anduser_guide.rstwith WP1/WP2, and keeps to its own line ranges.What changed
docs/source/quick_start.rstpress it straight in for SQUARE. A
.. note::covers v3/v2.5's four separate arrow buttons.Key names are unchanged, so the rest of the manual stands as written and there is no
"press RIGHT (or push the joystick right)" anywhere.
anything: the directional control (one joystick vs four arrow buttons — the fastest tell, led
with), the screen (1.91"/176×176 vs 1.5"/128×128), and the externally accessible spring-loaded SD
slot. Closes with the differences that follow from the revision. Labelled so other pages
:ref:to it.
described as a physical question about where the screen faces; AS Bloom and AS Heart are
called out as the exceptions — they name an Analog Sky telescope that can be ordered with a fully
integrated PiFinder, not an orientation. The v3/v2.5 entries (Left, Right, Straight, Flat v3,
Flat v2) move into a
.. note::. The stale opening line "(Right/Left/Straight/Flat)" is gone.limit in a note. No engineering figures; those stay in ADR 0023.
docs/source/user_guide.rstcentre press to SQUARE, with the v3/v2.5 layout in a note. The duplicated key list itself is
byte-identical to the Quick Start's, as its comment requires.
docs/source/index.rst,docs/source/troubleshooting.rstScreenshots
All captured at 176 px and run through
screenshot_to_doc.py --scale 2(→ 352×352), except the onethat is deliberately 128 px because it is illustrating v3/v2.5 hardware.
Re-taken in the sections this PR edits (D3 rule 3):
pifinder_type_select.png— now shows the five rev4 entries the new prose describes: AS Bloom,AS Heart, Rev4 Left (highlighted), Rev4 Right, Rev4 Straight.
settings_menu_config.png— this one was stale as well as small: it showed PiFinder Typesitting directly in the Settings menu, while the surrounding prose has long said
Settings → Advanced → PiFinder Type. It is now the Advanced menu, so image and text agree.
settings_select.png— re-taken, composition unchanged.New, for "Which PiFinder do I have?":
main_menu_rev4_docs.png(352×352) andmain_menu_v3_docs.png(256×256) — the same mainmenu on each panel, side by side in a
list-table. The rev4 capture also carries the title-barbattery icon, captured with
-fb.The screen paragraph describes what those two captures actually show. An earlier draft claimed
rev4 "shows nine menu rows and v3 shows seven" from
Layout176.menu_visible_items; driving the realUI showed no menu displays that many, so the claim was dropped rather than shipped.
Sphinx build
Clean.
sphinx-build -b html -n -Eagainst an empty build directory (full rebuild, nitpicky,fresh environment — an incremental build can hide "undefined label" on documents Sphinx decides not
to re-read, which is exactly the risk when adding a new label): zero warnings, zero errors,
matching the verified baseline. All four
:ref:s toquick_start:which pifinder do i have?resolve.Note for other agents: in a worktree-isolated session the Bash tool refuses any command containing
the substring
source, so the plan's build command is rejected outright.docs/sourc[e]works.TODO(rich) markers left in the docs
Three, all rST comments (they do not render), each flagging a photo only Rich can shoot:
quick_start.rstUnboxing —pf_front.jpeg/pf_rear.jpegboth show a v3 unit and neither hasa joystick; rev4 front and rear shots wanted alongside them.
quick_start.rst"Which PiFinder do I have?" — one photo of a v3 and a rev4 side by side, screenslit, would answer the whole section at a glance (plan §6 Beta #7). The section now carries a
screen-capture comparison, but a photo would also show the joystick and the case.
quick_start.rstConfiguration Setup — pictures of Rev4 Left / Right / Straight and of the ASBloom and AS Heart units (plan §6 #8–#10). These are menu options an owner must self-identify and
there is currently no picture of any of them.
The prose in each of those places is written to stand on its own without the image.
Photos needed (plan §6)
Blocking for WP3: #4 rev4 front (joystick visible), #5 rev4 rear, #6 annotated rev4
keypad close-up, #7 rev3 next to rev4 with screens lit, #8 Rev4 Left/Right/Straight,
#9 AS Bloom, #10 AS Heart.
Also worth noting, outside the strict WP3 list: the Quick Start's opening hero image
(
v3_slate_family_front.jpeg) is a v3 family shot, andindex.rst's banner isPiFinder_v3_banner.png(plan §6 #12).Plan open questions
#7 (what "AS" means) is resolved and reflected in the prose: "AS" is Analog Sky, and
AS Bloom/AS Heartare customer-facing names an owner of those telescopes will recognise.#6, #8 and #9 were resolved mid-PR by Rich. Their substance belongs to other files and other
agents, so nothing here writes them up: the camera modules are unchanged on rev4 (no caveat
needed anywhere, so none was added); the GPS receiver change lands in
menu_map.rst(WP2); theexternally accessible SD slot lands in
sd_card.rst(separate agent). The one place it touchesthis PR is "Which PiFinder do I have?", where the spring-loaded side slot is listed as a third
externally visible tell — visible difference only, no card-swap procedure. No
TODO(rich)for anyof the three exists in the docs; the three markers below are all photo requests.
Consistency with
menu_map.rst(WP2's file — not touched here)menu_map.rst:264-266lists the PiFinder Type values as Left, Right, Straight, Flat v3, Flat v2, ASBloom, AS Heart, Rev4 Left, Rev4 Right, Rev4 Straight. That matches
menu_structure.py:1006-1047exactly, in the same order, and matches this PR. No inconsistency found. One optional suggestion
for WP2:
menu_map.rstsays which values exist but not how to choose between them, so a:ref:quick_start:configuration setup`` from that entry would now land somewhere useful.Not done
quick_start.rst) was listed in the WP3 file ranges but needed no prosechange — the joystick is introduced one section earlier in Unboxing, and every key instruction in
it is already correct on both revisions. Its seven screenshots were therefore left at 128 px:
under D3 rule 3 they only get re-taken as a side effect of editing that section, and the guardrail
is explicit about not wandering into sections you aren't otherwise touching. Say the word and
they're a five-minute follow-up.
screen image, so none was added.